Tokenised Debicheck payments

Overview

Customer bank account details can be tokenised using Debicheck. The tokenisation requires the customer to accept a real-time push notification.

Off-line options are also available for the customer to authorise the tokenisation via their banking app, cellphone banking, ATM or bank branch.

When creating a new future purchase to charge a customer for, you need to specify a due date that is two days in the future to cater for industry debit order cut-off dates.

The purchase status will remain in pending_charge status until the due date, at which point the status will change to pending_execute in waiting for the customer's bank to process the payment.

You can also tokenise a customer's bank details for EFT debit order payment processing without upfront payment or with an R0 amount.

❗️

Availability

Debicheck tokenisation is only available between 3 am and 8.30 pm SAST. Make use of the Delayed mandate option to attempt Debicheck tokenisation


Debicheck mandate types

DebiCheck mandates have several unique fields that must be tailored to your use case. The most critical DebiCheck field is the value_type, as it determines the DebiCheck rule set under which collections are permitted to process. These are as follows:

TypeDescription
FIXEDNo amount or rate adjustment is permitted. The products.price and max_amount_cents remain the same forever. The max_amount_cents is limited to the products.price.
VARIABLEThis may be misleading as the amount and rate adjustments are permitted. Collecting any amount other than the authenticated products.price up to the max_amounts_cents is permitted but is disputable. The max_amount_cents is limited to 1.5x the products.price.
USAGEBASEDAmount and rate adjustments are permitted. Collecting any amount other than the authenticated products.price up to the max_amounts_cents is permitted but is disputable. The max_amount_cents is unlimited, but caution is advised when using large values as the customer experience may be affected.

Be aware that you may not enable both adjustment_rate and adjustment_amount_cents, and you must do one of the other and omit the unnecessary one from your payload or provide it as null.


Required fields

authentication_typedetermined whether the authentication is sent using TT1 (real-time) or TT2 (delayed) method. REALTIME issues a USSD/push notification for acceptance in 120sec whereas DELAYED sends an SMS for acceptance in 48hours.
do_delayed_on_auth_failurewhen enabled will attempt to obtain an RMS authentication with a 48-hour response time when real-time or delayed authentication times out. RMS will enable you to collect on DebiCheck even though the customer has not fully authenticated the mandate - although collections will be disputable.
debit_sequencedetermines whether you will be collecting once-off or recurring on this mandate.
adjustment_categorydetermines the frequency of adjustments made to the products.price and max_amount_cents over time according to the DebiCheck rules and adjustment_rate or adjustments_amount_cents used. The relevant adjustment will be made on the adjustment_category frequency provided. For example, you may choose to adjust for annual inflation. Its enumerators are: NEVER, QUARTERLY, BIANNUALLY, ANNUALLY, REPO.
allow_date_adjustmentdetermines whether or not you may vary the due_date of the recurring charge to be a date other than what was explicity authenticated with the customer. When this is enabled and the date is adjusted to any other date, the collection becomes disputable.
verify_accountwhen enabled will conduct an Account Holder Verification (AVS-R) request to verify the ownership and validity of the bank account details provided. When enabled and account details are invalid, this request will fail.
curl -X 'POST' \
  'https://gate.reviopay.com/api/v1/purchases/' \
  -H 'Authorization: Bearer {{Your Revio Bearer token}}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "{{Your customers Revio client_id}}",
    "payment_method_whitelist":["debicheck"],
    "purchase": {
    	"currency": "ZAR",
        "language": "en",
	    "products": [
	    	{
    			"name": "My product or service fixed payment 1",
                "price": 15000
			}
	    ],
        "payment_method_details": {
            "direct_debit": {
                "profile_code": "{{Revio profile code}}",
                "abbreviated_name": "{{Merchant MID/Abbreviated name}}",
                "account_number": "{{Merchant clearing account}}",
                "deduction_day": 1,
                "period_units": "months"
                "value_type": "USAGEBASED",
                "adjustment_category": "ANNUAL", 
                "adjustment_rate": 6, 
                "adjustment_amount_cents": null,
                "allow_date_adjustment": true,
                "authentication_type": "REALTIME",
                "do_delayed_on_auth_failure": false,
                "verify_account": false,
                "debit_sequence": "RCUR",
                "max_amount_cents": 30000
            }
        }        
	},
  "brand_id": "{{Your Revio brand_id}}",
  "force_recurring": true
}
'
curl -X 'POST' \
  'https://gate.reviopay.com/api/v1/purchases/' \
  -H 'Authorization: Bearer {{Your Revio Bearer token}}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "{{Your customers Revio client_id}}",
    "purchase": {
    	"currency": "ZAR",
        "language": "en",
	    "products": [
	    	{
    			"name": "My produce or service charge",
                "price": 15000
			}
            
	    ]       
	},
    "due": 1663600356,
    "brand_id": "{{Your Revio brand_id}}"
}'
curl -X 'GET' \
  'https://gate.reviopay.com/api/v1/clients/33671895-54e4-4664-9c3a-f4b1dd4b6934/recurring_tokens/' \
  -H 'Authorization: Bearer {{Your Revio Bearer token}}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json'
curl -X 'POST' \
  'https://gate.reviopay.com/api/v1/purchases/b7b12cbd-6411-40b4-8be8-c48edfebad24/charge/' \
  -H 'Authorization: Bearer {{Your Revio Bearer token}}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "recurring_token": "4a328161-24d1-47c5-9169-f1c37d85c582"
}'

A client can have multiple recurring tokens stored against their id.

{
  "next": null,
  "previous": null,
  "results": [
    {
      "payment_method": "eft",
      "description": "dc6e28f0-74dc-4c0d-8d18-a167dca1a97b",
      "created_on": 1663426626,
      "updated_on": 1663426626,
      "type": "client_recurring_token",
      "id": "7731c687-84ea-4291-9207-b3b2e22f35fa"
    },
    {
      "payment_method": "eft",
      "description": "22a5d1de-727f-4d25-9769-841e17ca910d",
      "created_on": 1660818893,
      "updated_on": 1660818893,
      "type": "client_recurring_token",
      "id": "4a328161-24d1-47c5-9169-f1c37d85c582"
    }
  ]
}

Amending Debicheck tokens

Amending a customer's Debicheck details are as simple as:

  • Creating a new Purchase
  • Charging the purchase with the new Debit order details E.g. New Bank account to tokenise
  • Store and use the new token for future charges

📘

To amend the customer's details will require a re-authorisation from the customer.

Recurring tokens no longer required can be deleted using the Delete Recurring Token endpoint.