Description
The Refund function is used to launch the payment application to process refunds for goods or services returned by customers.
Request
Parameters
The following table describes the parameters of the REFUND request message.
| 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
Parameters
The following table describes the parameters of the REFUND response message.
| 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"