Creating Direct Debits

Let's assume you want to receive €100 from a client for a specific invoice using SEPA Direct Debit. In order to start pulling funds from an account you will need a signed direct debit mandate (instruction) from your client. We can manage those for you, or you are welcome to manage them yourself. If you would like to know more about direct debits and mandates feel free to reach out to us at [email protected]

Before making requests, you will need your API Key, and source account ID.

1. Retrieve your account ID

📘

Sources & Account IDs

Payable uses the term accounts or sources to refer to your bank accounts.

When you create a Direct Debit, you must tell us the creditor bank account. This is the account which will be receiving funds.

If you want to Get an account , you can use the following request:

curl --request GET \
     --url https://api.payable.co/accounts/id \
     --header 'accept: application/json'

{
  "id": "acc_buqtzoruk7x44iqdn3zmxt26iu",
  "label": "string",
  "currency": "EUR",
  "type": "bank",
  "references": [
    "customer-invoice-123"
  ],
  "institution_id": "string",
  "connection_ids": [
    "con_buea4ma3bszo5vojc46jsv7rcm"
  ],
  "links": [
    {
      "href": "https://api.payable.co/accounts/acc_buqtzoruk7x44iqdn3zmxt26iu",
      "rel": "self",
      "method": "GET"
    }
  ]
}

2. Setup the account you will be requesting funds from

For the next step you will setup a the bank account details from which you will request the funds and credit your account.

You will use the payee endpoint to add your client's bank details including the account holder name, IBAN, SWIFT-BIC and what type of account is it business or personal.

Make a note of the Payee Id as we will need it later to setup a mandate in the Payable Platform.

You can use the below request to create a payee

curl --location 'https://api.payable.co/payees' \
--header 'X-Idempotency-Key: 8dc85ad2-f53e-4c7f-aee2-dee18b28247c' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <API-KEY>' \
--data '{
  "account_holder_details": {
    "name": "Client account holder"
  },
  "bank_details": {
    "type": "business",
    "iban": "GB29NWBK60161331926819",
    "bic": "HBUKGB4BXXX"
  },
  "name": "client-bank-account"
}'

{
  "id": "pye_r28xivvv1sb9e1xt1uj0v8aiyc",
  "organization_id": "org_bk3hiupv6okidhhbsmhf6p7z2u",
  "links": [
    {
      "href": "https://api.payable.co/payees/pye_r28xivvv1sb9e1xt1uj0v8aiyc",
      "rel": "self",
      "method": "GET"
    }
  ]
}

3. Setup the mandate

Once the payee is setup we can then setup the mandate. If you are managing your own mandates then the property setup_with_bank will need to be set to false, otherwise if we manage mandates for you then setup_with_bank will need to be true.

Note: If you are managing the mandates on your own, then signed_date will be required.

You will now use the Payee Id and account Id you obtained earlier to setup a mandate in the Payable platform.

If the Payee account is a business account then the scheme will be sepa_b2b otherwise it will be sepa_core.

If you are setting up direct debits outside the SEPA network, then the appropriate scheme will need to be used.

The request below will allow you to create a mandate

curl --location 'https://api.payable.co/mandates' \
--header 'X-Idempotency-Key: 52773bc8-072f-49e1-8942-80a2787c6f49' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <API-KEY>' \
--data '{
    "entity_id": "ent_bjec24xmzi4tr4g7m4lliotzz4",
    "scheme": "sepa_b2b",
    "debtor_id": "pye_r28xivvv1sb9e1xt1uj0v8aiyc",
    "creditor_id": "acc_buqtzoruk7x44iqdn3zmxt26iu",
    "reference": "Customer-Invoicing",
    "signed_date": "2024-01-31T03:04:05Z",
    "setup_with_bank": false
}'

{
  "id": "man_a2xdxrf5oyk4fdnhgheytqc7w4",
  "entity_id": "ent_bjec24xmzi4tr4g7m4lliotzz4",
  "status": "created",
  "reference": "ref-12345",
  "links": [
    {
      "href": "https://api.payable.co/mandates/man_a2xdxrf5oyk4fdnhgheytqc7w4",
      "rel": "self",
      "method": "GET"
    }
  ]
}

4. Create the direct debit

Once the mandate is setup, you can create a direct debit by supplying the mandate Id along with the amount, currency, a reference that will show up on the bank statement, and a unique reference to link back to your own system.

We use the details in the mandate you setup earlier to identify the correct creditor and debtor accounts, so you don't have to constantly supply the same bank details whenever creating a direct debit.

Lastly to create Create a direct debit you can use the request below.

curl --location 'https://api.payable.co/direct-debits' \
--header 'X-Idempotency-Key: a2b100aa-9e41-4a08-9a39-eeed24d51301' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <API-KEY>' \
--data '{
  "amount": {
    "value": "100",
    "currency": "EUR"
  },
  "mandate_id": "man_a2xdxrf5oyk4fdnhgheytqc7w4",
  "reference": "Invoice-Payment",
  "external_id": "Invoice-12345"
}'

{
  "id": "ddi_ndp7XjILxS8fDvjz7akVOJ7mgV",
  "status": "created",
  "entity_id": "ent_bjec24xmzi4tr4g7m4lliotzz4",
  "debtor_id": "pye_r28xivvv1sb9e1xt1uj0v8aiyc",
  "creditor_id": "acc_buqtzoruk7x44iqdn3zmxt26iu",
  "links": [
    {
      "href": "https://api.payable.co/direct-debits/ddi_ndp7XjILxS8fDvjz7akVOJ7mgV",
      "rel": "self",
      "method": "GET"
    }
  ]
}