DebiCheck mandates & collections

A DebiCheck debit order requires the consumer to electronically confirm the details of the debit order on a once-off basis, typically at the beginning of their contract.

The purpose of DebiCheck is to enable consumers to review and confirm the specific details of the debit order with their bank before it is processed to their bank accounts. This electronic approval process ensures that consumers have control over the debit orders and are fully aware of the transactions being processed to their accounts. In turn, this reduces the ability for consumers to effectively dispute transactions once processed.

Consumers can electronically approve a DebiCheck debit order using devices such as cellphones, banking apps, computers, or ATMs. The consumer's bank will provide information about the available options for electronic approval, ensuring that consumers have the tools to manage and monitor their debit orders effectively.

DebiCheck authentication types

Type	Description
Real Time	A Real-Time Transaction Type 1 (TT1) mandate applies to a mandate request that will be initiated for approval by the debtor via a Push USSD. The timeframe for this type of mandate is 120 seconds i.e. from receipt of the request at the creditor bank, presented to the debtor by his bank and response back to the creditor (be it approved, rejected, or timed out)
Delayed Real Time	A delayed Real-Time Transaction Type 1 (TT1) mandate applies to a mandate request submitted by the creditor and lodged with the debtor bank within 60 seconds for the debtor to approve. The debtor has until 20:00 on the same day to approve or reject the mandate. After this cut-off time, the mandate will expire. At any time during that day, when the debtor approves/rejects this type of mandate, the creditor will receive the feedback within 60 seconds.
Batch	A Batch Transaction Type 2 (TT2) mandate is submitted by the creditor during the day for action by the creditor bank overnight to the relevant debtor banks. The mandate must be made available to the debtor for approval by latest 08h00 on the day (day 1) following the initial request. The debtor then has until 19h00 the following day (Day 2) to approve his batch mandate, thereafter, the mandate will expire. Responses to batch mandate requests will be returned to the creditor from the creditor bank throughout the two-day period at prescribed intervals.
Upfront Authentication	An upfront authentication type 3 (TT3) mandate applies to a face-to-face interaction between the creditor and the debtor with the debtor's cheque card present. The debtor will swipe his bank card and enter his PIN to approve the mandate, and in this way, the authentication key is established upfront. The mandate registration can then be completed in real-time without any further action from the debtor. This method is currently not supported by Revio.

Creating a Debicheck mandate

Reference	Link
Integration Recipe	v2/mandate/debicheck/
Documentation	Swagger
API Reference	Reference

Sample request

{
    "referenceNumber": "d001",
    "authenticationReference": "da001",
    "trackingPeriod": 1,
    "initiationDate": "2023-06-05T10:50:58.835Z",
    "valueType": "FIXED",//or VARIABLE/USAGEBASED
    "debitSequence": "RCUR",
    "maxAmountCents": 4000,
    "allowDateAdjustment": true,
    "adjustmentCategory": "NEVER",
    "authenticationType": "REALTIME",
    "realtimeAuthRetries": 0,
    "doDelayedOnAuthFailure": false,
    "fallbackAuthenticationType": "DELAYED_WITHOUT_AUTH",//Auto failover if authentication fails
    "profileCode": "TEST1",
    "externalReference": "de00001",
    "abbreviatedName": "TESTMERCH1",
    "contractReference": "dc001",
    "debtor": {
        "accountNumber": "010553922",
        "accountType": "CURRENT",
        "bank": "ABSA",
        "branchCode": "632500",
        "firstName": "John",
        "lastName": "Postman",
        "identification": {
            "emailAddress": "[email protected]",
            "idNumber": "2001014800086",
            "phoneNumber": "+27-12345678",
            "passportNumber": ""
        }
    },
    "creditor": {
        "accountNumber": "12345678",
        "accountType": "CURRENT",
        "branchCode": "051001",
        "name": "TEST MERCHANT 1",
        "bank": "STANDARDBANK",
        "phoneNumber": "+27-615333440",
        "emailAddress": "[email protected]",
        "idNumber": "4101014800082"
    },
    "releaseDate": "2024-06-05T10:50:58.835Z",
    "firstCollectionDate": "2023-06-08T10:50:58.835Z",
    "firstCollectionAmountCents": 2500,
    "state": "NEW",
    "frequency": "MONTHLY",
    "ultimateCreditor": {                   //ultimate creditor only used if split payments are required. Leave out if not required.
        "accountNumber": "010553983",
        "accountType": "CURRENT",
        "branchCode": "051001",
        "name": "TEST MERCHANT 1",
        "bank": "STANDARDBANK",
        "phoneNumber": "+27-615333440",
        "emailAddress": "[email protected]",
        "idNumber": "4101014800082"
    },
    "entryClass": "21",
    "collectionDay": 20,
    "amountCents": 3000,
    "currency": "ZAR",
    "verifyAccount": false
}

Content-type : application/json
Authorization : Bearer XXXXXXXXXXXXXXXXXXXXXXXXX

// As generated in Post https://dev-payce.auth.eu-west-1.amazoncognito.com/oauth2/token

Amending DebiCheck mandates

Amending a mandate is the process where one or more fields on a Mandate is changed and produces one of the following results:

Changes are applied and no status change is required.
Changes are applied and a re-authentication is triggered at the banking provider.
Changes are applied and the banking provider requires a new mandate to be created.
After successfully amending (and potentially re-authenticating) a mandate, it will eventually transition to the COMPLETED state. All subsequent collections, created from these mandates, will be impacted by the changes.
This will not retroactively update past collections.

The following sections will cover the different results produced by amending a mandate.

Amendment outcome	Fields	Notes
No re-authentication required	ID Number	None
	First Name	None
	Last Name	None
	Phone Number	None
	Email Address	None
Re-authentication required	Tracking	Tracking is enabled/disabled on a mandate
	First Collection	Amount and/or Date is changed or added
	Abbreviated Name	Different than mandate
	Collection Day	Different than mandate
	Contract Reference	Different than mandate
	Adjustment Amount/Rate	Amount and/or Rate is changed or added
	Allowing Date Adjustment	AllowDateAdjustment is enabled or disabled
	Debit Amounts	If AmountCents and MaxAmountCents are not within the bounds of the original mandate
New Mandate Required (will result in AUTH_FAILURE)	Debtor Account	Changing account number and/or branch code
	Creditor	Changing any creditor details

DebiCheck mandate field requirements

DebiCheck mandates include several important fields that must be customised based on your specific use case. Among these fields, the value_type is particularly critical as it determines the rule set governing the processing of collections. Here are the available value_type options and their characteristics:

Field	Description
FIXED	With this value_type, no adjustments to the amount or rate are allowed. The products.price and max_amount_cents remain constant throughout the mandate. The max_amount_cents is limited to the products.price
VARIABLE	Despite the name, this value_type does allow for adjustments in the amount and rate of collections. You can collect amounts different from the authenticated products.price, but within the limit of the max_amount_cents. However, such collections are disputable. The max_amount_cents is limited to 1.5 times the products.price
USAGEBASED	This value_type permits adjustments in the collection amount and rate. Like "VARIABLE", you can collect amounts other than the authenticated products.price, but within the max_amount_cents limit. Again, these collections are disputable. The max_amount_cents has no specific limit, but it's advisable to exercise caution when using large values to ensure a smooth customer experience

Note that you should not enable both adjustment_rate and adjustment_amount_cents. Choose one, and omit the other from your payload or provide it as null.

Below are descriptions of the other important fields related to DebiCheck mandates:

Field name	Type	Description
authentication_type	string	Determines whether the authentication is sent in real-time (TT1) or delayed (TT2). REALTIME initiates a USSD/push notification for acceptance within 120 seconds, while DELAYED sends an SMS for acceptance within 48 hours.
do_delayed_auth_on_failure	boolean	When enabled, this field triggers a TT2 authentication with a 48-hour response time to obtain authentication when real-time authentication is unavailable or fails. You can also consult with us about enabling RMS when TT1 or TT2 requests time-out.
debit_sequence	string	Determines whether the mandate is for a one-time collection or recurring collections.
adjustment_category	string	Determines the frequency of adjustments made to the products.price and max_amount_cents over time based on the DebiCheck rules and adjustment_rate or adjustment_amount_cents used. You can specify the relevant adjustment frequency, such as quarterly, biannually, annually, etc.
allow_date_adjustment	boolean	When enabled, it allows for the variation of the due_date of recurring charges to a date different from what was initially authenticated. Adjusting the date to any other than the authenticated date makes the collection disputable.
verify_account	boolean	When enabled, it triggers an Account Holder Verification (AVS-R) request to verify the ownership and validity of the provided bank account details. If the account details are invalid, the verification request will fail.

By understanding and configuring these fields, you can tailor the DebiCheck mandates to your specific requirements and ensure compliance with industry rules and regulations.

Creating a DebiCheck collection from a mandate

Reference	Link
Integration Recipe	/v2/collection/debicheck/
Documentation	Swagger
API Reference	Reference

Sample request

{
    "mandateId": "77da5cb6-10e4-4d5e-ac3b-002ea6a01ef5", //mandateId created in the create mandate step
    "collectionDate": "2023-06-09T07:50:58.835Z",
    "cycleDate": "2023-06-09T07:50:58.835Z",
    "debitSequence": "RCUR",//FRST if first/pro-rata collection
    "amountCents": 2000,
    "trackingPeriod": 1//can be set to override tracking days on mandate. If mandate tracking period = 0, can only be 0.
}

Content-type : application/json
Authorization : Bearer XXXXXXXXXXXXXXXXXXXXXXXXX

// As generated in Post https://dev-payce.auth.eu-west-1.amazoncognito.com/oauth2/token

DebiCheck collection FAQs

FAQ	Fields required
Which collections frequencies are supported?	Use the frequency field We support YEARLY, MONTHLY and WEEKLY (we may support fortnightly in future)
Can I create a once-off collection with no recurring deduction?	Use OOFF as the value in the debitSequence field
How do I create a collection for the same amount every month?	Use FIXED as the value in the valueType field
How do I create a collection for an initial amount that is different to the recurring amount?	Use the firstCollectionAmountCents field
How do I create a collection for a different amount every month?	Use VARIABLE or USAGE_BASED VARIABLE = max_amount_cents is 1.5x amount_cents USAGE_BASED = max_amount_cents is the only one that matters, but collections are disputable