Sign in

v1

latestOpenAPI 3.1.02026-07-24180245513.9 KB
Direct Debit Mandates

Create direct debit mandate

Create a direct debit mandate.

post/direct_debit_mandates

Request body

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_idstring uuid required

The ID of the connected account.

creditor_account_idstring 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_idstring 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_idstring 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_idstring 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_referenceboolean

When generate_mandate_reference is true, Numeral automatically generates a unique mandate reference. Default value is false.

referencestring

The reference of the direct debit mandate. It must be empty if generate_mandate_reference is true.

signature_datestring

The signature date of the direct debit mandate.

metadataobject

Additional client data in JSON format. See Metadata.

custom_fieldsCommonCustomFields

Custom fields in JSON key:value format. See Custom fields.

Example request

{
  "direction": "outgoing",
  "type": "sepa_core",
  "connected_account_id": "ff1714ae-3ec8-450d-984c-c6ee44c82a88",
  "creditor_account": {
    "account_number": "FR7601234567890627967100010",
    "bank_code": "SOGEFRPP",
    "holder_name": "SoftwareCo",
    "creditor_identifier": "FR12ZZZ123456",
    "holder_address": {
      "line_1": "1, place de la Concorde",
      "building_number": "1",
      "street_name": "place de la Concorde",
      "postal_code": "75008",
      "city": "Paris",
      "country": "FR",
      "department": "Marketing",
      "sub_department": "Content team",
      "building_name": "Bat. 4",
      "floor": "3",
      "postal_box": "67b",
      "room": "47",
      "city_location_name": "Confluences",
      "district_name": "District 9"
    }
  },
  "originating_account": {
    "account_number": "FR7601234567890627967100010",
    "bank_code": "SOGEFRPP",
    "holder_name": "SoftwareCo",
    "creditor_identifier": "FR12ZZZ123456",
    "holder_address": {
      "line_1": "1, place de la Concorde",
      "building_number": "1",
      "street_name": "place de la Concorde",
      "postal_code": "75008",
      "city": "Paris",
      "country": "FR",
      "department": "Marketing",
      "sub_department": "Content team",
      "building_name": "Bat. 4",
      "floor": "3",
      "postal_box": "67b",
      "room": "47",
      "city_location_name": "Confluences",
      "district_name": "District 9"
    }
  },
  "creditor_account_id": "b38f5318-a389-4278-9cbe-d16116750982",
  "originating_account_id": "b38f5318-a389-4278-9cbe-d16116750982",
  "debtor_account": {
    "account_number": "FR7601234567891127967100082",
    "bank_code": "BNPAFRPPXXX",
    "holder_name": "PartnerCo",
    "holder_address": {
      "line_1": "1, place de la Concorde",
      "building_number": "1",
      "street_name": "place de la Concorde",
      "postal_code": "75008",
      "city": "Paris",
      "country": "FR",
      "department": "Marketing",
      "sub_department": "Content team",
      "building_name": "Bat. 4",
      "floor": "3",
      "postal_box": "67b",
      "room": "47",
      "city_location_name": "Confluences",
      "district_name": "District 9"
    }
  },
  "receiving_account": {
    "account_number": "FR7601234567891127967100082",
    "bank_code": "BNPAFRPPXXX",
    "holder_name": "PartnerCo",
    "holder_address": {
      "line_1": "1, place de la Concorde",
      "building_number": "1",
      "street_name": "place de la Concorde",
      "postal_code": "75008",
      "city": "Paris",
      "country": "FR",
      "department": "Marketing",
      "sub_department": "Content team",
      "building_name": "Bat. 4",
      "floor": "3",
      "postal_box": "67b",
      "room": "47",
      "city_location_name": "Confluences",
      "district_name": "District 9"
    }
  },
  "debtor_account_id": "d95fbdf7-90a7-4026-9597-3a7ecd0e819f",
  "receiving_account_id": "b38f5318-a389-4278-9cbe-d16116750982",
  "sequence": "recurring",
  "frequency": "recurring",
  "reference": "some reference",
  "signature_date": "2023-05-31",
  "metadata": {
    "property_a": true,
    "property_b": "some text"
  }
}

Response

200

idstring uuid required

The UUID of the direct debit mandate.

objectstring 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_idstring uuid required

The ID of the connected account.

creditor_account_idstring 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_idstring 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_idstring uuid

The ID of the internal account to be credited.

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

referencestring required

The reference of the direct debit mandate.

signature_datestring

The signature date of the direct debit mandate.

last_debit_collection_datestring date nullable

The date of the last direct debit collection processed against this mandate. Updated automatically when a direct debit collection is received.

expiry_datestring 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).

metadataobject required

Additional client data in JSON format. See Metadata.

custom_fieldsCommonCustomFields

Custom fields in JSON key:value format. See Custom fields.

created_atstring date-time required

The UTC timestamp of the creation of this direct debit mandate.

Example response

{
  "direction": "outgoing",
  "type": "sepa_core",
  "status": "active",
  "connected_account_id": "ff1714ae-3ec8-450d-984c-c6ee44c82a88",
  "creditor_account": {
    "account_number": "FR7601234567890627967100010",
    "bank_code": "SOGEFRPP",
    "holder_name": "SoftwareCo",
    "creditor_identifier": "FR12ZZZ123456",
    "holder_address": {
      "line_1": "1, place de la Concorde",
      "building_number": "1",
      "street_name": "place de la Concorde",
      "postal_code": "75008",
      "city": "Paris",
      "country": "FR",
      "department": "Marketing",
      "sub_department": "Content team",
      "building_name": "Bat. 4",
      "floor": "3",
      "postal_box": "67b",
      "room": "47",
      "city_location_name": "Confluences",
      "district_name": "District 9"
    }
  },
  "creditor_account_id": "2c524087-20ae-437e-948c-f673b0757821",
  "creditor_account_type": "internal_account",
  "debtor_account": {
    "account_number": "FR7601234567891127967100082",
    "bank_code": "BNPAFRPPXXX",
    "holder_name": "PartnerCo",
    "holder_address": {
      "line_1": "1, place de la Concorde",
      "building_number": "1",
      "street_name": "place de la Concorde",
      "postal_code": "75008",
      "city": "Paris",
      "country": "FR",
      "department": "Marketing",
      "sub_department": "Content team",
      "building_name": "Bat. 4",
      "floor": "3",
      "postal_box": "67b",
      "room": "47",
      "city_location_name": "Confluences",
      "district_name": "District 9"
    }
  },
  "debtor_account_id": "b38f5318-a389-4278-9cbe-d16116750982",
  "debtor_account_type": "external_account",
  "originating_account": {
    "account_number": "FR7601234567890627967100010",
    "bank_code": "SOGEFRPP",
    "holder_name": "SoftwareCo",
    "creditor_identifier": "FR12ZZZ123456",
    "holder_address": {
      "line_1": "1, place de la Concorde",
      "building_number": "1",
      "street_name": "place de la Concorde",
      "postal_code": "75008",
      "city": "Paris",
      "country": "FR",
      "department": "Marketing",
      "sub_department": "Content team",
      "building_name": "Bat. 4",
      "floor": "3",
      "postal_box": "67b",
      "room": "47",
      "city_location_name": "Confluences",
      "district_name": "District 9"
    }
  },
  "originating_account_id": "2c524087-20ae-437e-948c-f673b0757821",
  "receiving_account": {
    "account_number": "FR7601234567891127967100082",
    "bank_code": "BNPAFRPPXXX",
    "holder_name": "PartnerCo",
    "holder_address": {
      "line_1": "1, place de la Concorde",
      "building_number": "1",
      "street_name": "place de la Concorde",
      "postal_code": "75008",
      "city": "Paris",
      "country": "FR",
      "department": "Marketing",
      "sub_department": "Content team",
      "building_name": "Bat. 4",
      "floor": "3",
      "postal_box": "67b",
      "room": "47",
      "city_location_name": "Confluences",
      "district_name": "District 9"
    }
  },
  "receiving_account_id": "b38f5318-a389-4278-9cbe-d16116750982",
  "sequence": "recurring",
  "frequency": "recurring",
  "reference": "some reference",
  "signature_date": "2023-05-31",
  "last_debit_collection_date": "2024-03-15",
  "expiry_date": "2027-03-15",
  "metadata": {
    "property_a": true,
    "property_b": "some text"
  },
  "created_at": "2023-06-07T08:49:54.54422Z",
  "bank_data": {
    "message_id": "ABCDEF"
  }
}