What is a Sale?

A sale is a transaction between two or more parties that involves the exchange of tangible or intangible goods, services, or other assets for money. In some cases, assets other than cash are paid to a seller.

In the case of the MPOS Companion API implementation the Sale transaction refers to the customer paying the goods or services received by means of tapping or inserting their bank card into the payment device.

The sale transaction is also used for purchase with cash (part of the sale is cash) and cashback (the entire sale amount is cash.)

The Sale request allows MPOS Applications to integrate card processing into their applications. To process a card payment the MPOS App must launch the Ecentric Payment App via an Android Intent call, to process the response intent data, in order to understand if the transaction succeeded of failed.

🚧
Note:
An auth token must exist before a payment can be requested.
Please refer to section Retail Auth Validation

How Does a Sale Work?

The diagram below displays an example of how a Sale works by making use of the Companion App (Here after known as the MPOS App), Payment App (Here after known as the Ecentric's Payment App), Transaction Processor (Here after known as the Ecentric Server) and Acquirer.

Sale transaction flow — Sale Transaction Flow

Process Description:

Step 1:

When a sale transaction is initiated on the MPOS App, the first step before processing the transaction, is to check if an authentication token is available in the request.

If there is an auth token available, then the transaction will continue as per normal.
If there is no auth token available, then the MPOS App will need to do a RETAIL_AUTH request in order to obtain a valid auth token, before a SALE transaction can be requested.

Step 2:

The MPOS App will initiate a SALE request, the SALE request will be sent to the Ecentric Payment App.

Step 3:

The Ecentric Payment App will process the card details and forward the SALE request to Ecentric's Server.

Step 4:

The Ecentric Server will validate the auth token in the request.

NOTE: If the auth token is not validated, the Ecentric Server will return an "invalid auth token" error to the Ecentric Payment App, and the transaction will be aborted.

Step 5:

The Ecentric Server will send a financial message to the Acquirer.

Step 6:

The Acquirer will the perform the necessary checks in order to validate and process the transaction.
Once the validation of the transaction has been performed, the Acquirer will respond with a financial message to the Ecentric Server, which contains the transaction outcome.

Step 7:

The Ecentric Server will return the transaction response to the Ecentric Payment App.

Step 8:

The Ecentric Payment App will then forward the transaction outcome to the MPOS App.

Step 9:

The MPOS App will be able to display the transaction outcome to the customer.

Sale Transaction Tutorial Video

Request

Sample Bundle: Sale

The following is an example of a SALE request for R10.00

"launchType": "SALE"	
"merchantID": "770000000000123"
"authenticationKey": "e27b5ce6-8ba6-4746-9453-536728f7cbeb"
"transactionAmount": 1000

Sample Bundle: Purchase with Cash

The following is an example of a Purchase request for R10.00 and a Cash amount of R50.00

"launchType": "SALE"	
"merchantID": "770000000000123"
"authenticationKey": "e27b5ce6-8ba6-4746-9453-536728f7cbeb"
"transactionAmount": 6000 // The entire amount in cents
"cashAmount": 5000 // the cash amount in cents

Sample Bundle: Cashback

The following is an example of a Cashback request for R50.00

"launchType": "SALE"	
"merchantID": "770000000000123"
"authenticationKey": "e27b5ce6-8ba6-4746-9453-536728f7cbeb"
"transactionAmount": 5000 // The entire amount in cents
"cashAmount": 5000 // The cash amount in cents

Parameters

📘
Note
When values are submitted in the request which exceed the maximum length, the intent request is halted, and the appropriate message is handed back to the MPOS application.

The following table describes the parameters of the SALE request message.

PARAMETERS	TYPE	DESCRIPTION	EXAMPLE
REQUIRED
launchType	STRING	Must be“SALE” Used for launching the Ecentric Payment App to process a payment.	SALE
merchantID	STRING	The merchant ID assigned to the merchant. The merchant ID will always be the same ID for a specific merchant. To be provided by Ecentric.	910100000000001
authenticationKey	STRING	The authentication token that was generated by the server on a successful retail auth call to the Ecentric Payment App.	e27b5456-8bff6-4746-94bg-367253356eb
transactionAmount	LONG	The full transaction amount to be charged in cents. This amount will include a cashAmount if it was specified.	1000
OPTIONAL
merchantName	STRING ALPHANUMERIC WITH SPACES	The name of the merchant that requested the transaction, as stored at the bank.	Merchant A
cashAmount	LONG	The amount of cash that was withdrawn in cents. The cashAmount will be included in the transacionAmount.	500
transactionDescription	STRING ALPHANUMERIC WITH SPACES	Reference description for the merchant’s records.	3rd party app desc
transactionReferenceNumber	STRING ALPHANUMERIC	Reference number field that also appears in a merchant portal when available.	ref#123456
cellNumberToSMSReceipt	STRING NUMERIC	10-digit cell phone number for receipt SMS destination. Can be blank. NOTE: If isReceiptRequired is true then this is a mandatory field.	0721234567
emailAddressToSendReceipt	ALPHANUMERIC	Valid email address for receipt email destination. Can be blank. NOTE: If isReceiptRequired is true then this is a mandatory field.	[email protected]
isReceiptRequired	BOOLEAN	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	true
alwaysShowTransactionStatusScreen	BOOLEAN	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.	true
externalSTAN	STRING NUMERIC	A systems trace number generated by some 3rd party ERP systems.	123456
externalRRN	STRING ALPHANUMERIC	A RRN generated by some 3rd party ERP systems.	ABCDEF123456
externalTransactionGUID	STRING ALPHANUMERIC	A GUID that identifies a specific transaction generated by 3rd party ERP systems.	2fdca02f-3cbe-4e8c-82ad-86a1a16b72e8
externalInvoiceGUID	STRING ALPHANUMERIC	A GUID that identifies a particular invoice that may appear on more than one transaction.	2fdca02f-3cbe-4e8c-82ad-86a1a16b72e9
transactionUuid	STRING ALPHANUMERIC	Unique ID of transaction	bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc
externalTransactionDateTime	STRING	A date and time the transaction was generated on the 3rd party ERP systems. Has the format of “yyyy-MM-dd'T'HH:mm:ss”	2017-04-28T09:30:00
externalTerminalId	STRING NUMERIC	A terminal identifier for device configured on the 3rd party ERP system.	98100010
latitude	STRING NUMERIC	A geolocation identifier indicating the latitude position of the device.	-28.1619942
longitude	STRING NUMERIC	A geolocation identifier indicating the longitude position of the device.	30.2350981
accuracy	STRING NUMERIC	A accuracy indicator of the geolocation.
additionalData	OBJECT	See Additional Parameters section for the AdditionalData Object.	N/A

Additional Parameters

📘
Note

The 'additionalData' object allows the MPOS App to pass data fields of any type to the server.

This 'additionalData' object is NOT interrogated or used by the Ecentric Payment App itself, but only passes the object through to the server.

AdditionalData Object

The following tables describes the additional parameters of the SALE request message, based on the preference of the merchant.

📘
Note

All fields including a (*) are required parameters for PayFac clients.

All fields not marked are optional for all merchants based on the merchants preference.

PARAMETERS	TYPE	SIZE(MAX)	DESCRIPTION	EXAMPLE
Tokenization	OBJECT	N/A	See parameters under Tokenization Object. example included in code Sample Code SALE Request	N/A
extendedTrxType	NUMERIC STRING	12	The unique 4 digit number configured on Postilion switch, which 3rd party integrators can use to route transactions to a different acquirer. Provided by Ecentric. example included in code Sample Code SALE Request	1234
(*) subMid	NUMERIC STRING	15	The unique ID for each sub merchant. Determined by the PayFac. example included in code Sample Code SALE Request	574595612358745

Tokenization Object

PARAMETERS	TYPE	SIZE(MAX)	DESCRIPTION	EXAMPLE
MerchantUserID	NUMERIC STRING	16	Creates the ability to tokenize a customer card, in order for a PSP to perform subsequent transaction on the terminal as another means of securing customer information during transaction processing.	1

Sample Code

The following code needs to be implemented by the MPOS Application in order to invoke the Ecentric Payment App to initiate a SALE request message.

*See Sample Code SALE Response for the intentLauncher function

private void doSale() {
    Intent intent = new Intent();
   	intent.setClassName("com.ecentric.ecentricpay", "com.ecentric.ecentricpay.MainActivity");
    Bundle dataBundle = new Bundle();
    dataBundle.putString("launchType", "SALE");
  	dataBundle.putString("merchantID", "910100000000001")
    dataBundle.putString("authenticationKey", "received_authenticationKey");
    dataBundle.putLong("transactionAmount", 1000); // amount in cents
  
		JSONObject additionalData = new JSONObject();
		try {
      // Add subMid field
			additionalData.put("subMid", "574595612358745");
      
      // Add extendedTrxType
			additionalData.put("extendedTrxType", "6705");
                                          
      // Create a Tokenization object
 			JSONObject tokenization = new JSONObject();
			tokenization.put("MerchantUserID", "1");
			additionalData.put("Tokenization", tokenization);
	 
			dataBundle.putString("additionalData", additionalData.toString());
		} catch (JSONException e) {
			e.printStackTrace();
		}

    intent.putExtra("ecentricBundle", dataBundle);
    try {
        intentLauncher.launch(intent);
    } catch (Exception e) {
        Log.e(TAG, "Error launching intent: " + e);
    }

Response

📘
Note
Result of the transaction:

The resultCode will indicate the result of the sale request:
01 -> Successful
02 -> Declined
03 -> Aborted
04 -> Error

Receipt Bundle:

In the event that the Integrator would like to manage the receipt for the customer, the receipt bundle is sent back along with the Sale Response.

The Integrator may decide which fields they would like to display on the receipt but must take into account the mandatory which must be printed according to the L3 rules.

Mandatory Receipt Printing Fields

MERCHANT_NAME

Hashed merchantID (*Note that the full merchantID is sent back in the receipt bundle and it is the merchant's responsibility to HASH the merchantID before printing on the receipt.)

RC

STATUS

RRN

APP_LABEL

AID

TERMINAL_ID

PAN_WITH_BIN

transactionUuid

DATE

FORMATTED AMOUNT

📘
Note:
The following is only applicable for Gift Cards.
Within the Receipt Data two additional fields will be sent in the response:

AVAILABLE_BALANCE_CENTS AND AVAILABLE_BALANCE_FORMATTED: Shows completed transactions (i.e. where the advice message has been sent for that day’s deposits).

Reflects the total amount available on the card, excluding any newly deposited funds

CURRENT_BALANCE_CENTS AND CURRENT_BALANCE_FORMATTED: Shows the completed + incomplete transaction values (what the balance will be once the advice messages have been sent).

Reflects the total amount available on the card, including any newly deposited funds

Sample Bundle

The following is an example of a SALE response bundle the MPOS Application will receive.

"resultDescription": "APPROVED",
"buildInfo": "Ecentric",
"isReceiptDataAvailable": true,
"resultCode": "01",
"receiptBundle": {
    "MERCHANT_REGION_CODE": "09",
    "RC_ALT": "00",
    "CASH_AMOUNT_CENTS": "0",
    "SEQ_NO": "000",
    "STATUS": "APPROVED",
    "BUDGET_PERIOD": "0",
    "CARD_TYPE": "",
    "PAN_WITH_BIN": "445143******2309",
    "MERCHANT_ID": "770000000000123",
    "TIMESTAMP": "1745476020950",
    "EXTERNAL_TRANSACTION_DATETIME": "",
    "PROCESSING_CODE": "0",
    "RC_DESCRIPTION": "Approved",
   	"EXTERNAL_INVOICE_GUID": "",
 		"CURRENT_BALANCE_CENTS" = "705000",
    "REPLACEMENT_MERCHANT_ID": "",
   	"BATCH_NO": "000",
		"AVAILABLE_BALANCE_FORMATTED" = "R 7000.00"
    "AUTH_PROFILE": "0",
    "INTERCHANGE": "null",
    "ESC_BY_AUTH_CODE": "226 00 IH 15882",
    "TX_TYPE": "0",
    "ACC_TYPE_DESC": "Default",
   	"TIP_AMOUNT": "",
		"AVAILABLE_BALANCE_CENTS" = "700000",
    "CURRENCY_CODE": "0710",
    "AUTH_CODE": "15882",
    "RC": "00",
    "AID": "A0000000031010",
    "ATC": "055D",
    "CRY": "13A531FAFC4D29F6",
    "CVM": "none",
    "IAD": "06010A03A04000",
    "PAN": "************2309",
    "RRN": "511427060006",
    "TSI": "0000",
    "TVR": "0000000000",
    "APSN": "",
    "DATE": "2025-04-24T06:27:06.749+0000",
    "STAN": "",
    "NAME_ON_CARD": "UnknownCardholderName",
    "AMOUNT_CENTS": "1000",
    "ABS_AMOUNT": "10.00",
    "TOKEN": "",
    "RECEIPT_NUMBER": "",
    "EXTENDED_TRX_TYPE": "",
    "TERMINAL_ID": "77012398",
    "TX_TYPE_DESCRIPTION": "SALE",
    "EXTERNAL_TERMINAL_ID": "",
    "FORMATTED_AMOUNT": "R 10.00",
    "DESCRIPTION": "511427060006",
    "BATCH_NUMBER": "0",
    "SETTLEMENT_DATE": "",
   	"SURCHARGE_AMOUNT": "0.00",
 		"CURRENT_BALANCE_FORMATTED" = "R 7050.00",
    "EXTERNAL_TRANSACTION_GUID": "",
    "CARD_BIN": "445143",
    "TRANSACTION_INFO": "22600IH15882",
    "REPLACEMENT_TERMINAL_ID": "",
    "POS_ENTRY": "701",
    "RC_ISO_DESCRIPTION": "Approved or completed successfully",
    "APPLICATION_LABEL": "VISA SAVINGS",
    "MERCHANT_CITY": "Cape Town",
    "MERCHANT_NAME": "Istore",
    "CUSTOMER_NAME": "",
    "APP_VERSION": "",
    "CARD_SEQ_NO": "0",
    "APP_LABEL": "VISA SAVINGS",
    "INVOICE_NUM": "",
    "MESSAGE_1": "",
    "MESSAGE_2": "",
    "CARD_TRANSACTION_TYPE": "CONTACTLESS",
    "FORMATTED_CASH_AMOUNT": "R 0.00",
    "CASH_AMOUNT": "0.00",
    "RESULT_CODE": "00",
    "MERCHANT_COUNTRY_CODE": "ZA",
    "REPRINT": "false",
    "PAN_HASH": "3f5c9f528a4bfa5d5e4137824d0b08491b5bc30b062ad778a818770f10771019",
    "AMOUNT": "10.00",
    "TIP_LABEL": "",
    "DIGITS": "2309",
    "CVM_ABSA": ""
 },
"merchantID": "770000000000123",
"serialNumber": "PC05P2CG10036",
"isApproved": "true",
"launchType": "SALE",
"cashAmount": "0",
"transactionUuid": "bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc",
"appVersion": "1.9.2",
"transactionAmount": "1000"

Parameters

The following table describes the parameters of the SALE response message.

*Note: If additional data was added to the sale request, those parameters will also be returned in the response.

PARAMETERS	TYPE	DESCRIPTION	EXAMPLE
launchType	STRING	Echo of the launchType used to launch the Ecentric Payment App.	SALE
resultCode	STRING	Represents the result status of the intent call to the Ecentric Payment App ● 00: COMPLETED ● 01: SUCCESSFUL ● 02: DECLINED ● 03: ABORTED ● 04: ERROR	00
resultDescription	STRING	A user readable representation of the above resultCode i.e. Approved for resultCode 01. If the bank or switch approves or declines the transaction, the response description is included in this field.	APPROVED
merchantID	STRING	Echo of the merchantID used in the request.	910100000000001
merchantName	STRING	The name of the merchant that requested the transaction as stored at the bank.	Merchant A
transactionAmount	STRING	Approved total transactionAmount.	1000
cashAmount	STRING	Approved cashAmount.	500
transactionDescription	STRING	Echo of the transactionDescription used to launch the Ecentric Payment App.	3rd party app desc
isReceiptDataAvailable	STRING	Boolean indicating whether a receiptBundle object is available. Will always be included for approved or declined transactions.	true
receiptBundle	STRING	Consists of a sub-bundle of server parameters that can be used by the partner application to create a receipt.	See Sample ecentricBundle SALE Response.
appVersion	STRING	The software version currently running on the Ecentric Payment App.	1.9.2
externalSTAN	STRING	Echo of the systems trace number generated by some 3rd party ERP systems.	123456
externalRRN	STRING	Echo of the RRN generated by some 3rd party ERP systems.	ABCDEF123456
externalTransactionGUID	STRING	Echo of the GUID that identifies a specific transaction generated by 3rd party ERP systems.	2fdca02f-3cbe-4e8c-82ad-86a1a16b72e8
externalInvoiceGUID	STRING	Echo of the GUID that identifies a particular invoice that may appear on more than one transaction.	2fdca02f-3cbe-4e8c-82ad-86a1a16b72e9
externalTransactionDateTime	STRING	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”	2017-04-28T09:30:00
externalTerminalId	STRING	Echo of the terminal identifier for device configured on the 3rd party ERP system.	98100010
transactionUuid	STRING	Echo of the Unique ID of a transaction.	bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc
terminalId	STRING	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.	77012398
latitude	STRING	Echo of geolocation identifier indicating the latitude position of the device.	-28.1619942
longitude	STRING	Echo of geolocation identifier indicating the longitude position of the device.	30.2350981
accuracy	STRING	Echo of accuracy indicator of the geolocation.
serialNumber	STRING	The serial number for the device that was used for the RETAIL_AUTH intent call.	PC05P2CG10036

Sample Code

The following code needs to be implemented by the MPOS Application to decode the SALE transaction outcome and resume the MPOS App flow accordingly.

When the response is returned the calling app needs to override the onActivityResult() method and can be done as follows:

private final ActivityResultLauncher<Intent> intentLauncher = registerForActivityResult(
       new ActivityResultContracts.StartActivityForResult(),
       result -> {
           if (result.getResultCode() == Activity.RESULT_OK) {
               Intent data = result.getData();
               if (data != null) {
                   Bundle responseBundle = new Bundle(data.getBundleExtra("ecentricApplicationResponse"));
                   String launchType = responseBundle.getString("launchType");
                   String resultCode = responseBundle.getString("resultCode");
                 		// Determine if the transaction was successfully executed using returned resultCode
                   Boolean success = false;
                   if (resultCode != null && (resultCode.matches("00") || resultCode.matches("01"))) {
                       success = true;
                   }

                   if (responseBundle.get("errorBundle") != null) {
                       Bundle errorBundle = new Bundle(responseBundle.getBundle("errorBundle"));
                   }
               }
           } else {
               Log.e(TAG, "Received error resultCode: " + result.getResultCode());
           }
       }
);

Error Handling

The following table contains typical errors that might occur and how to handle these errors:

ERROR MESSAGE	SOLUTION
Incorrect merchantID	Ensure that you have entered the correct merchantID.
authenticationKey is invalid	When your authenticationKey is invalid, you will receive an error message indicating that the authenticationKey is invalid, a RETAIL_AUTH request needs to be done to obtain a valid authenticationKey.
transactionAmount not present	Ensure that you are sending through a valid transactionAmount.
Duplicate UUID	Ensure that a unique UUID is sent through for every new sale transaction.

Sample Bundle

The following is an example of a SALE ERROR response bundle that the MPOS Application will receive.

"resultDescription": "ABORTED",
"errorBundle": {
    "description": "ERROR",
    "reference": "",
    "errorType": "TRANSACTION",
    "message": "Transaction cancelled by user"
  },
 "buildInfo": "Ecentric_DEBUG_Ecentric_INT",
 "isReceiptDataAvailable": false,
 "resultCode": "03",
 "merchantID": "910100000000001",
 "serialNumber": "PC05P2CG10036",
 "launchType": "SALE",
 "cashAmount": "0",
 "appVersion": "1.9.8",
 "transactionAmount": "1000"