Refund

Description

The Refund function is used to launch the payment application to process refunds for goods or services returned by customers.

Request

Sample Bundle

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

Parameters

PARAMETER	TYPE	DESCRIPTION	EXAMPLE
REQUIRED
launchType	STRING	Must be “REFUND” Used for launching the Ecentric Payment App to process a refund.	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 login to the Ecentric Payment App.	e27b5ce6-8ba6-4746-9453-536728f7cbeb
transactionAmount	LONG	The full transaction amount to be charged in cents (long)	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.	500
transactionDescription	STRING ALPHANUMERIC WITH SPACES	Reference number for the merchant’s records.	3tf party app desc
transactionReferenceNumber	STRING ALPHANUMERIC	Reference number field that also apperas in a merchant portal when available.	ref#123456
cellNumberToSMSReceipt	STRING NUMERIC	0-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	An optional 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
externalTransactionDateTime	STRING	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”	2017-04-28T09:30:00
externalTerminalId	STRING NUMERIC	An optional terminal identifier for device configured on the 3rd party ERP system	98100010
latitude	STRING NUMERIC	An optional geolocation identifier indicating the latitude position of the device	-28.1619942
longitude	STRING NUMERIC	An optional geolocation identifier indicating the longitude position of the device	30.2350981
accuracy	STRING NUMERIC	An optional accuracy indicator of the geolocation
originalTransactionUuid	STRING ALPHANUMERIC	Supplying the original sale UUID will initiate a matched refund. If the original sale was tokenized, the refund will be processed via the previously tokenized card holder details.	bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc

Sample Code

private void doRefund() {
    Intent intent = new Intent();
   	intent.setClassName("com.ecentric.ecentricpay", "com.ecentric.ecentricpay.MainActivity");
    Bundle dataBundle = new Bundle();
    dataBundle.putString("launchType", "REFUND");
  	dataBundle.putString("merchantID", "910100000000001");
  	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

"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": "1745489204493",
    "EXTERNAL_TRANSACTION_DATETIME": "",
    "PROCESSING_CODE": "0",
    "RC_DESCRIPTION": "Approved",
    "EXTERNAL_INVOICE_GUID": "",
    "REPLACEMENT_MERCHANT_ID": "",
    "BATCH_NO": "000",
    "AUTH_PROFILE": "0",
    "INTERCHANGE": "null",
    "ESC_BY_AUTH_CODE": "226 20 IH* 657404",
    "TX_TYPE": "20",
    "ACC_TYPE_DESC": "Default",
    "TIP_AMOUNT": "",
    "CURRENCY_CODE": "0710",
    "AUTH_CODE": "657404",
    "RC": "00",
    "AID": "A0000000031010",
    "ATC": "055E",
    "CRY": "B6C45455ADCB3607",
    "CVM": "none",
    "IAD": "06010A03804000",
    "PAN": "************2309",
    "RRN": "511406490032",
    "TSI": "0000",
    "TVR": "0000000000",
    "APSN": "",
    "DATE": "2025-04-24T10:06:49.559+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": "REFUND",
    "EXTERNAL_TERMINAL_ID": "",
    "FORMATTED_AMOUNT": "R 10.00",
    "DESCRIPTION": "511406490032",
    "BATCH_NUMBER": "0",
    "SETTLEMENT_DATE": "",
    "SURCHARGE_AMOUNT": "0.00",
    "EXTERNAL_TRANSACTION_GUID": "",
    "CARD_BIN": "445143",
    "TRANSACTION_INFO": "22620IH*657404",
    "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",
"launchType": "REFUND",
"cashAmount": "0",
"transactionUuid": "f3c345be-68c9-427c-9f5c-e4e7861ce127",
"appVersion": "1.9.2",
"transactionAmount": "1000"

Parameters

PARAMETERS	TYPE	DESCRIPTION	EXAMPLE
launchType	STRING	Echo of the launchType used to launch the Ecentric Payment App.	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 01 resultCode. 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
transactionUuid	STRING	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.	bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc
cellNumberToSMSReceipt	STRING	Masked out value of the cell number used to send the receipt to.	* * **657
emailAddressToSendReceipt	STRING	Masked out value of the email address used to send the receipt to.	* * * *@ecentric.com
isReceiptRequired	STRING	Echo of the isReceiptRequired used to launch the Ecentric Payment App.	true
isReceiptDataAvailable	STRING	A boolean indicating whether a receiptBundle parameter is available. Will always be there for accepted or declined transactions.	true
receiptBundle	STRING	Consists of a sub-bundle of server parameters that can be used by the partner application.	See Sample ecentricBundle 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
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 REFUND intent call.	PC05P2CG10036

Sample Code

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
										// 00 = Completed
										// 01 = Transaction successful
                   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

Sample Bundle

"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": "REFUND",
"cashAmount": "0",
"appVersion": "1.9.8",
"transactionAmount": "1000"