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",
"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
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.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.

  "appVersion": "2.2.0",
  "buildInfo": "com.ecentric.ecentricpay-DEBUG-Ecentric-[Ecentric_INT]",
  "isReceiptDataAvailable": true,
  "launchType": "AUTHENTICATED_COLLECTION",
  "merchantID": "910100000000001",
  "receiptBundle": {
    "ABS_AMOUNT": "1,000.00",
    "ACC_TYPE_DESC": "Default",
    "AC_ACCOUNT_NUMBER": "0000000009099999999",
    "AC_COLLECTION_AMOUNT": "100000",
    "AC_CONTRACT_NUMBER": "a00023",
    "AC_DEBTOR_ID": "9707111000272",
    "AC_DEBTOR_ID_TYPE": "ID",
    "AC_MAC_DATA": "ZTPAOD0N",
    "AC_MAX_COLLECTION_AMOUNT": "200000",
    "AC_RESPONSE_CODE": "910000",
    "AC_RESPONSE_DESCRIPTION": "",
    "AID": "A0000000031010",
    "AMOUNT": "1,000.00",
    "AMOUNT_CENTS": "100000",
    "APPLICATION_LABEL": "VISA SAVINGS",
    "APP_LABEL": "VISA SAVINGS",
    "APP_VERSION": "",
    "APSN": "",
    "ATC": "072A",
    "AUTH_CODE": "",
    "AUTH_PROFILE": "0",
    "BATCH_NO": "000",
    "BATCH_NUMBER": "0",
    "BUDGET_PERIOD": "00",
    "CARD_BIN": "445143",
    "CARD_DESCRIPTION": "Visa Debit Classic",
    "CARD_SEQ_NO": "0",
    "CARD_TRANSACTION_TYPE": "ICC",
    "CARD_TYPE": "Debit",
    "CASH_AMOUNT": "0.00",
    "CRY": "791AC10DD6EFD8D4",
    "CURRENCY_CODE": "ZAR",
    "CUSTOMER_NAME": "",
    "CVM": "PIN Verified",
    "CVM_ABSA": "PIN Verified",
    "DATE": "2026-05-21T13:16:48.754+0000",
    "DESCRIPTION": "614116480001",
    "DIGITS": "2309",
    "ED_AC_ACCOUNT_NUMBER": "0000000009099999999",
    "ED_AC_COLLECTION_AMOUNT": "100000",
    "ED_AC_CONTRACT_NUMBER": "a00023",
    "ED_AC_DEBTOR_ID": "9707111000272",
    "ED_AC_DEBTOR_ID_TYPE": "ID",
    "ED_AC_MAC_DATA": "ZTPAOD0N",
    "ED_AC_MAX_COLLECTION_AMOUNT": "200000",
    "ED_AC_RESPONSE_CODE": "910000",
    "ED_AC_RESPONSE_DESCRIPTION": "",
    "ESC_BY_AUTH_CODE": "226 31 IH ",
    "EXTENDED_TRX_TYPE": "",
    "EXTERNAL_INVOICE_GUID": "",
    "EXTERNAL_TERMINAL_ID": "",
    "EXTERNAL_TRANSACTION_DATETIME": "",
    "EXTERNAL_TRANSACTION_GUID": "",
    "FORMATTED_AMOUNT": "R 1000.00",
    "FORMATTED_CASH_AMOUNT": "R 0.00",
    "IAD": "06010A03A0E801",
    "INTERCHANGE": "Debit",
    "INVOICE_NUM": "",
    "MERCHANT_CITY": "CAPE TOWN",
    "MERCHANT_COUNTRY_CODE": "ZA",
    "MERCHANT_ID": "910100000000001",
    "MERCHANT_NAME": "IPP Test L3",
    "MERCHANT_REGION_CODE": "09",
    "MESSAGE_1": "",
    "MESSAGE_2": "",
    "NAME_ON_CARD": "VISA FLAG DEBIT CARD/",
    "PAN": "**** **** **** 2309",
    "PAN_HASH": "",
    "PAN_WITH_BIN": "445143** **** 2309",
    "POS_ENTRY": "501",
    "PROCESSING_CODE": "0",
    "RC": "00",
    "RC_ALT": "00",
    "RC_DESCRIPTION": "Approved",
    "RC_ISO_DESCRIPTION": "Approved or completed successfully",
    "RECEIPT_NUMBER": "",
    "REPLACEMENT_MERCHANT_ID": "",
    "REPLACEMENT_TERMINAL_ID": "",
    "REPRINT": "",
    "RESULT_CODE": "00",
    "RRN": "614116480001",
    "SEQ_NO": "000",
    "SETTLEMENT_DATE": "",
    "STAN": "",
    "STATUS": "APPROVED",
    "SURCHARGE_AMOUNT": "0.00",
    "TERMINAL_ID": "91000328",
    "TIMESTAMP": "1779369408754",
    "TIP_AMOUNT": "",
    "TIP_LABEL": "",
    "TOKEN": "",
    "TRANSACTION_INFO": "22631IH",
    "TSI": "E800",
    "TVR": "04C024E800",
    "TX_TYPE": "INQUIRY",
    "TX_TYPE_DESCRIPTION": "INQUIRY"
  },
  "resultCode": "01",
  "resultDescription": "APPROVED",
  "serialNumber": "PC05P2CG10036",
  "transactionUuid": "ed6880a8-291e-4409-949f-c8c0f57a0828",
  "txType": "INQUIRY"

Parameters

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

PARAMETERS	TYPE	DESCRIPTION	EXAMPLE
launchType	STRING	Echo of the launchType used to launch the Ecentric Payment App.	AUTHENTICATED_COLLECTION
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
contractNumber	STRING	Echo of the contractNumber used to launch the Ecentric Payment app.	ACC784512
debtorIDType	STRING	Echo of the debtorIDType used to launch the Ecentric Payment app.	RSA_ID
debtorID	STRING	Echo of the debtorID used to launch the Ecentric Payment app.	1234567891234
collectionAmount	STRING	Echo of the collectionAmount used to launch the Ecentric Payment app.	2500
collectionAmountMax	STRING	Echo of the value used to launch the Ecentric Payment app.	3000
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 AUTHENTICATED_COLLECTION Response.
transactionUuid	STRING	Echo of the Unique ID of a transaction.	bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc
appVersion	STRING	The software version currently running on the Ecentric Payment App.	2.2.0
serialNumber	STRING	The serial number for the device that was used for the RETAIL_AUTH intent call.	PC05P2CG10036

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"