DebiCheck

DebiCheck is an authenticated debit order system that requires customers to electronically confirm mandate details before collections can be processed.

‍

Overview

DebiCheck provides:

Reduced disputability: Authenticated mandates are harder to dispute
Higher success rates: Early processing window priority
Account tracking: Monitor accounts for up to 10 days post-action date
Electronic mandate storage: Banks store authenticated mandates

‍

How DebiCheck Works

Mandate Creation: Submit the mandate request with the customer details
Authentication: Customer receives and approves the mandate via their bank
Confirmation: Mandate status changes to COMPLETED
Collection: Create collections against authenticated mandates

‍

Authentication Types

|Type|Code|Description|Response Time| |---|---|---|---| |Real-Time|TT1|USSD push notification|120 seconds| |Delayed Real-Time|TT1b|Extended approval window|Same day until 20:00| |Batch|TT2|Overnight processing|Up to 48 hours|

‍

Real-Time (TT1)

Customer receives an immediate USSD/push notification and must approve within 120 seconds.

‍

JSON

{ "authenticationType": "REALTIME", "realtimeAuthRetries": 0 }

‍

Delayed Real-Time (TT1b)

Mandate is lodged within 60 seconds, the customer has until 20:00 the same day to approve.

‍

JSON

{ "authenticationType": "DELAYED" }

‍

Batch (TT2)

Mandate submitted overnight, the customer has until 19:00 the following day to approve.

‍

JSON

{ "authenticationType": "BATCH" }

‍

Mandates

Create DebiCheck Mandate

Endpoint

POST /v2/mandate/debicheck/

‍

Request (Fixed Value)

BASH

curl -X POST https://dev.api.revio.co.za/v2/mandate/debicheck/ \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "initiationDate": "2024-01-15T10:00:00.000Z", "valueType": "FIXED", "debitSequence": "RCUR", "maxAmountCents": 10000, "amountCents": 10000, "allowDateAdjustment": true, "adjustmentCategory": "NEVER", "authenticationType": "REALTIME", "realtimeAuthRetries": 0, "fallbackAuthenticationType": "DELAYED_WITHOUT_AUTH", "profileCode": "TEST1", "abbreviatedName": "TESTMERCH1", "contractReference": "DC001", "debtor": { "accountNumber": "010553922", "accountType": "CURRENT", "bank": "ABSA", "branchCode": "632500", "firstName": "John", "lastName": "Smith", "identification": { "emailAddress": "john@example.com", "idNumber": "2001014800086", "phoneNumber": "+27-123456789", "passportNumber": "" } }, "creditor": { "accountNumber": "12345678", "accountType": "CURRENT", "branchCode": "051001", "name": "TEST MERCHANT 1", "bank": "STANDARDBANK", "phoneNumber": "+27-615333440", "emailAddress": "merchant@test.com" }, "releaseDate": "2024-12-31T00:00:00.000Z", "frequency": "MONTHLY", "collectionDay": 20, "currency": "ZAR", "entryClass": "21", "verifyAccount": false }'

‍

Request Fields

|Field|Type|Required|Description| |---|---|---|---| |`initiationDate`|string|Yes|Date mandate is initiated| |`valueType`|string|Yes|Value type: `FIXED`, `VARIABLE`, `USAGEBASED`| |`debitSequence`|string|Yes|Sequence type: `RCUR`, `OOFF`, `FRST`, `FNAL`| |`maxAmountCents`|integer|Yes|Maximum collection amount in cents| |`amountCents`|integer|Yes|Standard collection amount in cents| |`allowDateAdjustment`|boolean|Yes|Allow collection date variation| |`adjustmentCategory`|string|Yes|Adjustment frequency| |`authenticationType`|string|Yes|Auth type: `REALTIME`, `DELAYED`, `BATCH`| |`realtimeAuthRetries`|integer|No|Number of real-time retry attempts| |`fallbackAuthenticationType`|string|No|Fallback if auth fails| |`profileCode`|string|Yes|Your merchant profile code| |`abbreviatedName`|string|Yes|Your PASA-registered name| |`contractReference`|string|Yes|Contract reference (max 14 chars)| |`debtor`|object|Yes|Customer details| |`creditor`|object|Yes|Merchant details| |`ultimateCreditor`|object|No|Split payment recipient| |`releaseDate`|string|No|Mandate release date| |`firstCollectionDate`|string|No|First collection date (if different)| |`firstCollectionAmountCents`|integer|No|First collection amount (if different)| |`frequency`|string|Yes|Collection frequency| |`collectionDay`|integer|Yes|Day of month (1-31)| |`trackingPeriod`|integer|No|Days to track account (0-10)| |`currency`|string|Yes|Currency (`ZAR`)| |`entryClass`|string|Yes|Always `21`| |`verifyAccount`|boolean|No|Perform account verification|

‍

Value Types

|Type|Description|Max Amount Limit| |---|---|---| |`FIXED`|No amount adjustments allowed|Equal to `amountCents`| |`VARIABLE`|Amount adjustments allowed, disputable|1.5x `amountCents`| |`USAGEBASED`|Full flexibility, disputable|No specific limit|

‍

Debit Sequence Types

|Type|Description| |---|---| |`FRST`|First collection of mandate| |`OOFF`|Once-off (single collection)| |`RCUR`|Recurring collection| |`RPRE`|Re-presented after failure| |`FNAL`|Final collection of mandate|

‍

Adjustment Categories

|Value|Description| |---|---| |`NEVER`|No adjustments allowed| |`QUARTERLY`|Adjust every 3 months| |`BIANNUALLY`|Adjust every 6 months| |`ANNUALLY`|Adjust every year|

‍

Fallback Authentication Types

Please note that fallback to DELAYED_WITHOUT_AUTH was deprecated in 2025 in line with PASA requirements.

‍

|Value|Description| |---|---| |`DELAYED`|Fall back to TT2 batch| |`DELAYED_WITHOUT_AUTH`|Fall back without re-authentication|

‍

Response

JSON

{ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "PENDING_AUTHENTICATION", "authenticationType": "REALTIME", "valueType": "FIXED", "contractReference": "DC001", "debtor": { ... }, "creditor": { ... } }

‍

Variable Value Mandate

JSON

{ "valueType": "VARIABLE", "adjustmentCategory": "QUARTERLY", "adjustmentRate": "10.0", "maxAmountCents": 15000, "amountCents": 10000 }

‍

Note: Use either adjustmentRate (percentage) OR adjustmentAmountCents, not both.

‍

Usage-Based Mandate

JSON

{ "valueType": "USAGEBASED", "adjustmentCategory": "NEVER", "maxAmountCents": 50000, "amountCents": 10000 }

‍

Get Mandate Status

Endpoint

GET /v2/mandate/debicheck/{mandateId}/status/

‍

Request

BASH

curl -X GET https://dev.api.revio.co.za/v2/mandate/debicheck/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status/ \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

‍

Response

JSON

{ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "COMPLETED" }

‍

Mandate Statuses

|Status|Description| |---|---| |`NEW`|Mandate created, not yet submitted| |`PENDING_AUTHENTICATION`|Waiting for customer approval| |`COMPLETED`|Customer approved mandate| |`AUTH_FAILURE`|Authentication failed or rejected| |`CANCELLED`|Mandate cancelled| |`SUSPENDED`|Mandate temporarily suspended|

‍

Get Mandate Details

Endpoint

GET /v2/mandate/debicheck/{mandateId}

‍

Response

JSON

{ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "state": "COMPLETED", "referenceNumber": "REF123456", "authenticationReference": "AUTH789", "lastSuccessfulAuditId": "AUDIT456", "mandateReferenceNumber": "MRN001", ... }

‍

Store these values for mandate amendments:

referenceNumber
authenticationReference
lastSuccessfulAuditId

‍

Amend DebiCheck Mandate

Modify an existing authenticated mandate.

‍

Endpoint

PUT /v2/mandate/debicheck/{mandateId}

‍

Request

BASH

curl -X PUT https://dev.api.revio.co.za/v2/mandate/debicheck/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "state": "COMPLETED", "referenceNumber": "REF123456", "authenticationReference": "AUTH789", "lastSuccessfulAuditId": "AUDIT456", "maxAmountCents": 15000, ... }'

‍

Amendment Outcomes

|Change|Result| |---|---| |ID Number, Names, Phone, Email|No re-authentication| |Tracking, First Collection, Abbreviated Name|Re-authentication required| |Collection Day, Contract Reference|Re-authentication required| |Debit Amounts (if outside bounds)|Re-authentication required| |Debtor Account Number|New mandate required (AUTH_FAILURE)| |Creditor Details|New mandate required (AUTH_FAILURE)|

‍

Collections

Create DebiCheck Collection

Endpoint

POST /v2/collection/debicheck/from_mandate

‍

Request

BASH

curl -X POST https://dev.api.revio.co.za/v2/collection/debicheck/from_mandate \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "mandateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "collectionDate": "2024-02-20T00:00:00.000Z", "cycleDate": "2024-02-20T00:00:00.000Z", "debitSequence": "RCUR", "amountCents": 10000, "trackingPeriod": 0 }'

‍

Request Fields

|Field|Type|Required|Description| |---|---|---|---| |`mandateId`|string|Yes|Authenticated mandate ID| |`collectionDate`|string|Yes|Collection date| |`cycleDate`|string|Yes|Billing cycle date| |`debitSequence`|string|Yes|Sequence type| |`amountCents`|integer|Yes|Amount in cents| |`trackingPeriod`|integer|No|Override mandate tracking days (0-10)|

‍

Note: Use FRST for first/pro-rata collections, RCUR for recurring.

‍

Response

JSON

{ "id": "coll-123-456-789", "mandateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "PENDING", "collectionDate": "2024-02-20T00:00:00.000Z", "amountCents": 10000 }

‍

Get Collection Status

Endpoint

GET /v2/collection/debicheck/{collectionId}/status

‍

Cut-off Times

|Service|Weekday|Weekend| |---|---|---| |DebiCheck/RMS Collect|08:00 - 16:00 (2 days before)|08:00 - 11:00 (2 days before)| |DebiCheck TT1a/b|03:00 - 18:30|03:00 - 18:30| |DebiCheck TT2|03:00 - 18:30|03:00 - 18:30|

‍

Important: DebiCheck mandates can only be obtained between 06:00 and 20:00 on weekdays.

‍

Account Tracking

DebiCheck supports account tracking for up to 10 days post-action date:

‍

JSON

{ "trackingPeriod": 10 }

‍

If a collection fails due to insufficient funds, the bank will monitor the account and retry when funds are available.

‍

Best Practices

Have a timing plan: Switch to TT2 for authentication outside business hours
Handle failures: Implement a fallback to DELAYED_WITHOUT_AUTH
Plan for ignores: Follow up with customers who don't respond to authentication
Use correct value type: Choose FIXED, VARIABLE, or USAGEBASED based on your use case
Set appropriate max amounts: Ensure maxAmountCents covers your needs
Submit early: Present collections at least 2 calendar days before collection day
Match collection days: Present collections for the authenticated collection day

‍

Testing DebiCheck Mandates

Use these contract references to simulate scenarios:

‍

|Contract Reference|Scenario| |---|---| |`NORESPONSE`|Customer doesn't respond within timeout| |`FAILINIT`|Bank error during authentication| |`REJECT`|Customer rejects mandate| |`TIMEOUT`|Authentication times out|

‍

See Testing for more test scenarios.

Table of contents

DebiCheck

Overview

How DebiCheck Works

Authentication Types

Real-Time (TT1)

Delayed Real-Time (TT1b)

Batch (TT2)

Mandates

Create DebiCheck Mandate

Endpoint

Request (Fixed Value)

Request Fields

Value Types

Debit Sequence Types

Adjustment Categories

Fallback Authentication Types

Response

Variable Value Mandate

Usage-Based Mandate

Get Mandate Status

Endpoint

Request

Response

Mandate Statuses

Get Mandate Details

Endpoint

Response

Amend DebiCheck Mandate

Endpoint

Request

Amendment Outcomes

Collections

Create DebiCheck Collection

Endpoint

Request

Request Fields

Response

Get Collection Status

Endpoint

Cut-off Times

Account Tracking

Best Practices

Testing DebiCheck Mandates