📘
Note:
QR Refunds are currently only available for Payflex

What is a QR Refund?

A QR Refund is the process of returning funds to a customer for a previously approved QR Code transaction.

A QR refund occurs when a QR code transaction has already been approved, the payment has been processed, and the funds have been settled into the merchants account. At this stage, the merchant can initiate a QR refund to return the funds to the customer’s original payment method. QR refunds are typically issued when a customer is dissatisfied with a product or service, no longer needs the item, or if there was an issue with the order.

The Companion API enables an MPOS app to initiate full or partial QR refunds for previous QR Code transactions directly within the application.

To process a refund, the MPOS App must launch the Ecentric Payment App using an Android Intent call.

How Does a QR Refund Work?

Process Description:

Step 1:

On the MPOS App, the merchant selects a transaction from the transaction history to refund.

Step 2:

The merchant must enter either the full amount of the transaction value (Full refund) or a portion of the original transaction value (Partial refund).

Step 3:

The MPOS App will check if an auth token is available in the request.

If there is an auth token available then the transaction will continue as per normal.

If there 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 QR refund transaction can be requested.

Step 4:

A QR_REFUND is initiated on the MPOS App to the Ecentric Payment App via an Android Intent call.

Step 5:

The Ecentric Payment App will receive and process the QR_REFUND request.

Step 6:

The Ecentric Payment App will send a REFUND AUTHORIZATION message to the Ecentric Server.

Step 7:

The Ecentric Server will forward the REFUND AUTHORIZATION message to OMNI.

Step 8:

OMNI will the perform the necessary checks in order to validate and process the refund to the QR Provider. Once the validation of the refund has been performed, and OMNI receives a success response from the QR provider, OMNI will respond to the Ecentric Server, which contains the REFUND AUTHORIZATION response.

Step 9:

The Ecentric Server will return the REFUND AUTHORIZATION response to the Ecentric Payment App.

Step 10:

The Ecentric Pay App will send a REFUND CONFIRMATION message to Ecentric Server, unless there was a problem with the transaction locally, ie. was cancelled by Cashier.

Step 11:

The Ecentric Server will return the REFUND CONFIRMATION response to the Ecentric Payment App.

Step 12:

The Ecentric Payment App will then forward the refund outcome to the MPOS App,

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

Step 13:

The Ecentric Server will forward the REFUND CONFIRMATION message to OMNI.

Step 14:

OMNI will process the confirmation and forward to the QR provider.

Request

Sample Bundle

The following is an example of a QR_REFUND request

"launchType": "QR_REFUND"	
"merchantID": "770000000000123"
"originalTransactionUuid": "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": 1000

Parameters

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

PARAMETERS	TYPE	DESCRIPTION	EXAMPLE
REQUIRED
originalTransactionUuid	STRING ALPHANUMERIC	Supplying the original QR Transaction UUID.	bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc
launchType	STRING	Must be“QR_REFUND” Used for launching the Ecentric Payment App to process a QR refund.	QR_REFUND
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
externalRRN	STRING ALPHANUMERIC	Supplying the original QR Transaction RRN. 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	Supplying the original QR Transaction Invoice GUID.A GUID that identifies a particular invoice that may appear on more than one transaction. 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_REFUND request message.

*See Sample Code QR Refund Response for the intentLauncher function

private void doQrRefund() {
    Intent intent = new Intent();
   	intent.setClassName("com.ecentric.ecentricpay", "com.ecentric.ecentricpay.MainActivity");
    Bundle dataBundle = new Bundle();
    dataBundle.putString("launchType", "QR_REFUND");
  	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_REFUND 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_REFUND",
  "transactionUuid": "bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc",
  "appVersion": "1.9.2",
  "transactionAmount": "1000"

Parameters

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

PARAMETERS	TYPE	DESCRIPTION	EXAMPLE
launchType	STRING	Echo of the launchType used to launch the Ecentric Payment App.	QR_REFUND
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	STRING	Approved total transactionAmount.	1000
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_REFUND 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
transactionUuid	STRING	Echo of the Unique ID of a transaction.	bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc
externalTerminalId	STRING	Echo of the terminal identifier for device configured on the 3rd party ERP system.	98100010
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_REFUND 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.

Sample Bundle

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

"resultDescription": "ERROR",
"errorBundle": {
    "description": "ERROR",
    "reference": "",
    "errorType": "COMMS",
    "message": "Error communicating with server"
  },
"buildInfo": "Ecentric_DEBUG_Ecentric_INT",
"isReceiptDataAvailable": false,
"resultCode": "04",
"merchantID": "910100000000001",
"serialNumber": "PC05P2CG10036",
"launchType": "QR_REFUND",
"appVersion": "1.9.8",
"transactionAmount": 1000