# DebiCheck (/docs/direct-debit/debicheck)

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

## Overview [#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 [#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 [#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) [#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) [#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) [#batch-tt2]

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

```json
{
  "authenticationType": "BATCH"
}
```

## Mandates [#mandates]

### Create DebiCheck Mandate [#create-debicheck-mandate]

### Endpoint [#endpoint]

```text
POST https://api.revio.co.za/v2/mandate/debicheck/
```

### Request (Fixed Value) [#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": "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 [#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 [#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 [#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 [#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 [#fallback-authentication-types]

<Callout type="info">
Please note that fallback to `DELAYED_WITHOUT_AUTH` was deprecated in 2025 in line with PASA requirements.
</Callout>

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

### Response [#response]

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

### Variable Value Mandate [#variable-value-mandate]

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

<Callout type="info">
Note: Use either adjustmentRate (percentage) OR adjustmentAmountCents, not both.
</Callout>

### Usage-Based Mandate [#usage-based-mandate]

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

### Get Mandate Status [#get-mandate-status]

### Endpoint [#endpoint-1]

```text
GET https://api.revio.co.za/v2/mandate/debicheck/{mandateId}/status/
```

### Request [#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 [#response-1]

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

### Mandate Statuses [#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 [#get-mandate-details]

### Endpoint [#endpoint-2]

```text
GET https://api.revio.co.za/v2/mandate/debicheck/{mandateId}
```

### Response [#response-2]

```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 [#amend-debicheck-mandate]

Modify an existing authenticated mandate.

### Endpoint [#endpoint-3]

```text
PUT https://api.revio.co.za/v2/mandate/debicheck/{mandateId}
```

### Request [#request-1]

```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 [#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 [#collections]

### Create DebiCheck Collection [#create-debicheck-collection]

### Endpoint [#endpoint-4]

```text
POST https://api.revio.co.za/v2/collection/debicheck/from_mandate
```

### Request [#request-2]

```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 [#request-fields-1]

| 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) |

<Callout type="info">
Note: Use FRST for first/pro-rata collections, RCUR for recurring.
</Callout>

### Response [#response-3]

```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 [#get-collection-status]

### Endpoint [#endpoint-5]

```text
GET https://api.revio.co.za/v2/collection/debicheck/{collectionId}/status
```

## Cut-off Times [#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 |

<Callout type="info">
Important: DebiCheck mandates can only be obtained between 06:00 and 20:00 on weekdays.
</Callout>

## Account Tracking [#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 [#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 [#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.