Description
The Sale function is used to invoke the payment app in order to take payment for the goods or services provided to customers.
Sale Request
Parameters
The following table(s) describes the parameters of the Sale request message:
| Parameter | Description |
|---|---|
| launchType | Must be “SALE” (however “PAYMENT” is still supported) Used for launching the Ecentric Payment app to process a payment. |
| applicationKey | The 3rd party API key that will be issued by Ecentric specific for every 3rd party application |
| authenticationKey | The authentication token that was generated by the server on a successful login to the Ecentric Payment app |
| merchantUsername | The specific user name that with the appropriate role to transact via a Companion app with the Ecentric Payment app |
| merchantName | The name of the merchant that requested the transaction as stored at the bank |
| customerName | The name of the customer that will be making payment using the Ecentric Payment app |
| transactionAmount | The amount to be charged in cents (long) |
| transactionDescription | Reference number for the merchant’s records |
| transactionReferenceNumber | Reference number field that also appears in a merchant portal when available. |
| cellNumberToSMSReceipt | 10-digit cell phone number for receipt SMS destination. Can be blank. NOTE: If isReceiptRequired is true then this is a mandatory field. |
| emailAddressToSendReceipt | Valid email address for receipt email destination. Can be blank. NOTE: If isReceiptRequired is true then this is a mandatory field. |
| isReceiptRequired | If set to true, at least one of the receipt parameters above needs to be set. If set to false the user will not be prompted to send a receipt after payment using the Ecentric Payment app. NOTE: According to VISA and Mastercard requirements, this must always be set to true unless the app developer is providing an alternative means to send a receipt |
| alwaysShowTransactionStatusScreen | Once the Ecentric Payment app has processed a transaction there is a status screen that shows the success/failure of processing. Set this flag to true if you would like this displayed otherwise false to hide it. Default is false. |
| deviceIMEI | The IMEI number of the Payment Blade. This is absent when using a SUNMI. |
| externalSTAN | An optional systems trace number generated by some 3rd party ERP systems |
| externalRRN | An optional RRN generated by some 3rd party ERP systems |
| externalTransactionGUID | An optional GUID that identifies a specific transaction generated by 3rd party ERP systems |
| externalInvoiceGUID | An optional GUID that identifies a particular invoice that may appear on more than one transaction |
| externalTransactionDateTime | An optional date and time the transaction was generated on the 3rd party ERP systems. Has the format of “yyyy-MM-dd'T'HH:mm:ss” |
| externalTerminalId | An optional terminal identifier for device configured on the 3rd party ERP system |
| latitude | An optional geolocation identifier indicating the latitude position of the device |
| longitude | An optional geolocation identifier indicating the longitude position of the device |
| accuracy | An optional accuracy indicator of the geolocation |
| transactionUuid | Unique ID provided from 3rd party integrators. Format: UUID version 4 Note: If the field was not populated by the 3rd party integrator a system generated transaction UUID will be assign for every new transaction. |
| Parameter | Characteristics | Error message when exceeded |
|---|---|---|
| transactionAmount | Maximum numeric only value is 9,999,999.99 | Transaction Amount is not valid |
| transactionReferenceNumber | Maximum of 12 alphanumeric characters | Invoice Number is too long, must be a maximum of 12 in length |
| transactionDescription | Maximum of 30 alphanumeric characters | Transaction Description is too long, must be a maximum of 30 in length |
| customerName | Maximum of 40 alphanumeric characters | Customer Name is too long, must be a maximum of 40 in length |
| emailAddressToSendReceipt | Maximum of 50 alphanumeric characters | Email address is too long, must be a maximum of 50 in length |
| cellNumberToSMSReceipt | Maximum of 10 numeric characters | A valid South African mobile number must be supplied for mobile receipting |
| Parameter | Character Limit |
|---|---|
| DESCRIPTION_LENGTH | 30 |
| CUSTOMER_NAME_LENGTH | 40 |
| INVOICE_NUMBER_LENGTH | 12 |
| EMAIL_LENGTH | 50 |
| SMS_LENGTH | 15 |
| EXTERNAL_STAN_LENGTH | 6 |
| EXTERNAL_RRN_LENGTH | 12 |
| EXTERNAL_TERMINAL_ID_LENGTH | 8 |
| REFERENCE_NO_LENGTH | 10 |
Sample Request Code
private String appURL = "payment.thumbzup.com";
private String appClass = "payment.thumbzup.com.IntentActivity";
Intent intent = new Intent();
intent.setClassName(appURL, appClass);
Bundle dataBundle = new Bundle();
dataBundle.putString("launchType", "SALE");
dataBundle.putString("merchantID", "910100000000001"); //provided by the onboarding team
dataBundle.putString("authenticationKey", "c282cdd3-59d2-42ff-8c96-826725a27e6e");
// in cents
dataBundle.putLong("transactionAmount", 10000);
// UUID Version 4
dataBundle.putString("transactionUuid", " 491321f4-c900-40a0-b5fa-4d8c0d7a91b7");
/*
The 'additionalData' object allows the 3rd party application to pass data fields
of any type to the server.
This 'additionalData' object is NOT interrogated or used by the Payment app itself,
but only passes the object through to the server.
Below shows examples of how the 'additionalData' field can be used to pass a
'merchantInfo' object and a 'subMid' field to the server.
*/
JSONObject additionalData = new JSONObject();
try {
// The 'merchantInfo' object is a Mastercard requirement for all transactions
JSONObject merchantInfo = new JSONObject();
merchantInfo.put("Phone_No", "0114567891");
merchantInfo.put("Street", "cnr Von Willich Ave &, Leonie St);
merchantInfo.put("URL", "www.merchantwebsite.com");
merchantInfo.put("Support_Phone_No", "0114567891";
merchantInfo.put("City", "Johannesburg");
merchantInfo.put("Province", "Gauteng");
merchantInfo.put("Country_Code", "ZA");
merchantInfo.put("Currency_Code", "710");
merchantInfo.put("Postal_Code", "0157");
additionalData.put("Merchant_Info", merchantInfo);
// AN6022 requires a Sub Merchant ID field to be included.
additionalData.put("subMid", "574595612358745");
// Add the above to the intent bundle
dataBundle.putString("additionalData", additionalData.toString());
} catch (JSONException e) {
e.printStackTrace();
}
intent.putExtra("thumbzupBundle", dataBundle);
startActivityForResult(intent, 0);
Sale Response
Parameters
| Parameter | Description |
|---|---|
| launchType | Echo of the launchType used to launch the Ecentric Payment app. |
| isApproved | Represents the processing result from a card perspective of the transaction. This will indicate whether the payment will occur or not. Valid values are: ● true – card payment will be made by the issuer ● false – card payment failed due to for example invalid PIN ● error – card payment failed due to an unknown error |
| resultCode | Represents the result status of the intent call to the Ecentric Payment app (NOTE: to determine if payment will occur then please use the isApproved field as a definitive answer): ● 01 – transaction successful ● 02 – transaction declined ● 03 – transaction aborted ● 04 – error This is not a result code from the bank or switch and should not be made available to the customer at any time. For the Issuer/Acquirer response code, see field RC in the receiptBundle (see 3.6 Additional Server Fields). |
| resultDescription | A user readable representation of the above resultCode i.e. Approved for 01 resultCode If the bank or switch approves or declines the transaction, the response description is included in this field |
| merchantName | The name of the merchant that requested the transaction as stored at the bank |
| customerName | Echo of the customerName used to launch the Ecentric Payment app |
| authenticationKey | The authentication token that was generated by the server on a successful login to the Ecentric Payment app |
| transactionAmount | Echo of the transactionAmount used to launch the Ecentric Payment app |
| transactionDescription | Echo of the transactionDescription used to launch the Ecentric Payment app |
| transactionUuid | Unique ID provided from 3rd party integrators. Format: UUID version 4 Note: If the field was not populated by the 3rd party integrator a system generated transaction UUID will be assign for every new transaction. |
| cellNumberToSMSReceipt | Masked out value of the cell number used to send the receipt to e.g. * * * **657 |
| emailAddressToSendReceipt | Masked out value of the email address used to send the receipt to e.g. * * * * *@ecentric.com |
| isReceiptRequired | Echo of the isReceiptRequired used to launch the Ecentric Payment app |
| isReceiptDataAvailable | A boolean indicating whether a receiptBundle parameter is available. Will always be there for accepted or declined transactions. |
| receiptBundle | Consists of a sub-bundle of server parameters that can be used by the partner application. For a full list of these parameters see the Additional Server Fields section |
| pebbleFirmwareVersion | The software version currently running on the Payment Pebble® |
| pebbleSerialNumber | The serial number of the Payment Pebble® |
| appVersion | The software version currently running on the Ecentric Payment app |
| externalSTAN | Echo of the systems trace number generated by some 3rd party ERP systems |
| externalRRN | Echo of the RRN generated by some 3rd party ERP systems |
| externalTransactionGUID | Echo of the GUID that identifies a specific transaction generated by 3rd party ERP systems |
| externalInvoiceGUID | Echo of the GUID that identifies a particular invoice that may appear on more than one transaction |
| externalTransactionDateTime | Echo of the date and time the transaction was generated on the 3rd party ERP systems. Has the format of “yyyy-MM-dd'T'HH:mm:ss” |
| externalTerminalId | Echo of the terminal identifier for device configured on the 3rd party ERP system |
| terminalId | This is an automatically system-assigned terminalID of the payment terminal’s identity number, which can be used to assist with settlement information and is returned in BASE36 format |
| latitude | Echo of geolocation identifier indicating the latitude position of the device |
| longitude | Echo of geolocation identifier indicating the longitude position of the device |
| accuracy | Echo of accuracy indicator of the geolocation |
Sample Code
@Override
protected void onActivityResult(int requestCode, int resCode, Intent data) {
String result = "";
Bundle b = new Bundle(data.getBundleExtra("thumbzupApplicationResponse"));
if(resCode == Activity.RESULT_OK) {
// handle ok result
String launchType = b.getString("launchType");
String isApproved = b.getString("isApproved"); // final result of sale
String resultCode = b.getString("resultCode");
String authenticationKey = b.getString("authenticationKey");
String resultDescription = b.getString("resultDescription"); // bank response
String merchantName = b.getString("merchantName");
String customerName = b.getString("customerName");
Long transactionAmount = b.getLong("transactionAmount");
String transactionDescription = b.getString("transactionDescription");
String transactionUuid = b.getString("transactionUuid");
String cellNumberToSMSReceipt = b.getString("cellNumberToSMSReceipt");
String emailAddressToSendReceipt = b.getString("emailAddressToSendReceipt");
boolean isReceiptRequired = b.getBoolean("isReceiptRequired");
boolean isReceiptDataAvailable = b.getBoolean("isReceiptDataAvailable");
String externalSTAN = b.getInt("externalSTAN");
String externalRRN = b.getString("externalRRN");
String externalTransactionGUID = b.getString("externalTransactionGUID");
String externalInvoiceGUID = b.getString("externalInvoiceGUID");
String externalTransactionDateTime = b.getString("externalTransactionDateTime");
String externalTerminalId = b.getString("externalTerminalId");
String latitude = b.getString("latitude");
String longitude = b.getString("longitude");
String accuracy = b.getString("accuracy");
if (isReceiptDataAvailable) {
// this represents extra data from card processing backend
Bundle receiptBundle = b.getBundle("receiptBundle");
Iterator it = receiptBundle.keySet().iterator();
while (it.hasNext()) {
// go through extra data
Object key = it.next();
Object val = receiptBundle.get(key.toString());
}
}
}
}