> ## Documentation Index
> Fetch the complete documentation index at: https://docs-sandbox.sparkle.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Direct Debit Management

> Learn how to manage direct debit mandates and implement recurring payment flows

## 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.

<Accordion title="Sample Request">
  <CodeGroup>
    ```bash cURL theme={null}
    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"
          }
        ]
      }'
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Sample Response">
  ```json theme={null}
  {
    "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"
        }
      ]
    }
  }
  ```
</Accordion>

### 2. Get All Direct Debits

Retrieve all direct debit mandates for a customer, providing a comprehensive view of all active and inactive mandates.

<Accordion title="Sample Request">
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X GET ${API_BASE_URL}/direct-debits \
      -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
      -H "signature: ${SIGNATURE}"
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Sample Response">
  ```json theme={null}
  {
    "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"
            }
          ]
        }
      ]
    }
  }
  ```
</Accordion>

### 3. Update Direct Debit Mandate

Update an existing direct debit mandate to modify its parameters such as amount, frequency, or status.

<Accordion title="Sample Request">
  <CodeGroup>
    ```bash cURL theme={null}
    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"
          }
        ]
      }'
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Sample Response">
  ```json theme={null}
  {
    "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"
        }
      ]
    }
  }
  ```
</Accordion>

### 4. Get Direct Debit by ID

Retrieve a specific direct debit mandate using its unique mandate ID.

<Accordion title="Sample Request">
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X GET ${API_BASE_URL}/direct-debits/MAN123456789 \
      -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
      -H "signature: ${SIGNATURE}"
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Sample Response">
  ```json theme={null}
  {
    "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"
        }
      ]
    }
  }
  ```
</Accordion>

### 5. Trigger Direct Debit

Execute a direct debit payment using an existing mandate to process the recurring payment.

<Accordion title="Sample Request">
  <CodeGroup>
    ```bash cURL theme={null}
    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"
          }
        ]
      }'
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Sample Response">
  ```json theme={null}
  {
    "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"
        }
      ]
    }
  }
  ```
</Accordion>

## Direct Debit Frequency Types

The direct debit system supports various frequency options for recurring payments:

| Frequency     | Description                   |
| ------------- | ----------------------------- |
| **DAILY**     | Execute payment every day     |
| **WEEKLY**    | Execute payment every week    |
| **MONTHLY**   | Execute payment every month   |
| **QUARTERLY** | Execute payment every quarter |
| **YEARLY**    | Execute payment every year    |

## Mandate Status Types

Direct debit mandates can have different statuses throughout their lifecycle:

| Status       | Description                                         |
| ------------ | --------------------------------------------------- |
| **ACTIVE**   | Mandate is active and can be used for payments      |
| **INACTIVE** | Mandate 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

<Note>
  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.
</Note>

## Next Steps

Now that you understand direct debit management operations, explore these related topics:

* [Developer Onboarding](/guides/developer-onboarding) - Onboard Developer
* [Customer Management](/guides/customers) - Manage customer information and relationships
* [Account Management](/guides/account) - Manage bank accounts and balances
* [Transfers](/guides/transfers) - Process money transfers between accounts
* [Bill Payment](/guides/bill-payment) - Process utility and bill payments
* [Card Management](/guides/card-management) - Manage Payment Cards
* [Dispute Management](/guides/dispute-management) - Manage Payment Cards
* [Savings Information](/guides/savings-information) - Manage Payment Cards
* [Loan Information](/guides/loans) - Access customer Loan Information

<Button href="/api-reference/registration" size="sm">
  Explore API Reference
</Button>

<Note>
  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.
</Note>