DebiCheck
DebiCheck is an authenticated debit order system that requires customers to electronically confirm mandate details before collections can be…
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.
{
"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.
{
"authenticationType": "DELAYED"
}Batch (TT2)
Mandate submitted overnight, the customer has until 19:00 the following day to approve.
{
"authenticationType": "BATCH"
}Mandates
Create DebiCheck Mandate
Endpoint
POST https://api.revio.co.za/v2/mandate/debicheck/Request (Fixed Value)
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": "0001010000006",
"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
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "PENDING_AUTHENTICATION",
"authenticationType": "REALTIME",
"valueType": "FIXED",
"contractReference": "DC001",
"debtor": { ... },
"creditor": { ... }
}Variable Value Mandate
{
"valueType": "VARIABLE",
"adjustmentCategory": "QUARTERLY",
"adjustmentRate": "10.0",
"maxAmountCents": 15000,
"amountCents": 10000
}Note: Use either adjustmentRate (percentage) OR adjustmentAmountCents, not both.
Usage-Based Mandate
{
"valueType": "USAGEBASED",
"adjustmentCategory": "NEVER",
"maxAmountCents": 50000,
"amountCents": 10000
}Get Mandate Status
Endpoint
GET https://api.revio.co.za/v2/mandate/debicheck/{mandateId}/status/Request
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
{
"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 https://api.revio.co.za/v2/mandate/debicheck/{mandateId}Response
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"state": "COMPLETED",
"referenceNumber": "REF123456",
"authenticationReference": "AUTH789",
"lastSuccessfulAuditId": "AUDIT456",
"mandateReferenceNumber": "MRN001",
...
}Store these values for mandate amendments:
referenceNumberauthenticationReferencelastSuccessfulAuditId
Amend DebiCheck Mandate
Modify an existing authenticated mandate.
Endpoint
PUT https://api.revio.co.za/v2/mandate/debicheck/{mandateId}Request
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 https://api.revio.co.za/v2/collection/debicheck/from_mandateRequest
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
{
"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 https://api.revio.co.za/v2/collection/debicheck/{collectionId}/statusCut-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:
{
"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, orUSAGEBASEDbased on your use case - Set appropriate max amounts: Ensure
maxAmountCentscovers 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.