Guides

DebiCheck bill payments

Overview

A debiCheck debit order is one that a consumer confirms electronically on a once-off basis (at the start of their contract).

Its purpose is for consumers to confirm the details of the debit order with their bank before it is processed to their bank accounts.

To electronically approve a debit order means they confirm the details of their debit order on an electronic device such as a cellphone, bank app, personal computer or perhaps an ATM.

A consumer’s bank will let them know which options are available for them to use. It ensures that consumers are in control and know that debit orders are processed to their bank accounts.


Debicheck tokenisation options

  • Fixed: Best for subscriptions where the recurring payment value won't change over time

  • Variable: Best for subscriptions where you need to cater for changes in deduction date or amount within certain contract limitations. E.g. Annual price escalation

  • Usage-based: best for subscriptions where the manually amount charged will differ. E.g. ISP billing

🚧

Coverage

Debicheck payments are only available in South Africa

While debicheck payments are highly regulated in South Africa, merchants who responsibly collect from customers will be able to collect recurring revenue with little friction.


Tokenised debicheck order subscription payments

To sign-up a subscriber using debicheck as a recurring payment method requires three basic steps:

  1. Create a billing template using the Billing template endpoint

  2. Add subscriber to billing template using the Add subscriber endpoint

  3. Tokenise your customer's bank account details using Custom payment flow or Revio payment flow flows


Debicheck field requirements

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:

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

The other fields are described below:

  • 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_auth_on_failure when enabled will send a TT2 authentication with a 48-hour response time to attempt to obtain an authentication when real-time authentication is unavailable or fails. You can also chat with us about enabling RMS when TT1 or TT2 requests time-out.

  • 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.

"payment_method_details": {
        "direct_debit": {
            "profile_code": "{{Revio profile code provide by Revio}}",
            "abbreviated_name": "{{Merchant MID/Abbreviated name provided by Revio}}",
            "account_number": "{{Clearing account provided by Revio}}"
        }

{
  	"client_id": "{{Your customers client_id}}",
    "payment_method_whitelist": ["eft"],
    "subscription_first_deduction_amount": 110,
    "subscription_first_deduction_date": "2022-03-01",
    "subscription_deduction_date": "2022-03-28",
    "subscription_release_date": "2023-02-28",
    "subscription_tracking_period": 2,
    "value_type": "VARIABLE",
    "adjustment_category": "QUARTERLY", 
    "adjustment_rate": 1.1, 
    "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": 150
}

Tokenised DebiCheck subscription payments - Custom payment flow

The Revio custom payment flow allows you to create a subscription, add a subscriber and tokenise account details, all from your back-end and keeping with your target user experience.

curl -X 'POST' \
  'https://gate.reviopay.com/api/v1/billing_templates/' \
  -H 'Authorization: Bearer {{Your Revio Bearer token}}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Recurring debicheck example",
  "purchase": {
    "currency": "ZAR",
    "products": [
      {
        "name": "Recurring debicheck example",
        "price": 100
      }
    ],
    "payment_method_details": {
        "direct_debit": {
            "profile_code": "{{Revio profile code}}",
            "abbreviated_name": "{{Merchant MID/Abbreviated name}}",
            "account_number": "{{Merchant clearing account}}"
        }
    }
  },
  "brand_id": "{{Your Revio brand_id}}",
  "is_subscription": true,
  "subscription_active": true,
  "subscription_period": 1,
  "subscription_period_units": "months",
  "subscription_due_period": 1,
  "subscription_due_period_units": "days",
  "subscription_charge_period_end": false,
  "subscription_trial_periods": 0,
  "force_recurring": true
}'

curl -X 'POST' \
  'https://gate.reviopay.com/api/v1/billing_templates/65035aaf-34fb-49c2-b9b7-bd1f15eb4233/add_subscriber/' \
  -H 'Authorization: Bearer {{Your Revio Bearer token}}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_id": "{{Your customers client_id}}",
    "payment_method_whitelist": ["debicheck"],
    "subscription_first_deduction_amount": 110,
    "subscription_first_deduction_date": "2022-09-21",
    "subscription_deduction_date": "2022-10-01",
    "subscription_release_date": "2023-10-01",
    "subscription_tracking_period": 2,
    "subscription_value_type": "FIXED",
    "subscription_allow_date_adjustment": true,
    "subscription_authentication_type": "REALTIME",
    "subscription_realtime_auth_retries": 0,
    "subscription_do_delayed_on_auth_failure": false,
    "subscription_verify_account": false
}'

curl -X 'POST' \
  'https://gate.reviopay.com/api/v1/billing_templates/65035aaf-34fb-49c2-b9b7-bd1f15eb4233/add_subscriber/' \
  -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"],
    "subscription_first_deduction_amount": 110,
    "subscription_first_deduction_date": "2022-09-21",
    "subscription_deduction_date": "2022-10-01",
    "subscription_release_date": "2023-10-01",
    "subscription_tracking_period": 2,
    "subscription_value_type": "USAGEBASED",
    "subscription_allow_date_adjustment": true,
    "subscription_authentication_type": "REALTIME",
    "subscription_realtime_auth_retries": 0,
    "subscription_do_delayed_on_auth_failure": false,
    "subscription_verify_account": false,
    "subscription_max_amount_cents": 500
}'

curl -X 'POST' \
  'https://gate.reviopay.com/api/v1/billing_templates/65035aaf-34fb-49c2-b9b7-bd1f15eb4233/add_subscriber/' \
  -H 'Authorization: Bearer {{Revio Bearer token}}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_id": "{{Your customers Revio client_id}}",
    "payment_method_whitelist": ["debicheck"],
    "subscription_first_deduction_amount": 100,
    "subscription_first_deduction_date": "2022-09-21",
    "subscription_deduction_date": "2022-10-01",
    "subscription_release_date": "2023-10-01",
    "subscription_tracking_period": 2,
    "value_type": "VARIABLE",
    "adjustment_category": "QUARTERLY", 
    "adjustment_rate": 1.1, 
    "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": 150
}'

pm:debicheck
PayceFirstName:Test
PayceLastName:Test
PaycePhoneNumber:0768887009 // needs to be this form
PayceIdType:idNumber // or passportNumber
PayceIdNumber:2001014800086 // needs to be valid SA ID number
PayceBranchCode:123456 // needs to be 6 digits
PayceAccountType:Current // or Savings or Transmission (case sensitive)
PayceAccount:123456781 // valid South Africa bank account

See Debicheck mandates for a list of Debicheck rules.

🚧

When using the Direct charge payment method, ensure that the URL you use for tokenising customers banking details are: https://gate.reviopay.com/p/{{Purchase_id generated from add-subscriber call}}/

The first deduction or recurring deduction date must be four days in the future when adding the subscriber to the subscription billing template.

❗️

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.

When using postman to test this request, make sure to select x-www-form-urlencoded.


Tokenised DebiCheck subscription payments - Revio payment flow

The Revio payment flow allows customers to be redirected to the Revio payments page to tokenise their bank account details.


✅

Pro tip

Send your customer a payment-link via email, SMS or text to allow them to securely tokenise their banking details without having to provide them to a call centre agent or your website.


Amending Debicheck tokens


You can amend Debicheck tokens by calling PATCH /billing_templates/{id}/clients/{id}/


Here is the full list of fields you can amend:


'subscription_tracking_period',
'subscription_value_type',
'subscription_allow_date_adjustment',
'subscription_authentication_type',
'subscription_realtime_auth_retries',
'subscription_do_delayed_on_auth_failure',
'subscription_verify_account',
'subscription_reference_number',
'subscription_max_amount_cents',
'subscription_debtor_account_number',
'subscription_debtor_account_type',
'subscription_debtor_branch_code',
'subscription_debtor_first_name',
'subscription_debtor_last_name',
'subscription_debtor_id_number',
'subscription_debtor_phone_number',
'subscription_adjustment_category',
'subscription_adjustment_rate',
'subscription_adjustment_amount',
'subscription_release_date',

Updated 8 months ago