Skip to main content
Direct debit lets you pull funds from a customer’s bank account on a recurring basis without requiring them to initiate each payment. The customer provides authorization once through a mandate, and you can then debit them within the agreed limits as often as needed. The full flow is: create a mandate → initiate activation → validate activation → debit.
You must complete the full activation flow before attempting to debit a mandate. Attempting a debit on an unactivated or cancelled mandate returns a 409 error.
1

Create a Mandate

Send a POST request to /direct-debits/mandates with the customer’s bank details and the parameters governing future debits.
Request
The duration from start_date to end_date must be at least 30 days. Mandates with a shorter duration are rejected.
A successful response returns a mandate_reference and an initial status of pending_activation.
2

Initiate Mandate Activation

Trigger the bank’s customer verification process by sending a POST request to /direct-debits/mandates/{mandate_reference}/initiate-activation.
Request
This call instructs the customer’s bank to send them an OTP or similar challenge. The customer must receive and complete this challenge before activation can be validated in the next step.
You do not need a request body for this call. The mandate_reference in the URL path is sufficient.
3

Validate Mandate Activation

Once the customer has received their OTP (and, where required, their PIN), submit the credentials to complete activation:
Request
A successful response changes the mandate status to active. Paylink also fires a mandate_activated webhook event to your configured endpoint.
If you try to call validate-activation before calling initiate-activation, the API returns a 409 Mandate activation needs to be initiated first error.
4

Debit the Mandate

With an active mandate in place, you can now pull funds from the customer’s account. Send a POST request to /direct-debits/debit:
Request
Each payment_reference must be unique. Re-using a reference returns a 409 Direct debit payment already exists for the given reference error.
Ensure debit_amount does not cause the month’s total to exceed max_monthly_amount, and that the number of debits this month stays within max_monthly_debit_count.
5

Check Debit Status

Debit requests are processed asynchronously. Poll GET /direct-debits/status/{payment_reference} to check the outcome:
Request
Response
Paylink also fires a direct_debit_success (or direct_debit_failure) webhook event so you don’t need to poll repeatedly.

​
Additional Operations

​
Look Up a Mandate

Retrieve the current state of any mandate at GET /direct-debits/mandates/{mandate_reference}:
Request

​
Cancel a Mandate

To revoke a mandate, send a PATCH request to /direct-debits/mandates/{mandate_reference}/cancel:
Request
Once cancelled, the mandate cannot be reactivated. You must create a new mandate if you need to resume debiting the customer.

​
Disbursements

After collecting funds, use POST /direct-debits/disburse to move money to your desired destination account. See the Transfers guide for details on payout flows.

​
Webhook Events