API References

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

{
  "clientTxId": "string",          // Required: unique transaction ID to prevent duplicates
  "mandate_reference": "string",   // Required: mandate reference number
  "amount": 0,                     // Required: amount in cents (ie. 1000 == ZAR 10.00)
  "collection_date": "2024-01-15", // 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 chars)
  "frequency": "string",           // Required: "once_off", "weekly", "monthly", "annually"
  "end_date": "2024-12-31",        // Optional: end date for recurring debits
  "tracking_days": 10,             // Optional: number of days to track (default: 10)
  "notification_email": "string",  // Optional: email for notifications
  "metadata": {}                   // Optional: additional data for your reference
}
FieldTypeRequiredDescription
clientTxIdstringrequiredUnique transaction ID to prevent duplicate transactions
mandate_referencestringrequiredMandate reference number authorizing this debit order
amountnumberrequiredAmount in cents (i.e. 1000 == ZAR 10.00)
collection_datestringrequiredDate to collect the debit order (YYYY-MM-DD)
account_holder_namestringrequiredAccount holder's full name
account_numberstringrequiredBank account number
account_typestringrequired"cheque" or "savings"
branch_codestringrequiredBank branch code
referencestringrequiredPayment reference (max 20 characters)
frequencystringrequired"once_off", "weekly", "monthly", or "annually"
end_datestringoptionalEnd date for recurring debit orders
tracking_daysnumberoptionalNumber of days to track the debit order status (default: 10)
notification_emailstringoptionalEmail address for notifications
metadataobjectoptionalAdditional data for your reference

Optional Fields

  • end_date: required for recurring debit orders
  • tracking_days: days to track the debit order status (default: 10, max: 30)
  • metadata: store additional information (max 1KB)

Response

{
  "debit_order_id": "do_1a2b3c4d5e6f",
  "status": "scheduled",
  "collection_date": "2024-01-15",
  "amount": "10000",
  "reference": "INV-12345"
}

Possible Errors

  • 400 Bad Request: Invalid request data | Invalid collection date | Invalid mandate
  • 401 Unauthorized: Authentication failed
  • 409 Conflict: Duplicate transaction ID
  • 422 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

{
  "status": "string",        // Optional: filter by status: "scheduled", "processing", "successful", "failed"
  "from_date": "2024-01-01", // Optional: start date for filtering
  "to_date": "2024-01-31",   // Optional: end date for filtering
  "limit": 100,              // Optional: number of results (default: 100, max: 1000)
  "offset": 0                // Optional: pagination offset
}
FieldTypeRequiredDescription
statusstringoptionalFilter by status: "scheduled", "processing", "successful", or "failed"
from_datestringoptionalStart date for filtering
to_datestringoptionalEnd date for filtering
limitnumberoptionalNumber of results to return (default: 100, max: 1000)
offsetnumberoptionalPagination offset

Response

{
  "debit_orders": [
    {
      "debit_order_id": "do_1a2b3c4d5e6f",
      "clientTxId": "unique-tx-123",
      "mandate_reference": "MAND-12345",
      "amount": 10000,
      "status": "successful",
      "collection_date": "2024-01-15",
      "processed_date": "2024-01-15T06:00:00Z",
      "reference": "INV-12345",
      "account_holder_name": "John Doe",
      "frequency": "monthly",
      "next_collection_date": "2024-02-15",
      "created_at": "2024-01-10T10:30:00Z"
    }
  ],
  "total": 150,
  "limit": 100,
  "offset": 0
}

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

{
  "debit_order_id": "do_1a2b3c4d5e6f", // Required: ID of the debit order to cancel
  "reason": "string"                    // Optional: reason for cancellation
}
FieldTypeRequiredDescription
debit_order_idstringrequiredID of the debit order to cancel
reasonstringoptionalReason for cancellation

Response

{
  "debit_order_id": "do_1a2b3c4d5e6f",
  "status": "cancelled",
  "cancelled_at": "2024-01-14T10:30:00Z"
}

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

{
  "debit_order_id": "do_1a2b3c4d5e6f" // Required: ID of the debit order
}
FieldTypeRequiredDescription
debit_order_idstringrequiredID of the debit order

Response

{
  "debit_order_id": "do_1a2b3c4d5e6f",
  "status": "successful",
  "status_history": [
    {
      "status": "scheduled",
      "timestamp": "2024-01-10T10:30:00Z",
      "description": "Debit order created and scheduled"
    },
    {
      "status": "processing",
      "timestamp": "2024-01-15T00:00:00Z",
      "description": "Debit order sent to bank for processing"
    },
    {
      "status": "successful",
      "timestamp": "2024-01-15T06:00:00Z",
      "description": "Debit order successfully collected",
      "bank_reference": "BANK123456"
    }
  ],
  "amount": 10000,
  "collection_date": "2024-01-15",
  "processed_date": "2024-01-15T06:00:00Z",
  "bank_charges": 150,
  "net_amount": 9850
}

Status Values

  • scheduled: debit order is scheduled for future collection
  • processing: debit order is being processed by the bank
  • successful: funds successfully collected
  • failed: collection failed (insufficient funds, closed account, etc.)
  • disputed: customer disputed the debit order
  • cancelled: 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_id for tracking and reconciliation
  • Handle failed debit orders with appropriate retry logic
  • Keep mandate documentation up to date and accessible

On this page