---
title: "Create direct debit mandate"
method: POST
path: "/direct_debit_mandates"
tags: ["Direct Debit Mandates"]
---

# Create direct debit mandate

`POST /direct_debit_mandates`

Create a direct debit mandate.

## Request body

- DirectDebitMandatesCreateDirectDebitMandate
  - `direction` 'outgoing' | 'incoming', required — The direction of the direct debit mandate. An outgoing mandate aims to debit a third-party account, and an incoming mandate aims to debit an internal account. It must be `outgoing` for a corporate connected account.
  - `type` 'sepa_core' | 'sepa_b2b' | 'bacs_debit', required — The type of the direct debit mandate.
  - `connected_account_id` string, uuid, required — The ID of the connected account.
  - `creditor_account` DirectDebitMandatesCreditorAccount — The account to be credited.
    - `account_number` string, required — The account number of the creditor account. See accepted account number formats [here](https://docs.numeral.io/reference/payment-methods). For `bacs_debit` mandates, must be a UK domestic 8-digit account number.
    - `bank_code` string, required — The bank code, for instance BIC / Swift code, UK sort code, or US routing number. For `bacs_debit` mandates, must be a UK sort code (6 digits).
    - `account_number_format` 'iban' | 'uk_account_number' | 'us_account_number' | 'tokenized' | 'other' — The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`. Always present in API responses (empty string when not set).
    - `bank_code_format` 'bic' | 'uk_sorting_code' | 'us_aba_routing_number' | 'tokenized' | 'other' — The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`. Always present in API responses (empty string when not set).
    - `holder_name` string, required — The name of the legal entity or individual holding the account.
    - `creditor_identifier` string, required — The unique reference for organisations collecting payments by SEPA Direct Debit.
    - `holder_address` CommonAddress — The address of the account holder, as an address object.
      - `line_1` string — Line 1.
      - `line_2` string — Line 2.
      - `building_number` string — Building number.
      - `street_name` string — Street name.
      - `postal_code` string — Postal / zip code.
      - `region_state` string — Region or state.
      - `city` string — City.
      - `country` string — ISO 3166 alpha-2 country code.
      - `department` string, nullable — Department name or code.
      - `sub_department` string, nullable — Sub-department name.
      - `building_name` string, nullable — Name of the building.
      - `floor` string, nullable — Floor number or identifier.
      - `postal_box` string, nullable — Postal box.
      - `room` string, nullable — Room number.
      - `city_location_name` string, nullable — Specific city location or landmark.
      - `district_name` string, nullable — District name or administrative region.
  - `originating_account` DirectDebitMandatesOriginatingAccount — The account to be credited.
    - `account_number` string, required — The account number of the originating account. See accepted account number formats [here](https://docs.numeral.io/reference/payment-methods). For `bacs_debit` mandates, must be a UK domestic 8-digit account number.
    - `bank_code` string, required — The bank code, for instance BIC / Swift code, UK sort code, or US routing number. For `bacs_debit` mandates, must be a UK sort code (6 digits).
    - `account_number_format` 'iban' | 'uk_account_number' | 'us_account_number' | 'tokenized' | 'other' — The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`. Always present in API responses (empty string when not set).
    - `bank_code_format` 'bic' | 'uk_sorting_code' | 'us_aba_routing_number' | 'tokenized' | 'other' — The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`. Always present in API responses (empty string when not set).
    - `holder_name` string, required — The name of the legal entity or individual holding the account.
    - `creditor_identifier` string, required — The unique reference for organisations collecting payments by SEPA Direct Debit.
    - `holder_address` CommonAddress — The address of the account holder, as an address object.
      - `line_1` string — Line 1.
      - `line_2` string — Line 2.
      - `building_number` string — Building number.
      - `street_name` string — Street name.
      - `postal_code` string — Postal / zip code.
      - `region_state` string — Region or state.
      - `city` string — City.
      - `country` string — ISO 3166 alpha-2 country code.
      - `department` string, nullable — Department name or code.
      - `sub_department` string, nullable — Sub-department name.
      - `building_name` string, nullable — Name of the building.
      - `floor` string, nullable — Floor number or identifier.
      - `postal_box` string, nullable — Postal box.
      - `room` string, nullable — Room number.
      - `city_location_name` string, nullable — Specific city location or landmark.
      - `district_name` string, nullable — District name or administrative region.
  - `creditor_account_id` string, uuid — The ID of the internal account to be credited. It must be left empty if `creditor_account` parameter is filled. Only supported for outgoing mandates created by financial institution connected accounts.
  - `originating_account_id` string, uuid — The ID of the internal account to be credited. It must be left empty if `originating_account` parameter is filled or if connected account's type is corporate.
  - `debtor_account` DirectDebitMandatesDebtorAccount — The account to be debited. It must be left empty if `debtor_account_id` parameter is filled.
    - `account_number` string, required — The account number of the debtor account. See accepted account number formats [here](https://docs.numeral.io/reference/payment-methods). For `bacs_debit` mandates, must be a UK domestic 8-digit account number.
    - `bank_code` string, required — The bank code, for instance BIC / Swift code, UK sort code, or US routing number. For `bacs_debit` mandates, must be a UK sort code (6 digits).
    - `account_number_format` 'iban' | 'uk_account_number' | 'us_account_number' | 'tokenized' | 'other' — The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`. Always present in API responses (empty string when not set).
    - `bank_code_format` 'bic' | 'uk_sorting_code' | 'us_aba_routing_number' | 'tokenized' | 'other' — The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`. Always present in API responses (empty string when not set).
    - `holder_name` string, required — The name of the legal entity or individual holding the account.
    - `holder_address` CommonAddress — The address of the account holder, as an address object.
      - `line_1` string — Line 1.
      - `line_2` string — Line 2.
      - `building_number` string — Building number.
      - `street_name` string — Street name.
      - `postal_code` string — Postal / zip code.
      - `region_state` string — Region or state.
      - `city` string — City.
      - `country` string — ISO 3166 alpha-2 country code.
      - `department` string, nullable — Department name or code.
      - `sub_department` string, nullable — Sub-department name.
      - `building_name` string, nullable — Name of the building.
      - `floor` string, nullable — Floor number or identifier.
      - `postal_box` string, nullable — Postal box.
      - `room` string, nullable — Room number.
      - `city_location_name` string, nullable — Specific city location or landmark.
      - `district_name` string, nullable — District name or administrative region.
  - `receiving_account` DirectDebitMandatesReceivingAccount — The account to be debited. It must be left empty if `receiving_account_id` parameter is filled.
    - `account_number` string, required — The account number of the originating account. See accepted account number formats [here](https://docs.numeral.io/reference/payment-methods). For `bacs_debit` mandates, must be a UK domestic 8-digit account number.
    - `bank_code` string, required — The bank code, for instance BIC / Swift code, UK sort code, or US routing number. For `bacs_debit` mandates, must be a UK sort code (6 digits).
    - `account_number_format` 'iban' | 'uk_account_number' | 'us_account_number' | 'tokenized' | 'other' — The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`. Always present in API responses (empty string when not set).
    - `bank_code_format` 'bic' | 'uk_sorting_code' | 'us_aba_routing_number' | 'tokenized' | 'other' — The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`. Always present in API responses (empty string when not set).
    - `holder_name` string, required — The name of the legal entity or individual holding the account.
    - `holder_address` CommonAddress — The address of the account holder, as an address object.
      - `line_1` string — Line 1.
      - `line_2` string — Line 2.
      - `building_number` string — Building number.
      - `street_name` string — Street name.
      - `postal_code` string — Postal / zip code.
      - `region_state` string — Region or state.
      - `city` string — City.
      - `country` string — ISO 3166 alpha-2 country code.
      - `department` string, nullable — Department name or code.
      - `sub_department` string, nullable — Sub-department name.
      - `building_name` string, nullable — Name of the building.
      - `floor` string, nullable — Floor number or identifier.
      - `postal_box` string, nullable — Postal box.
      - `room` string, nullable — Room number.
      - `city_location_name` string, nullable — Specific city location or landmark.
      - `district_name` string, nullable — District name or administrative region.
  - `debtor_account_id` string, uuid — The ID of the account to be debited. For outgoing mandates, it can be an external account ID. For incoming mandates it can be an internal account ID, however it only applies to financial institutions. A `debtor_account_id` cannot be used if the `debtor_account` property is already filled.
  - `receiving_account_id` string, uuid — The ID of the external account to be debited. It must be left empty if `receiving_account` parameter is filled.
  - `sequence` 'one_off' | 'recurring' — Deprecated, use `frequency` instead.
  - `frequency` 'one_off' | 'recurring' — The frequency of the direct debit mandate. Mandatory when type is `sepa_core` or `sepa_b2b`. Not applicable for `bacs_debit` mandates.
  - `generate_mandate_reference` boolean — When `generate_mandate_reference` is `true`, Numeral automatically generates a unique mandate reference. Default value is `false`.
  - `reference` string — The reference of the direct debit mandate. It must be empty if `generate_mandate_reference` is `true`.
  - `signature_date` string — The signature date of the direct debit mandate.
  - `metadata` object — Additional client data in JSON format. See [Metadata](https://docs.numeral.io/reference/metadata).
  - `custom_fields` CommonCustomFields — Custom fields in JSON `key:value` format. See [Custom fields](https://docs.numeral.io/reference/custom-fields).

## Response `200`

200

- DirectDebitMandatesDirectDebitMandate
  - `id` string, uuid, required — The UUID of the direct debit mandate.
  - `object` string, required — Type of the object, `direct_debit_mandate`.
  - `direction` 'outgoing' | 'incoming', required — The direction of the direct debit mandate.
  - `type` 'sepa_core' | 'sepa_b2b' | 'bacs_debit', required — The type of the direct debit mandate.
  - `status` 'active' | 'blocked' | 'canceled' | 'disabled' | 'expired' | 'pending_review' | 'rejected', required — The status of the direct debit mandate.
  - `connected_account_id` string, uuid, required — The ID of the connected account.
  - `creditor_account` DirectDebitMandatesCreditorAccount — The account to be credited.
    - `account_number` string, required — The account number of the creditor account. See accepted account number formats [here](https://docs.numeral.io/reference/payment-methods). For `bacs_debit` mandates, must be a UK domestic 8-digit account number.
    - `bank_code` string, required — The bank code, for instance BIC / Swift code, UK sort code, or US routing number. For `bacs_debit` mandates, must be a UK sort code (6 digits).
    - `account_number_format` 'iban' | 'uk_account_number' | 'us_account_number' | 'tokenized' | 'other' — The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`. Always present in API responses (empty string when not set).
    - `bank_code_format` 'bic' | 'uk_sorting_code' | 'us_aba_routing_number' | 'tokenized' | 'other' — The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`. Always present in API responses (empty string when not set).
    - `holder_name` string, required — The name of the legal entity or individual holding the account.
    - `creditor_identifier` string, required — The unique reference for organisations collecting payments by SEPA Direct Debit.
    - `holder_address` CommonAddress — The address of the account holder, as an address object.
      - `line_1` string — Line 1.
      - `line_2` string — Line 2.
      - `building_number` string — Building number.
      - `street_name` string — Street name.
      - `postal_code` string — Postal / zip code.
      - `region_state` string — Region or state.
      - `city` string — City.
      - `country` string — ISO 3166 alpha-2 country code.
      - `department` string, nullable — Department name or code.
      - `sub_department` string, nullable — Sub-department name.
      - `building_name` string, nullable — Name of the building.
      - `floor` string, nullable — Floor number or identifier.
      - `postal_box` string, nullable — Postal box.
      - `room` string, nullable — Room number.
      - `city_location_name` string, nullable — Specific city location or landmark.
      - `district_name` string, nullable — District name or administrative region.
  - `creditor_account_id` string, uuid — The ID of the internal account to be credited. Only filled in the case of outgoing mandates created by financial institution connected accounts.
  - `creditor_account_type` 'internal_account' — The type of the account that `creditor_account_id` is referencing.
  - `debtor_account` DirectDebitMandatesDebtorAccount — The account to be debited. It must be left empty if `debtor_account_id` parameter is filled.
    - `account_number` string, required — The account number of the debtor account. See accepted account number formats [here](https://docs.numeral.io/reference/payment-methods). For `bacs_debit` mandates, must be a UK domestic 8-digit account number.
    - `bank_code` string, required — The bank code, for instance BIC / Swift code, UK sort code, or US routing number. For `bacs_debit` mandates, must be a UK sort code (6 digits).
    - `account_number_format` 'iban' | 'uk_account_number' | 'us_account_number' | 'tokenized' | 'other' — The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`. Always present in API responses (empty string when not set).
    - `bank_code_format` 'bic' | 'uk_sorting_code' | 'us_aba_routing_number' | 'tokenized' | 'other' — The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`. Always present in API responses (empty string when not set).
    - `holder_name` string, required — The name of the legal entity or individual holding the account.
    - `holder_address` CommonAddress — The address of the account holder, as an address object.
      - `line_1` string — Line 1.
      - `line_2` string — Line 2.
      - `building_number` string — Building number.
      - `street_name` string — Street name.
      - `postal_code` string — Postal / zip code.
      - `region_state` string — Region or state.
      - `city` string — City.
      - `country` string — ISO 3166 alpha-2 country code.
      - `department` string, nullable — Department name or code.
      - `sub_department` string, nullable — Sub-department name.
      - `building_name` string, nullable — Name of the building.
      - `floor` string, nullable — Floor number or identifier.
      - `postal_box` string, nullable — Postal box.
      - `room` string, nullable — Room number.
      - `city_location_name` string, nullable — Specific city location or landmark.
      - `district_name` string, nullable — District name or administrative region.
  - `debtor_account_id` string, uuid — The ID of the account (internal or external) to be debited.
  - `debtor_account_type` 'internal_account' | 'external_account' — The type of the account that `debtor_account_id` is referencing.
  - `originating_account` DirectDebitMandatesOriginatingAccount, required — The account to be credited.
    - `account_number` string, required — The account number of the originating account. See accepted account number formats [here](https://docs.numeral.io/reference/payment-methods). For `bacs_debit` mandates, must be a UK domestic 8-digit account number.
    - `bank_code` string, required — The bank code, for instance BIC / Swift code, UK sort code, or US routing number. For `bacs_debit` mandates, must be a UK sort code (6 digits).
    - `account_number_format` 'iban' | 'uk_account_number' | 'us_account_number' | 'tokenized' | 'other' — The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`. Always present in API responses (empty string when not set).
    - `bank_code_format` 'bic' | 'uk_sorting_code' | 'us_aba_routing_number' | 'tokenized' | 'other' — The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`. Always present in API responses (empty string when not set).
    - `holder_name` string, required — The name of the legal entity or individual holding the account.
    - `creditor_identifier` string, required — The unique reference for organisations collecting payments by SEPA Direct Debit.
    - `holder_address` CommonAddress — The address of the account holder, as an address object.
      - `line_1` string — Line 1.
      - `line_2` string — Line 2.
      - `building_number` string — Building number.
      - `street_name` string — Street name.
      - `postal_code` string — Postal / zip code.
      - `region_state` string — Region or state.
      - `city` string — City.
      - `country` string — ISO 3166 alpha-2 country code.
      - `department` string, nullable — Department name or code.
      - `sub_department` string, nullable — Sub-department name.
      - `building_name` string, nullable — Name of the building.
      - `floor` string, nullable — Floor number or identifier.
      - `postal_box` string, nullable — Postal box.
      - `room` string, nullable — Room number.
      - `city_location_name` string, nullable — Specific city location or landmark.
      - `district_name` string, nullable — District name or administrative region.
  - `originating_account_id` string, uuid — The ID of the internal account to be credited.
  - `receiving_account` DirectDebitMandatesReceivingAccount, required — The account to be debited. It must be left empty if `receiving_account_id` parameter is filled.
    - `account_number` string, required — The account number of the originating account. See accepted account number formats [here](https://docs.numeral.io/reference/payment-methods). For `bacs_debit` mandates, must be a UK domestic 8-digit account number.
    - `bank_code` string, required — The bank code, for instance BIC / Swift code, UK sort code, or US routing number. For `bacs_debit` mandates, must be a UK sort code (6 digits).
    - `account_number_format` 'iban' | 'uk_account_number' | 'us_account_number' | 'tokenized' | 'other' — The format of the account number. When set, it must match `account_number` unless the format is `other` or `tokenized`. Always present in API responses (empty string when not set).
    - `bank_code_format` 'bic' | 'uk_sorting_code' | 'us_aba_routing_number' | 'tokenized' | 'other' — The format of the bank code. When set, it must match `bank_code` unless the format is `other` or `tokenized`. Always present in API responses (empty string when not set).
    - `holder_name` string, required — The name of the legal entity or individual holding the account.
    - `holder_address` CommonAddress — The address of the account holder, as an address object.
      - `line_1` string — Line 1.
      - `line_2` string — Line 2.
      - `building_number` string — Building number.
      - `street_name` string — Street name.
      - `postal_code` string — Postal / zip code.
      - `region_state` string — Region or state.
      - `city` string — City.
      - `country` string — ISO 3166 alpha-2 country code.
      - `department` string, nullable — Department name or code.
      - `sub_department` string, nullable — Sub-department name.
      - `building_name` string, nullable — Name of the building.
      - `floor` string, nullable — Floor number or identifier.
      - `postal_box` string, nullable — Postal box.
      - `room` string, nullable — Room number.
      - `city_location_name` string, nullable — Specific city location or landmark.
      - `district_name` string, nullable — District name or administrative region.
  - `receiving_account_id` string, uuid — The ID of the account (internal or external) to be debited.
  - `sequence` 'one_off' | 'recurring' — Deprecated, use `frequency` instead.
  - `frequency` 'one_off' | 'recurring' — The frequency of the direct debit mandate. Populated for SEPA mandates (`sepa_core`, `sepa_b2b`); not applicable for `bacs_debit` mandates.
  - `reference` string, required — The reference of the direct debit mandate.
  - `signature_date` string — The signature date of the direct debit mandate.
  - `last_debit_collection_date` string, date, nullable — The date of the last direct debit collection processed against this mandate. Updated automatically when a direct debit collection is received.
  - `expiry_date` string, date, nullable — The date after which the mandate is expired and cannot be used for subsequent direct debit collections. For SEPA mandates, this is 36 months after `last_debit_collection_date`. For Bacs mandates, this depends on the bank's mandate validity period configuration; if not configured, the value is `null` (no expiry).
  - `metadata` object, required — Additional client data in JSON format. See [Metadata](https://docs.numeral.io/reference/metadata).
  - `custom_fields` CommonCustomFields — Custom fields in JSON `key:value` format. See [Custom fields](https://docs.numeral.io/reference/custom-fields).
  - `created_at` string, date-time, required — The UTC timestamp of the creation of this direct debit mandate.
  - `bank_data` object — Bank data exposed for the mandate. Populated for schemes where a registration message is sent to the bank — currently Bacs (AUDDIS).
    - `message_id` string — ID of the message that registered the mandate at the bank.

## Other responses

- `400` — Validation error.
- `409` — Conflict.
- `415` — Unsupported Media Type.

---

[API](https://skmtc.net/numeral/apis/payments.md) · [All operations](https://skmtc.net/numeral/apis/payments/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/numeral/payments/revisions/220f101cc2ef/schema)