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:

Type	Description
`FIXED`	No 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.
`VARIABLE`	This 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.
`USAGEBASED`	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 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_type`	determined 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_failure`	when 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_sequence`	determines whether you will be collecting once-off or recurring on this mandate.
`adjustment_category`	determines 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_adjustment`	determines 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_account`	when 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.

Overview

❗️Availability

Debicheck mandate types

Required fields

Amending Debicheck tokens

📘

❗️
Availability