Direct debits
Use direct debits to regularly accept payments from customers based on agreed terms.
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:
Parameter | Description |
---|---|
mandate.type | The type of mandate you want to create. Must be direct_debit for a direct debit.Use sweeping for VRPs. |
mandate.remitter.account_holder_name | The name of the user who will make payments under the direct debit. |
mandate.remitter.account_identifier | The bank details of the user who will make payments under the direct debit. Contains three child fields: - type : Currently only supports sort_code_account_number for SCAN payments.- sort_code : The user's sort code.- account_number : The user's account number. |
mandate.remitter.address | The address of the user who will make payments under the direct debit. Contains 5 child parameters describing the user's address: - address_line1 : The street address including house or flat number and street name.- city : The city or town.- state : The county, province or state.- zip : The post code.- country_code : The country code as a two-letter ISO-3166-1 alpha-2 code. |
mandate.beneficiary.type | The type of beneficiary the direct debit will pay. For direct debits, this must be merchant_account . |
mandate.beneficiary.merchant_account_id | The id associated with the merchant account the direct debit will pay.You can retrieve the id by using the /v3/merchant-accounts endpoint or checking the Merchant Account page in Console. |
currency | The currency that the direct debit will make payments in. As only the UK is supported currently, this must be gbp . |
user.name | The name of the remitting user who will make payments under the direct debit. This is likely the same as the account_holder_name . |
user.email | The email of the remitting user who will make payments under the direct debit. |
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
mandate_authorized
webhookYou 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
mandate_failed
webhookYou 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
mandate_revoked
webhookThis 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
mandate_remitter_changed
webhookThe 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:
mandate.remitter.account_identifier.account_number | Scenario to test |
---|---|
Any number ending in 1111 | The payment fails. The failure reason is provider_rejected . |
Any number ending in 2222 | The payment fails with a 500 error code from the `/mandates` endpoint. |
For individual direct debit payments, you can test different failure scenarios by inputting different payment amounts:
amount_in_minor | Scenario to test |
---|---|
1111 | The payment fails. The failure reason is provider_rejected . |
2222 | he payment fails with a 500 error code from the /payments endpoint. |
Any other value causes the mandate or payment to move into the authorised
and eventually the settled
status.
Direct debit-specific payment failure_reasons
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"
}
Updated 23 days ago