​
Direct Debit Management Guide

This guide covers everything you need to know about managing direct debit mandates in your Open Banking application. Our direct debit API provides comprehensive tools for creating, managing, and executing recurring payment instructions.

​
Overview

Direct debit management enables automated recurring payments from customer accounts to merchant accounts. This functionality is essential for subscription services, utility payments, and other regular financial obligations. Our API supports the complete direct debit lifecycle from mandate creation to payment execution.

​
Key Direct Debit Operations

​
1. Create Direct Debit Mandate

Create a new direct debit mandate that authorizes recurring payments from a customer’s account to a specified destination account. 
curl -X POST ${API_BASE_URL}/direct-debits \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
  -H "signature: ${SIGNATURE}" \
  -d '{
    "reference": "DD123456789",
    "narration": "Monthly subscription payment",
    "amount": 100.00,
    "start_date": "2024-03-20",
    "end_date": "2025-03-20",
    "frequency": "MONTHLY",
    "destination_bank_code": "044",
    "destination_account": "0987654321",
    "destination_account_name": "Merchant Name Ltd",
    "callback_url": "https://api.merchant.com/webhooks/dd-status/DD123456789",
    "custom_properties": [
      {
        "id": "subscription_id",
        "description": "Subscription identifier",
        "type": "reference",
        "value": "SUB123456"
      }
    ]
  }'

{
  "status": "00",
  "message": "Direct debit created successfully",
  "data": {
    "mandate_status": "ACTIVE",
    "mandate_id": "MAN123456789",
    "next_possible_charge_date": "2024-03-20",
    "custom_properties": [
      {
        "id": "subscription_id",
        "description": "Subscription identifier",
        "type": "reference",
        "value": "SUB123456"
      }
    ]
  }
}

​
2. Get All Direct Debits

Retrieve all direct debit mandates for a customer, providing a comprehensive view of all active and inactive mandates. 
curl -X GET ${API_BASE_URL}/direct-debits \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "signature: ${SIGNATURE}"

{
  "status": "00",
  "message": "Payment successful",
  "data": {
    "mandates": [
      {
        "mandate_status": "ACTIVE",
        "mandate_id": "1234-4567-8901",
        "reference": "DD123456789",
        "narration": "Monthly subscription payment",
        "amount": 100.00,
        "start_date": "2024-03-20",
        "end_date": "2025-03-20",
        "next_possible_charge_date": "2024-11-10",
        "frequency": "MONTHLY",
        "destination_bank_code": "044",
        "destination_account": "0987654321",
        "destination_account_name": "Merchant Name Ltd",
        "callback_url": "https://api.merchant.com/webhooks/dd-status/DD123456789",
        "custom_properties": [
          {
            "id": "subscription_id",
            "description": "Subscription identifier",
            "type": "reference",
            "value": "SUB123456"
          }
        ]
      }
    ]
  }
}

​
3. Update Direct Debit Mandate

Update an existing direct debit mandate to modify its parameters such as amount, frequency, or status. 
curl -X PATCH ${API_BASE_URL}/direct-debits/MAN123456789 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
  -H "signature: ${SIGNATURE}" \
  -d '{
    "mandate_status": "ACTIVE",
    "reference": "DD123456789",
    "narration": "Updated monthly subscription payment",
    "amount": 150.00,
    "start_date": "2024-03-20",
    "end_date": "2025-03-20",
    "frequency": "MONTHLY",
    "destination_bank_code": "044",
    "destination_account": "0987654321",
    "destination_account_name": "Merchant Name Ltd",
    "callback_url": "https://api.merchant.com/webhooks/dd-status/DD123456789",
    "custom_properties": [
      {
        "id": "subscription_id",
        "description": "Updated subscription identifier",
        "type": "reference",
        "value": "SUB123456"
      }
    ]
  }'

{
  "status": "00",
  "message": "Payment successful",
  "data": {
    "mandate_status": "ACTIVE",
    "mandate_id": "1234-4567-8901",
    "next_possible_charge_date": "2024-11-10",
    "custom_properties": [
      {
        "id": "subscription_id",
        "description": "Updated subscription identifier",
        "type": "reference",
        "value": "SUB123456"
      }
    ]
  }
}

​
4. Get Direct Debit by ID

Retrieve a specific direct debit mandate using its unique mandate ID. 
curl -X GET ${API_BASE_URL}/direct-debits/MAN123456789 \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "signature: ${SIGNATURE}"

{
  "status": "00",
  "message": "Payment successful",
  "data": {
    "mandate_status": "ACTIVE",
    "mandate_id": "1234-4567-8901",
    "reference": "DD123456789",
    "narration": "Monthly subscription payment",
    "amount": 100.00,
    "start_date": "2024-03-20",
    "end_date": "2025-03-20",
    "next_possible_charge_date": "2024-11-10",
    "frequency": "MONTHLY",
    "destination_bank_code": "044",
    "destination_account": "0987654321",
    "destination_account_name": "Merchant Name Ltd",
    "callback_url": "https://api.merchant.com/webhooks/dd-status/DD123456789",
    "custom_properties": [
      {
        "id": "subscription_id",
        "description": "Subscription identifier",
        "type": "reference",
        "value": "SUB123456"
      }
    ]
  }
}

​
5. Trigger Direct Debit

Execute a direct debit payment using an existing mandate to process the recurring payment. 
curl -X POST ${API_BASE_URL}/direct-debits/MAN123456789 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
  -H "signature: ${SIGNATURE}" \
  -d '{
    "reference": "DD123456789",
    "narration": "Monthly subscription payment",
    "amount": 100.00,
    "custom_properties": [
      {
        "id": "payment_reference",
        "description": "Payment reference for this transaction",
        "type": "reference",
        "value": "PAY123456"
      }
    ]
  }'

{
  "status": "00",
  "message": "Payment successful",
  "data": {
    "mandate_status": "ACTIVE",
    "mandate_id": "1234-4567-8901",
    "next_possible_charge_date": "2024-11-10",
    "custom_properties": [
      {
        "id": "payment_reference",
        "description": "Payment reference for this transaction",
        "type": "reference",
        "value": "PAY123456"
      }
    ]
  }
}

​
Direct Debit Frequency Types

The direct debit system supports various frequency options for recurring payments:
FrequencyDescription
DAILYExecute payment every day
WEEKLYExecute payment every week
MONTHLYExecute payment every month
QUARTERLYExecute payment every quarter
YEARLYExecute payment every year

​
Mandate Status Types

Direct debit mandates can have different statuses throughout their lifecycle:
StatusDescription
ACTIVEMandate is active and can be used for payments
INACTIVEMandate is inactive and cannot be used for payments

​
Best Practices

​
Mandate Creation

  • Use clear and descriptive narration for customer understanding
  • Set appropriate start and end dates for the mandate
  • Choose the correct frequency based on business requirements
  • Include callback URLs for status notifications
  • Use custom properties for additional tracking

​
Payment Execution

  • Verify mandate status before triggering payments
  • Respect the next possible charge date
  • Implement proper error handling for failed payments
  • Monitor payment success rates and mandate health

​
Customer Communication

  • Provide clear information about mandate terms
  • Notify customers before creating mandates
  • Offer easy cancellation and modification options
  • Maintain transparency about payment schedules
Make sure you send the appropriate scopes while requesting for a token: direct-debits.create, direct-debits.update, direct-debits.list, direct-debits.readonly, and direct-debits.transaction.create. Failure to include these scopes will prevent access to the direct debit management APIs.

​
Next Steps

Now that you understand direct debit management operations, explore these related topics:
Always ensure proper consent and authorization before creating direct debit mandates. Implement robust error handling and maintain detailed audit trails for all direct debit activities. Regular monitoring and compliance with regulatory requirements are essential for successful direct debit implementation.
⌘I