Start from the API
Create a Direct Debit subscription through the API against a mandate the customer has already set up
Subscriptions created through the API don't collect payment yet. They are created without an amount, so no renewal takes a payment, on card or Direct Debit. This is tracked as REV-8403. To collect today, send the customer a checkout link or an invoice.
POST /v2/subscriptions can create a subscription that collects by Direct Debit against a mandate the customer already has.
Request
{
"customerId": "…",
"priceId": "…",
"paymentRail": "direct_debit",
"mandateId": "…"
}The response includes payment_rail, mandate_id and payment_method_id, so you can read back how the subscription collects.
What is checked
| Check | Answer when it fails |
|---|---|
mandateId sent without paymentRail: direct_debit | 400 mandate_requires_direct_debit |
paymentRail: direct_debit without a mandateId | 400 mandate_required |
A paymentMethodId on a Direct Debit subscription | 400 payment_method_not_allowed_on_direct_debit |
| Direct Debit is not enabled for your account | 403 direct_debit_not_enabled |
| The price is not in GBP | 400 direct_debit_requires_gbp |
| The mandate does not exist, or belongs to another customer | 404 mandate_not_found |
| The mandate cannot collect yet (for example, still being set up) | 422 mandate_not_active |
A mandate that does not exist and a mandate that belongs to someone else get the same answer.
Who can call it
Creating a Direct Debit subscription needs a signed-in team member or an OAuth app with access to mandates. API keys are refused with 403, the same answer they get from the mandate endpoints.
Setting up the mandate first
The customer sets up the mandate themselves, from a mandate request, checkout or an invoice. You cannot create a mandate through this endpoint.