Description
The Deposit function is used to launch the payment application to deposit funds onto a card.
Request
Sample Bundle
"launchType": "DEPOSIT"
"merchantID": "770000000000123"
"authenticationKey": "e27b5ce6-8ba6-4746-9453-536728f7cbeb"
"transactionAmount": 1000
Parameters
The following table describes the parameters of the DEPOSIT request message.
| PARAMETERS | TYPE | DESCRIPTION | EXAMPLE |
|---|---|---|---|
| REQUIRED | |||
| launchType | STRING | Must be “DEPOSIT”. Used for launching the Ecentric Payment App to obtain an auth token. | DEPOSIT |
| 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 |
| 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. |
Sample Code
private void doDeposit() {
Intent intent = new Intent();
intent.setClassName("com.ecentric.ecentricpay", "com.ecentric.ecentricpay.MainActivity");
Bundle dataBundle = new Bundle();
dataBundle.putString("launchType", "DEPOSIT");
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_DEBUG_Ecentric_INT",
"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": "478769******5035",
"MERCHANT_ID": "910100000000001",
"TIMESTAMP": "1753967575073",
"EXTERNAL_TRANSACTION_DATETIME": "",
"PROCESSING_CODE": "0",
"RC_DESCRIPTION": "Approved",
"EXTERNAL_INVOICE_GUID": "",
"CURRENT_BALANCE_CENTS" = "805000",
"REPLACEMENT_MERCHANT_ID": "",
"BATCH_NO": "000",
"AVAILABLE_BALANCE_FORMATTED" = "R 8000.00",
"AUTH_PROFILE": "0",
"INTERCHANGE": "null",
"ESC_BY_AUTH_CODE": "206 21 SH 840343",
"TX_TYPE": "33",
"ACC_TYPE_DESC": "Default",
"TIP_AMOUNT": "",
"AVAILABLE_BALANCE_CENTS" = "800000",
"CURRENCY_CODE": "0710",
"AUTH_CODE": "840343",
"RC": "00",
"AID": "",
"ATC": "",
"CRY": "",
"CVM": "none",
"PAN": "************5035",
"RRN": "",
"APSN": "",
"DATE": "2025-07-31T13:13:00.949+0000",
"STAN": "",
"NAME_ON_CARD": "GROENEWALD/CG.MR",
"AMOUNT_CENTS": "1000",
"ABS_AMOUNT": "10.00",
"TOKEN": "",
"RECEIPT_NUMBER": "",
"EXTENDED_TRX_TYPE": "",
"TERMINAL_ID": "91000328",
"TX_TYPE_DESCRIPTION": "DEPOSIT",
"EXTERNAL_TERMINAL_ID": "",
"FORMATTED_AMOUNT": "R 10.00",
"DESCRIPTION": "",
"BATCH_NUMBER": "0",
"SETTLEMENT_DATE": "",
"SURCHARGE_AMOUNT": "0.00",
"CURRENT_BALANCE_FORMATTED" = "R 8050.00",
"EXTERNAL_TRANSACTION_GUID": "",
"CARD_BIN": "478769",
"TRANSACTION_INFO": "20621SH840343",
"REPLACEMENT_TERMINAL_ID": "",
"POS_ENTRY": "9001",
"RC_ISO_DESCRIPTION": "Approved or completed successfully",
"MERCHANT_CITY": "CAPE TOWN",
"MERCHANT_NAME": "THUMBZUP INT RETAIL",
"CUSTOMER_NAME": "",
"APP_VERSION": "",
"CARD_SEQ_NO": "0",
"APP_LABEL": "",
"INVOICE_NUM": "",
"MESSAGE_1": "",
"MESSAGE_2": "",
"CARD_TRANSACTION_TYPE": "MAG",
"FORMATTED_CASH_AMOUNT": "R 0.00",
"CASH_AMOUNT": "0.00",
"RESULT_CODE": "00",
"MERCHANT_COUNTRY_CODE": "ZA",
"REPRINT": "false",
"PAN_HASH": "8fe154743df867956bfd585a16c634e2cd45663a08466eca046e06fd66170533",
"AMOUNT": "10.00",
"TIP_LABEL": "",
"DIGITS": "5035",
"CVM_ABSA": ""
},
"merchantID": "910100000000001",
"serialNumber": "PC05P2CG10036",
"launchType": "DEPOSIT",
"transactionUuid": "8be8d316-38e9-4e14-b396-cfbacb9269ec",
"appVersion": "1.9.10",
"transactionAmount": "5000"
Parameters
The following table describes the parameters of the DEPOSIT response message.
| PARAMETERS | TYPE | DESCRIPTION | EXAMPLE |
|---|---|---|---|
| launchType | STRING | Echo of the launchType used to launch the Ecentric Payment App. | DEPOSIT |
| 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 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
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
Sample Bundle
"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": "DEPOSIT",
"appVersion": "1.9.8",
"transactionAmount": "5000"