Documentation/API/Debit Order

Debit Order Service

Subject to change

API reference for creating and managing debit orders. Debit orders allow you to automatically collect payments from customer accounts on scheduled dates.

VERTEX ENGINE

00

Table of Contents

  1. Overview
  2. Create Debit Order
  3. List Debit Orders
  4. Cancel Debit Order
  5. Check Debit Order Status

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
}

Required Fields

  • clientTxId - Unique identifier to prevent duplicate transactions. IDs are stored for 30 days.
  • mandate_reference - The mandate reference number authorizing this debit order
  • amount - Amount in cents (1000 = R10.00)
  • collection_date - Must be at least 2 business days in the future
  • account_type - Either "cheque" or "savings"
  • frequency - Collection frequency: "once_off", "weekly", "monthly", or "annually"

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 organization 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
}

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
}

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
}

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
Previous: CardsNext: Notifications "Webhook"