📘

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.

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

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:

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