Direct debits

Direct debits are an agreement between a customer and a business for regular payments. Once the terms of the payments are agreed upon, the business sends a direct debit instruction to the customer's bank, which authorises a payment to be made regularly.

You can use direct debits for purposes such as:

• Regular payments with a varying amount, such as bills.
• Large purchases split out over a series of scheduled payments.
• Subscriptions or donations on a fixed schedule.

Unlike variable recurring payments (VRPs), there are no constraints such as payment limit or validity for a direct debit mandate. This means that payments of any value can be taken through a direct debit mandate, until it's revoked by the user.

Your user interface needs to clearly inform users before each direct debit payment is taken.

Direct debit vs VRP

The integration process for the direct debits is very similar to the one for VRPs. Like VRPs, direct debits are based on a mandate, which you create through the /v3/mandates endpoint. However, there are a few general differences:

• A direct debit mandate creation request requires a remitter parameter instead of the provider selection object.
• There's no end user authorisation flow, which means the mandate immediately enters the authorizing status after you create it.
  Typically it takes 2-3 working days for the BACS scheme to authorise a direct debit.
• You don't need to provide any constraints for a direct debit mandate.

Create a direct debit mandate

The first step to accepting payments over a direct debit is to create a direct_debit mandate.

Direct debit mandate creation request

In more detail, these are the parameters you need to include in a direct debit mandate creation request:

This is an example of a direct debit mandate creation request including the parameters detailed above:

{
  "mandate": {
    "type": "direct_debit",
    "remitter": {
      "account_holder_name": "Remy Turr",
      "account_identifier": {
        "type": "sort_code_account_number",
        "sort_code": "010101",
        "account_number": "12345678"
      },
      "address": {
        "address_line1": "1 Hardwick St",
        "city": "London",
        "state": "London",
        "zip": "EC1R 4RB",
        "country_code": "GB"
      }
    },
    "beneficiary": {
      "type": "merchant_account",
      "merchant_account_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941"
    }
  },
  "currency": "GBP",
  "user": {
    "name": "Remy Turr",
    "email": "[email protected]"
  }
}

Direct debit mandate creation response

If the request is successful, you receive a response as below. It contains the mandate id, the mandate status, and the user id. Unlike a VRP mandate, the response doesn't contain a resource_token, as end user authorisation isn't needed.

{
  "id": "be6db706-68f1-4e9c-ab09-b83d8e3ea60d",
  "status": "authorizing",
  "user": {
    "id": "995993c8-14fb-4a94-8520-519d9e114c7e"
  }
}

Direct debit mandate webhooks

We recommend that you use webhooks to monitor the progress of anything you do with the Payments API. Learn how to set up webhooks for your integration.

There are four webhooks that apply to direct debit mandates.

Three of the webhooks also apply to VRP mandates, but the mandate_remitter_changed webhook only applies to direct debit mandates.

Learn more about mandate webhooks.

mandate_authorized webhook

You receive this webhook when a mandate is authorised. However, direct debits aren't authorised by the end user, but instead by the Bacs scheme. This means it takes 2/3 working days after you create a mandate before it becomes authorised.

This is an example of the mandate_authorized webhook for a direct debit mandate:

{
  "type":"mandate_authorized",
  "event_version":1,
  "event_id":"8d46385c-4769-4ba0-9e90-cf31414709d1",
  "id": "be6db706-68f1-4e9c-ab09-b83d8e3ea60d",
  "authorized_at": "2024-01-30T06:00:36.789001Z"
}

mandate_failed webhook

You receive this webhook when the mandate authorisation process fails. As direct debit mandates are authorised by the Bacs scheme, it can take 2/3 working days until you find out if a mandate failed.

This is an example of the mandate_failed webhook for a direct debit mandate:

{
  "type":"mandate_failed",
  "event_version":1,
  "event_id":"8d46385c-4769-4ba0-9e90-cf31414709d1",
  "id": "be6db706-68f1-4e9c-ab09-b83d8e3ea60d",
  "failed_at": "2024-01-30T06:00:36.789001Z",
  "failure_stage": "authorizing",
  "failure_reason": "invalid_sort_code"
}

mandate_revoked webhook

This webhook tells you when a mandate has been revoked. You can revoke a mandate with the /v3/mandates/{id}/revoke endpoint.

For direct debits, we've added a new revocation_source field to the webhook, which tells you whether you (client)or the bank (provider) have revoked the mandate.

This is an example of the mandate_revoked webhook for a direct debit mandate:

{
  "type":"mandate_revoked",
  "event_version":1,
  "event_id":"8d46385c-4769-4ba0-9e90-cf31414709d1",
  "id": "be6db706-68f1-4e9c-ab09-b83d8e3ea60d",
  "revoked_at": "2024-01-31T06:00:36.789001Z",
  "revocation_source": "provider"
}

mandate_remitter_changed webhook

The mandate_remitter_changed webhook tells you when the remitter bank account for a mandate has changed. This could apply when the user changes their bank account, for example through the Current account switch guarantee.

This is an example of the mandate_remitter_changed webhook for a direct debit mandate:

{
  "type":"mandate_remitter_changed",
  "event_version":1,
  "event_id":"8d46385c-4769-4ba0-9e90-cf31414709d1",
  "id": "be6db706-68f1-4e9c-ab09-b83d8e3ea60d",
  "remitter_changed_at": "2024-01-31T06:00:36.789001Z"
}

Create a payment on a direct debit mandate

The process to create a payment on a direct debit mandate is very similar to the process to create a payment on a VRP mandate. You need to specify a mandate as the payment_method for the payment and also provide personal details about the user, which should match those provided at mandate creation.

{
  "payment_method": {
    "type": "mandate",
    "mandate_id": "be6db706-68f1-4e9c-ab09-b83d8e3ea60d"
  },
  "amount_in_minor": 1,
  "currency": "GBP",
  "user": {
    "name": "Remy Turr",
    "email": "[email protected]"
  }
}

When you create a payment on a direct debit mandate, it should immediately have the authorized status. This is because the payment was authorised through the initial direct debit instruction. This is an example of the response you receive:

{
  "id": "948adeda-e9a5-438a-bdf7-013ef7115a32",
  "user": {
    "id": "be6db706-68f1-4e9c-ab09-b83d8e3ea60d"
  },
  "status": "authorized"
}

Test direct debit payments and mandates

To test different failure scenarios in the sandbox environment, include specific numbers within the remitter's account number:

For individual direct debit payments, you can test different failure scenarios by inputting different payment amounts:

Any other value causes the mandate or payment to move into the authorised and eventually the settled status.

Direct debit-specific payment failure_reasons

There are two payment failure_reasons that are unique to payments over a direct debit:

• payment_disputed: You receive this when a payment because the user has raised an indemnity claim against the direct debit.
• mandate_invalid: You receive this when a mandate is no longer valid to create payments over.

Monitor direct debit payments

Compared to VRPs, it takes longer for direct debits to reach the settled status. This is because direct debit payments are processed through the Bacs scheme, which means they aren't confirmed as settled by the bank for at least 5 working days.

This means it's very important to use webhooks or the GET /v3/payments/{id} endpoint to monitor the progress of any payments made over a direct debit mandate.

Direct debit payment webhooks

A payment over a direct debit can return the same webhooks as most other payments. Learn more about payment webhooks.

However, there is a new payment webhook unique to direct debits, payment_disputed. This indicates that an indemnity claim has been made against the direct debit. This is an example of the payment_disputed webhook:

{
  "type": "payment_disputed",
  "event_version": 1,
  "event_id": "8f8a4988-c47c-4e7c-b8b4-2d04c7593ddb",
  "payment_id": "948adeda-e9a5-438a-bdf7-013ef7115a32",
  "payment_method": {
    "type": "mandate",
    "mandate_id": "be6db706-68f1-4e9c-ab09-b83d8e3ea60d"
  },
  "disputed_at": "2024-01-31T16:22:10.837Z"
}