QR Code Transaction
Note:QR Code Transactions are currently only available for Payflex
What is a QR Code Transaction?
QR Code Payments enable customers to complete transactions by scanning a QR code using a mobile wallet or payment app. The QR code contains key transaction details such as the merchant identifier, transaction amount, currency, and reference number. The platform supports dynamic QR codes (generated per transaction with real-time data). This payment method offers a fast, secure, and contactless experience. When initiating a QR code payment, the API response will return the encoded QR code data (as string text) for display to the customer.
The QR code payment request allows MPOS Applications to integrate QR code payment processing into their applications. To process a QR code 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 QR Code Transaction Work?
Process Description:
Step 1:
When a QR code 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_AUTHrequest in order to obtain a valid auth token, before aQR_CODE_PAYMENTtransaction can be requested.
Step 2:
The MPOS App will initiate a QR_CODE_PAYMENT request and the QR_CODE_PAYMENT request will be sent to the Ecentric Payment App.
Step 3:
The Ecentric Payment App will forward the QR_CODE_PAYMENT 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 generate a QR code payload and send the payload back to the Ecentric Payment App, in order for the terminal to display the QR code.
Step 6:
The Ecentric Payment App will display the QR code for a user to scan, and send a TRANSACTION AUTHORIZATION message to the Ecentric Server.
Step 7:
The Ecentric Server will forward the TRANSACTION AUTHORIZATION message to OMNI.
Step 8:
OMNI will the perform the necessary checks in order to validate and process the transaction.
Once the validation of the transaction has been performed, and OMNI receives a success response from the QR provider, OMNI will respond to the Ecentric Server, which contains the TRANSACTION AUTHORIZATION response.
Step 9:
The Ecentric Server will return the TRANSACTION AUTHORIZATION response to the Ecentric Payment App.
Step 10:
The Ecentric Payment App will then remove the QR code from the display, and if the transaction has not been cancelled or aborted from the MPOS or by the User, will send a TRANSACTION CONFIRMATION message to the Ecentric Server.
Step 11:
The Ecentric Server will return the TRANSACTION CONFIRMATION response to the Ecentric Payment App.
Step 12:
The Ecentric Payment App will then forward the transaction outcome to the MPOS App.
The MPOS App will be able to display the transaction outcome to the customer.
Step 13:
The Ecentric Server will forward the TRANSACTION CONFIRMATION message to OMNI.
Step 14:
OMNI will the process the confirmation and forward to the QR provider.
Request
Sample Bundle
The following is an example of a QR_CODE_PAYMENT request
"launchType": "QR_CODE_PAYMENT"
"merchantID": "770000000000123"
"transactionUuid": "bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc"
"externalRRN" : "HcMQSFcY"
"externalTerminalId" : "98100010"
"externalInvoiceGUID" : "2fdca02f-3cbe-4e8c-82ad-86a1a16b72e8"
"externalTransactionDateTime" : "2025-09-17T09:16:59.6387832+00:00"
"authenticationKey": "e27b5ce6-8ba6-4746-9453-536728f7cbeb"
"transactionAmount": 1000Parameters
The following table describes the parameters of the QR_CODE_PAYMENT request message.
| PARAMETERS | TYPE | DESCRIPTION | EXAMPLE |
|---|---|---|---|
| REQUIRED | |||
| launchType | STRING | Must be QR_CODE_PAYMENT Used for launching the Ecentric Payment App to process a payment. | QR_CODE_PAYMENT |
| 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. | 1000 |
| OPTIONAL | |||
| transactionUuid | STRING ALPHANUMERIC | Unique ID of transaction Although this is an optional field, it is strongly recommended for the POS to send this value. | bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc |
| externalRRN | STRING ALPHANUMERIC | A RRN generated by some 3rd party ERP systems. Although this is an optional field, it is strongly recommended for the POS to send this value. | ABCDEF123456 |
| externalTerminalId | STRING NUMERIC | A terminal identifier for device configured on the 3rd party ERP system. Although this is an optional field, it is strongly recommended for the POS to send this value. | 98100010 |
| externalInvoiceGUID | STRING ALPHANUMERIC | A GUID that identifies a particular invoice that may appear on more than one transaction. Although this is an optional field, it is strongly recommended for the POS to send this value. | 2fdca02f-3cbe-4e8c-82ad-86a1a16b72e9 |
| 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” Although this is an optional field, it is strongly recommended for the POS to send this value. | 2017-04-28T09:30:00 |
| merchantName | STRING ALPHANUMERIC WITH SPACES | The name of the merchant that requested the transaction, as stored at the bank. | Merchant A |
| transactionDescription | STRING ALPHANUMERIC WITH SPACES | Reference description for the merchant’s records. | 3rd party app desc |
| transactionReferenceNo | 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 |
| externalTransactionGUID | STRING ALPHANUMERIC | A GUID that identifies a specific transaction generated by 3rd party ERP systems. | 2fdca02f-3cbe-4e8c-82ad-86a1a16b72e8 |
| 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. |
Sample Code
The following code needs to be implemented by the MPOS Application in order to invoke the Ecentric Payment App to initiate a QR_CODE_PAYMENT request message.
*See Sample Code QR Code Payment Response for the intentLauncher function
private void doQRCodePayment() {
Intent intent = new Intent();
intent.setClassName("com.ecentric.ecentricpay", "com.ecentric.ecentricpay.MainActivity");
Bundle dataBundle = new Bundle();
dataBundle.putString("launchType", "QR CODE PAYMENT");
dataBundle.putString("merchantID", "910100000000001")
dataBundle.putString("transactionUuid", "bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc")
dataBundle.putString("externalRRN", "HcMQSFcY")
dataBundle.putString("externalTerminalId", "98100010")
dataBundle.putString("externalInvoiceGUID", "2fdca02f-3cbe-4e8c-82ad-86a1a16b72e8")
dataBundle.putString("authenticationKey", "received_authenticationKey");
dataBundle.putLong("transactionAmount", 1000); // amount in cents
intent.putExtra("ecentricBundle", dataBundle);
try {
intentLauncher.launch(intent);
} catch (Exception e) {
Log.e(TAG, "Error launching intent: " + e);
}Response
Sample Bundle
The following is an example of a QR_CODE_PAYMENT response bundle the MPOS Application will receive.
"resultDescription": "APPROVED",
"buildInfo": "Ecentric",
"isReceiptDataAvailable": true,
"resultCode": "01",
"receiptBundle": {
"CARD_DESCRIPTION" = "",
"MERCHANT_REGION_CODE": "09",
"RC_ALT": "00",
"CASH_AMOUNT_CENTS": "0",
"SEQ_NO": "000",
"STATUS": "APPROVED",
"BUDGET_PERIOD": "0",
"CARD_TYPE": "",
"PAN_WITH_BIN": "",
"MERCHANT_ID": "770000000000123",
"TIMESTAMP": "1745476020950",
"EXTERNAL_TRANSACTION_DATETIME": "",
"PROCESSING_CODE": "0",
"RC_DESCRIPTION": "Approved",
"EXTERNAL_INVOICE_GUID": "aaaaaaaa-ffff-1111-2222-8cbbcc334426",
"REPLACEMENT_MERCHANT_ID": "",
"BATCH_NO": "000",
"AUTH_PROFILE": "0",
"INTERCHANGE": "null",
"ESC_BY_AUTH_CODE": "226 00 IH 15882",
"TX_TYPE": "0",
"ACC_TYPE_DESC": "Default",
"TIP_AMOUNT": "",
"CURRENCY_CODE": "0710",
"AUTH_CODE": "",
"RC": "00",
"AID": "",
"ATC": "",
"CRY": "",
"CVM": "none",
"PAN": "",
"RRN": "511427060006",
"TSI": "",
"TVR": "",
"APSN": "",
"DATE": "2025-04-24T06:27:06.749+0000",
"STAN": "",
"NAME_ON_CARD": "",
"AMOUNT_CENTS": "1000",
"ABS_AMOUNT": "10.00",
"TOKEN": "",
"RECEIPT_NUMBER": "",
"EXTENDED_TRX_TYPE": "",
"TERMINAL_ID": "77012398",
"TX_TYPE_DESCRIPTION": "QR PAYMENT",
"EXTERNAL_TERMINAL_ID": "",
"FORMATTED_AMOUNT": "R 10.00",
"DESCRIPTION": "511427060006",
"BATCH_NUMBER": "0",
"SETTLEMENT_DATE": "",
"SURCHARGE_AMOUNT": "0.00",
"EXTERNAL_TRANSACTION_GUID": "",
"CARD_BIN": "",
"TRANSACTION_INFO": "22600IH15882",
"REPLACEMENT_TERMINAL_ID": "",
"POS_ENTRY": "",
"RC_ISO_DESCRIPTION": "Success",
"APPLICATION_LABEL": "",
"MERCHANT_CITY": "Cape Town",
"MERCHANT_NAME": "Istore",
"CUSTOMER_NAME": "",
"APP_VERSION": "",
"CARD_SEQ_NO": "0",
"APP_LABEL": "",
"INVOICE_NUM": "",
"MESSAGE_1": "",
"MESSAGE_2": "",
"CARD_TRANSACTION_TYPE": "ALTERNATIVE_PAYMENT",
"FORMATTED_CASH_AMOUNT": "R 0.00",
"CASH_AMOUNT": "0.00",
"RESULT_CODE": "00",
"MERCHANT_COUNTRY_CODE": "ZA",
"REPRINT": "false",
"PAN_HASH": "",
"AMOUNT": "10.00",
"TIP_LABEL": "",
"DIGITS": "",
"CVM_ABSA": ""
},
"merchantID": "770000000000123",
"serialNumber": "PC05P2CG10036",
"launchType": "QR_CODE_PAYMENT",
"transactionUuid": "bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc",
"appVersion": "1.9.2",
"transactionAmount": 1000Parameters
The following table describes the parameters of the QR_CODE_PAYMENT response message.
| PARAMETERS | TYPE | DESCRIPTION | EXAMPLE |
|---|---|---|---|
| launchType | STRING | Echo of the launchType used to launch the Ecentric Payment App. | QR_CODE_PAYMENT |
| resultCode | STRING | Represents the result status of the intent call to the Ecentric Payment App ● 01: SUCCESSFUL ● 02: DECLINED ● 03: ABORTED ● 04: ERROR | 01 |
| 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 | LONG | 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 QR_CODE_PAYMENT 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 QR_CODE_PAYMENT 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 QR_CODE_PAYMENT ERROR response bundle that the MPOS Application will receive.
"appVersion": "2.1.2",
"buildInfo": "Ecentric_UAT,
"cashAmount": 0,
"errorBundle": {
"description": "ERROR",
"errorType": "TRANSACTION",
"message": "Transaction cancelled by user",
"reference": ""
},
"externalRrn": "RRN123456789",
"isReceiptDataAvailable": false,
"launchType": "QR_CODE_PAYMENT",
"merchantID": "910100000000001",
"resultCode": "03",
"resultDescription": "ABORTED",
"serialNumber": "F31P606437P1025",
"transactionAmount": 4400Updated about 2 months ago