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

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

‍

Authentication Types

‍

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

‍

Value Types

‍

Debit Sequence Types

‍

Adjustment Categories

‍

Fallback Authentication Types

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

‍

‍

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

‍

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

‍

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

‍

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

‍

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

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

‍

Testing DebiCheck Mandates

Use these contract references to simulate scenarios:

‍

‍

See Testing for more test scenarios.