What is DebiCheck?

DebiCheck is a type of debit order that requires you to confirm your debit order with your bank when entering into a contract with a service or credit provider. Using DebiCheck reduces the risk of an incorrect or fraudulent debit order being collected because the debit order can only be done according to the approved agreement (mandate).

📘
Ecentric’s role in processing DebiCheck mandates:
Though the DebiCheck TT3 is a comprehensive solution, Ecentric is specifically responsible for the TT3.

The DebiCheck TT3 authentication call allows an MPOS to request an authentication for a recurring debit order as per the PASA DebiCheck regulations, into their applications.

To process the Debicheck TT3 authentication request, the MPOS App must launch the Ecentric Payment App via an Android Intent call, to process the response intent data in order to understand if the debit order authentication request succeeded or failed.

📘
Note:
Ecentric only processes the authentication process, not the subsequent debiting of the Card Holder's account. A 'MAC' is then returned in the response, a number which permits the Integrator to debit money using a platform which manages in settlement.

How Does DebiCheck Work?

Process Description:

Step 1:

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

Step 2:

The Ecentric Payment App will process the card details and forward the AUTHENTICATED_COLLECTION request to the Ecentric Server.

Step 3:

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 4:

The Ecentric Server will send a financial message to the Acquirer.

Step 5:

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

Step 6:

The Ecentric Server will return the outcome to the Ecentric Payment App.

Step 7:

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

Step 8:

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

Request

Sample Bundle

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

"authenticationKey": "e27b6ce6-78ba6-4y46-9953-5afr28f7cbeb",
"merchantID": "971234500000003",
"launchType": "AUTHENTICATED_COLLECTION",
"accountNumber": "0000000000000000000",
"collectionAmount": 2500,
"collectionAmountMax": 3500,
"debtorIDType": "RSA_ID",
"debtorID": "1234567891234",
"contractNumber": "000000"

Parameters

The following table describes the parameters of the AUTHENTICATED_COLLECTION request message.

PARAMETERS	TYPE	DESCRIPTION	EXAMPLE
REQUIRED
launchType	STRING	Must be AUTHENTICATED_COLLECTION Used for launching the Ecentric Payment App to process a DebiCheck TT3 Authentication request.	AUTHENTICATED_COLLECTION
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
accountNumber	STRING	Account number from which the debit order will be deducted.	0000000000000000000
collectionAmount	LONG	The amount that will be debited from the cardholders' account in cents.	2500
collectionAmountMax	LONG	The maximum amount in cents that can be debited from a cardholder in the cases of a variable debit order.	3500
debtorIDType	STRING	Can be one of: ● RSA_ID ● PASSPORT	RSA_ID
debtorID	STRING	The RSA ID number or Passport Number depending on the debtorIDType used.	1234567891234
contractNumber	STRING ALPHANUMERIC	A contract number is a unique reference number assigned by the service provider to identify the agreement between the customer and the company.	ACC784512
OPTIONAL
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
transactionUuid	STRING ALPHANUMERIC	Unique ID of transaction	bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc
isReceiptRequired	BOOLEAN	If set to true, at least one of the receipt parameters cellNumberToSMSReceipt OR emailAddressToSendReceipt 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
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]

Sample Code

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

See Sample Code AUTHENTICATED_COLLECTION Response for the intentLauncher function

private void doAuthenticatedCollection() {
   Intent intent = new Intent();
   intent.setClassName("com.ecentric.ecentricpay", "com.ecentric.ecentricpay.MainActivity");
   Bundle dataBundle = new Bundle();
   dataBundle.putString("launchType", "AUTHENTICATED_COLLECTION");
   dataBundle.putString("merchantID", "910100000000001");
   dataBundle.putString("authenticationKey", "received_authenticationKey");
   dataBundle.putString("accountNumber", "0000000000000000000");
   dataBundle.putLong("collectionAmount", 2500);
   dataBundle.putLong("collectionAmountMax", 3500);
   dataBundle.putString("debtorIDType", "RSA_ID");
   dataBundle.putString("debtorID", "1234567891234");
   dataBundle.putString("contractNumber", "ACC784512"); 
   intent.putExtra("ecentricBundle", dataBundle);
   try {
       intentLauncher.launch(intent);
   } catch (Exception e) {
       Log.e(TAG, "Error launching intent: " + e);
   }
}

Response

Sample Bundle

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

Receipt Bundle Section

  "adjustAmount": 0,
  "appVersion": "2.2.0",
  "buildInfo": "com.ecentric.ecentricpay-DEBUG-Ecentric-[Ecentric_TEST]",
  "cashAmount": 0,
  "accountNumber": "0000000000000000000"
  "collectionAmount": 100000,
  "collectionAmountMax": 200000,
  "contractNumber": "a00023",
  "debtorID": "9707111000272",
  "debtorIDType": "ID",
  "isReceiptDataAvailable": true,
  "launchType": "AUTHENTICATED_COLLECTION",
  "macData": "        ",
  "merchantID": "910100000000001",
  "outstandingAmount": 100000,
  "posId": "",
  "receiptBundle": { Please see receipt bundle section   
  },
  "resultCode": "02",
  "resultDescription": "APPROVED",
  "serialNumber": "PC05P2CG10036",
  "transactionAmount": 100000,
  "transactionUuid": "72a3d56a-0495-45ac-b6ae-a7036b520567",
  "txType": "INQUIRY"

Parameters

The following table describes the parameters of the AUTHENTICATED_COLLECTION response message.

PARAMETERS	TYPE	DESCRIPTION	EXAMPLE
adjustAmount	STRING	N/A for DebiCheck	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 DebiCheck	0
accountNumber	STRING	Echo of Account number from which the debit order will be deducted.	0000000000000000000
collectionAmount	LONG	Echo of the collectionAmount used to launch the Ecentric Payment app.	2500
collectionAmountMax	LONG	Echo of the value used to launch the Ecentric Payment app.	3000
contractNumber	STRING	Echo of the contractNumber used to launch the Ecentric Payment app.	ACC784512
debtorID	STRING	Echo of the debtorID used to launch the Ecentric Payment app.	1234567891234
debtorIDType	STRING	Echo of the debtorIDType used to launch the Ecentric Payment app.	RSA_ID
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.	AUTHENTICATED_COLLECTION
macData	STRING		ZTPAOD0N
merchantID	STRING	Echo of the merchantID used in the request.	910100000000001
outstandingAmount	LONG	N/A for DebiCheck	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 query. ● 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
transactionUuid	STRING	Echo of the Unique ID of a transaction.	bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc
txType	STRING	Transaction type	INQUIRY

Sample Code

The following code needs to be implemented by the MPOS Application to recover the AUTHENTICATED_COLLECTION 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.
Required fields not present	Ensure that you are sending through all required fields.
Duplicate UUID	Ensure that a unique UUID is sent through for every new sale transaction.

Sample Bundle

The following is an example of a AUTHENTICATED_COLLECTION ERROR response bundle that the MPOS Application will receive.

  "appVersion": "2.2.0",
  "buildInfo": "com.ecentric.ecentricpay-DEBUG-Ecentric-[Ecentric_UAT]",
  "errorBundle": {
    "description": "ERROR",
    "errorType": "TRANSACTION",
    "message": "Transaction cancelled by user",
    "reference": ""
  },
  "isReceiptDataAvailable": false,
  "launchType": "AUTHENTICATED_COLLECTION",
  "merchantID": "910100000000001",
  "resultCode": "04",
  "resultDescription": "ABORTED"