📘
Note:
The deposit function is currently only available for Gift Cards.

What is a Deposit?

A deposit is the amount of money loaded or reloaded onto a card, making funds available for use. It represents the stored value that can be spent or accessed according to the card’s terms of use.

How Does a Deposit Work?

Process Description:

Step 1:

When a deposit 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_AUTH request in order to obtain a valid auth token, before a DEPOSIT transaction can be requested.

Step 2:

The MPOS App will initiate a DEPOSIT request, the DEPOSIT request will be sent to the Ecentric Payment App.

Step 3:

The Ecentric Payment App will process the card details and forward the DEPOSIT transaction 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 send a financial message to the Acquirer.

Step 6:

The Acquirer will the perform the necessary checks in order to validate and process the DEPOSIT.
Once the validation of the DEPOSIT has been performed, the Acquirer will respond with a financial message to the Ecentric Server, which contains the DEPOSIT outcome.

Step 7:

The Ecentric Server will return the DEPOSIT response to the Ecentric Payment App.

Step 8:

The Ecentric Payment App will then forward the DEPOSIT outcome to the MPOS App.

Step 9:

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

Request

Sample Bundle

The following is an example of a DEPOSIT request bundle that the MPOS Application will request.

"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 process a deposit.	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. If transactionDescription field is left blank in the request, Ecentric will automatically generate/populate the field with the RRN value for the transaction.	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
externalRRN	STRING ALPHANUMERIC	A RRN generated by some 3rd party ERP systems. If externalRRN field is left blank in the request, Ecentric will automatically generate an externalRRN for the transaction.	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. If transactionUuid field is left blank in the request, Ecentric will automatically generate a transactionUuid for the 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. If externalTerminalId field is left blank in the request, Ecentric will automatically send the payment device TerminalId in the externalTerminalId field for the transaction.	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

The following code needs to be implemented by the MPOS Application in order to invoke the Ecentric Payment App to initiate a DEPOSIT request message.

*See Sample Code DEPOSIT Response for the intentLauncher function

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

📘
Note:
The following is only applicable for Gift Cards.
Within the Receipt Bundle Section look for the following fields to assist with the deposit response.

AVAILABLE_BALANCE_CENTS AND AVAILABLE_BALANCE_FORMATTED

CURRENT_BALANCE_CENTS AND CURRENT_BALANCE_FORMATTED

Sample Bundle

The following is an example of a DEPOSIT response bundle the MPOS Application will receive.

Receipt Bundle Section

  "adjustAmount": 0,
  "appVersion": "2.2.0",
  "buildInfo": "com.ecentric.ecentricpay-DEBUG-Ecentric-[Ecentric_TEST]",
  "cashAmount": 0,
  "isReceiptDataAvailable": true,
  "launchType": "DEPOSIT",
  "merchantID": "910100000000001",
  "outstandingAmount": 0,
  "posId": "",
  "receiptBundle": { Please see receipt bundle section
  },
  "resultCode": "01",
  "resultDescription": "APPROVED",
  "serialNumber": "PC05P2CG10036",
  "transactionAmount": 5000,
  "transactionLinkIdentifier": "",
  "transactionUuid": "cd14a381-32a7-4dfd-92f6-d73f7324055d",
  "txType": "DEPOSIT"

Parameters

PARAMETERS	TYPE	DESCRIPTION	EXAMPLE
adjustAmount	LONG	N/A for Deposits	0
appVersion	STRING	The software version currently running on the Ecentric Payment App.	2.0.0
buildInfo	STRING	Metadata that identifies the specific software build running on the payment device.	com.ecentric.ecentricpay-DEBUG-Ecentric-[Ecentric_UAT]
cashAmount	LONG	N/A for Deposits	0
isReceiptDataAvailable	STRING	Boolean indicating whether a receiptBundle object is available. Will always be included for approved or declined transactions.	true
launchType	STRING	Echo of the launchType used to launch the Ecentric Payment App.	DEPOSIT
merchantID	STRING	Echo of the merchantID used in the request.	910100000000001
outstandingAmount	LONG	N/A for Deposits	0
posId	STRING	N/A for Companion API Integrations
receiptBundle	STRING	Consists of a sub-bundle of server parameters that can be used by the partner application to create a receipt.	See Receipt Bundle Section
resultCode	STRING	Represents the final outcome of the transaction. ● 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
serialNumber	STRING	The serial number for the device that was used for the RETAIL_AUTH intent call.	PC05P2CG10036
transactionAmount	LONG	Approved total transactionAmount.	1000
transactionLinkIdentifier	STRING	N/A for Deposits
transactionUuid	STRING	Echo of the Unique ID of a transaction.	bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc
txType	STRING	Transaction type	DEPOSIT

Sample Code

The following code needs to be implemented by the MPOS Application to decode the DEPOSIT 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 deposit transaction.

Sample Bundle

The following is an example of a DEPOSIT 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": "DEPOSIT",
"appVersion": "1.9.8",
"transactionAmount": 5000