Debit Order Service
API reference for creating and managing debit orders to automatically collect payments from customer accounts on scheduled dates.
API reference for creating and managing debit orders. Debit orders allow you to automatically collect payments from customer accounts on scheduled dates.
Overview
The Debit Order API enables you to create recurring or once-off debit orders against customer bank accounts. This service is ideal for subscription-based businesses, recurring payments, and automated collections.
Mandate Requirements
Before initiating debit orders, ensure you have obtained proper mandates from customers. All debit orders must comply with local regulations and banking requirements.
Key Features
- Create once-off or recurring debit orders
- Set specific collection dates
- Track debit order status in real-time
- Automatic retry logic for failed collections
- Comprehensive webhook notifications
1. Create Debit Order
Create a new debit order to collect funds from a customer's bank account.
Subject: svc.debit.<entity_id>.create
Request
| Field | Type | Required | Description |
|---|---|---|---|
clientTxId | string | required | Unique transaction ID to prevent duplicate transactions |
mandate_reference | string | required | Mandate reference number authorizing this debit order |
amount | number | required | Amount in cents (i.e. 1000 == ZAR 10.00) |
collection_date | string | required | Date to collect the debit order (YYYY-MM-DD) |
account_holder_name | string | required | Account holder's full name |
account_number | string | required | Bank account number |
account_type | string | required | "cheque" or "savings" |
branch_code | string | required | Bank branch code |
reference | string | required | Payment reference (max 20 characters) |
frequency | string | required | "once_off", "weekly", "monthly", or "annually" |
end_date | string | optional | End date for recurring debit orders |
tracking_days | number | optional | Number of days to track the debit order status (default: 10) |
notification_email | string | optional | Email address for notifications |
metadata | object | optional | Additional data for your reference |
Optional Fields
end_date: required for recurring debit orderstracking_days: days to track the debit order status (default: 10, max: 30)metadata: store additional information (max 1KB)
Response
Possible Errors
400 Bad Request: Invalid request data | Invalid collection date | Invalid mandate401 Unauthorized: Authentication failed409 Conflict: Duplicate transaction ID422 Unprocessable Entity: Business validation failed
2. List Debit Orders
Retrieve a list of debit orders for your entity with optional filtering.
Subject: svc.debit.<entity_id>.list
Request
| Field | Type | Required | Description |
|---|---|---|---|
status | string | optional | Filter by status: "scheduled", "processing", "successful", or "failed" |
from_date | string | optional | Start date for filtering |
to_date | string | optional | End date for filtering |
limit | number | optional | Number of results to return (default: 100, max: 1000) |
offset | number | optional | Pagination offset |
Response
3. Cancel Debit Order
Cancel a scheduled debit order. Can only cancel debit orders that haven't been processed yet.
Subject: svc.debit.<entity_id>.cancel
Request
| Field | Type | Required | Description |
|---|---|---|---|
debit_order_id | string | required | ID of the debit order to cancel |
reason | string | optional | Reason for cancellation |
Response
Cancellation Window
Debit orders can only be cancelled up to 24 hours before the collection date. For same-day cancellations, contact support.
4. Check Debit Order Status
Get detailed status information for a specific debit order.
Subject: svc.debit.<entity_id>.status
Request
| Field | Type | Required | Description |
|---|---|---|---|
debit_order_id | string | required | ID of the debit order |
Response
Status Values
scheduled: debit order is scheduled for future collectionprocessing: debit order is being processed by the banksuccessful: funds successfully collectedfailed: collection failed (insufficient funds, closed account, etc.)disputed: customer disputed the debit ordercancelled: debit order was cancelled
Important Notes
Processing Times
- Debit orders must be submitted at least 2 business days before collection date
- Processing typically occurs in the early morning hours (00:00 - 06:00 SAST)
- Final status updates are usually available by 10:00 SAST on collection day
Best Practices
- Always validate bank account details before creating debit orders
- Implement webhook handlers to receive real-time status updates
- Store the
debit_order_idfor tracking and reconciliation - Handle failed debit orders with appropriate retry logic
- Keep mandate documentation up to date and accessible