Debit order and Debicheck

Introduction

Debit order and DebiCheck payments are two common methods used for financial transactions in South Africa, particularly for recurring payments such as subscriptions, loan repayments, and utility bills.

Here's an overview of how these payment methods work:

Debit Order:

Debicheck

DebiCheck offers an additional layer of security by requiring explicit customer approval for each transaction, reducing the risk of unauthorized deductions. This method helps customers maintain better control over their recurring payments.

🚧

Please note

It's important to note that the specifics of debit orders and DebiCheck payments may vary based on the financial institutions, service providers, and the evolving regulations in South Africa.

Step1: Initiate Purchase

To accept Debit orders and Debicheck payments in your application or website, use:

• Please remember to specify the success/fail redirect in the call
• To capture customers' bank details, use an HTML form hosted on your website
• Note that additional fields are required to create a Debicheck mandate

{
    "client_id": "{{your client_id}}",
    "payment_method_whitelist":["eft"],
    "purchase": {
    	"currency": "ZAR",
        "language": "en",
	    "products": [
	    	{
    			"name": "My product or service - charge 1",
                "price": 100
			}
	    ],
        "payment_method_details": {
            "direct_debit": {
                "profile_code": "{{Revio profile_code}}",
                "abbreviated_name": "{{MID/abbreviated name}}",
                "account_number": "{{clearing account_number}}",
                "deduction_day":" {{clients preferred payment deduction day}}",
                "period_units": "months"
            }
        }        
	},
	"brand_id": "{{your brand_id}}",
    "force_recurring": true
}

{
    "client_id": "77a96956-4e84-46d4-abf4-29493d447952",
    "payment_method_whitelist":["debicheck"],
    "due": 1678701785,
    "purchase": {
    	"currency": "ZAR",
        "language": "en",
	    "products": [
	    	{
    			"name": "BNPLProduct",
                "price": 269900
			}
	    ],
        "payment_method_details": {
            "direct_debit": {
                "value_type": "USAGEBASED",					/Can also be FIXED OR VARIABLE
                "period_units": "months",
                "profile_code": "Q4TIER3_ORG21",		/Provided by Revio
                "deduction_day": 13,
                "account_number": "201647605",
                "debit_sequence": "RCUR",						/or OOF for once-off collections
                "verify_account": false,						/automated bank account verification
                "adjustment_rate": null,
                "tracking_period": 0,
                "abbreviated_name": "HAPPYPAY",
                "max_amount_cents": 269900,
                "reference_number": null,
                "adjustment_amount": null,
                "adjustment_category": "NEVER",
                "authentication_type": "DELAYED",
                "default_service_type": "TWODAY",
                "allow_date_adjustment": true,
                "realtime_auth_retries": 0,
                "do_delayed_on_auth_failure": false,
                "first_deduction_date":"2023-05-22",
                "first_deduction_amount": 120
            }
        }  
	},
	"brand_id": "ee711cab-4ec2-4aa6-89f0-e8012d3fbcb8",
    "force_recurring": true
}

Step2: Create debit order mandate

The platform requires a customer mandate before a payment collection can be generated. This is done by charging the purchase via the Direct post method using the details below.

```
curl --location 'https://gate.reviopay.com/p/transaction_id/' \
--form 'pm="debicheck"' \
--form 'PayceFirstName="Test"' \
--form 'PayceLastName="Test"' \
--form 'PaycePhoneNumber="0768887009"' \ 		needs to be this format
--form 'PayceIdType="idNumber"' \						or passportNumber
--form 'PayceIdNumber="2001014800086"' \		needs to be valid SA ID number
--form 'PayceBranchCode="123456"' \					needs to be 6 digits
--form 'PayceAccountType="Current"' \				or Savings or Transmission (case sensitive)
--form 'PayceAccount="123456781"' \					valid South Africa bank account required
```

You will always receive a 200 response as this call returns HTML. The best way to check for success/errors is to GET the purchase and check the status and attempts. Set up a Webhook using your account's Developers section or Webhook API to listen to purchase.paid, or purchase.payment_failure event on your server.

Step3: Create purchase for upcoming payment

After a mandate has been created, you can create a payment collection instruction using the following:

The request body for Debit order and Debicheck is largely the same. Debicheck allows for tracking, which will check your customer's account for up to 10 days after and initial payment collection failure. If the account is funded after the collection date, the bank will automatically collect the outstanding amount and pay it over to the creditor.

{
    "client_id": "{{client_id}}",
    "payment_method_whitelist":["debicheck"],
    "purchase": {
    	"currency": "ZAR",
        "language": "en",
	    "products": [
	    	{
    			"name": "My product or service ",
                "price": 100
			},
        {"direct_debit": {"first_deduction": true}}
	    ]
	},
    "due": "{{future epoch charge date}}",
    "tracking_period": 5,					//Debicheck only, and up to 10 tracking days allowed
   	"brand_id": "{{brand_id}}"		
}

Step4: Charge customer's bank account

❗️

Processing cut-off

Debit order and Debicheck payment collection instructions needs to be created at least 2 days before the intended customer deduction date

Now that the purchase for the payment collection has been created, you can charge the customer's bank account.

Once the charge request has been initiated, an instruction will be sent to the bank to deducted the required amount from the customer's account.

{
  "recurring_token": "{{purchase_id step2}}"
}

Step5: Verify status

• Use the success_callback parameter of the Purchase object.
• Use GET /purchases/<purchase_id> request.
• Set up a Webhook using your account's Developers section or Webhook API to listen to purchase.paid, or purchase.payment_failure event on your server.

Debit order and DebiCheck mandate management

PASA mandates guidelines:

Minimum requirements per mandate type

For voice-recorded mandates, please take note of the following additional points:

• Written confirmation: The voice-recorded mandate must be confirmed in writing to the account holder within 21 days of the mandate recording. This written confirmation should be provided before any debit payment instructions are processed to the account.
• Customer awareness: It is essential to inform the customer that their voice is being recorded and that the message will be the official authority to debit their account.
• Contract reference and abbreviated name: The customer should be informed of the unique contract reference and abbreviated name that will appear on their bank statement to identify the transaction.
• Reliable recording devices: Ensure that the recording devices used for voice mandates are reliable and provide acceptable acoustic quality. It is preferable to use recording devices that are SABS approved.
• Proper indexing: Recorded messages should be indexed systematically, facilitating easy accessibility and efficient handling of possible inquiries and disputes.

Debicheck-specific rules

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.

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

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:

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

DebiCheck collection FAQs