Skip to main content
A direct debit mandate authorizes Paylink to pull funds from a customer’s bank account on your behalf. The lifecycle follows a strict sequence: create the mandate, initiate activation to trigger the bank authorization flow, validate activation with the credentials returned by the bank, and then use the active mandate for debits. You may cancel a mandate at any time.
1

Create a Mandate

Registers a new direct debit mandate for a customer. The mandate is created in a pending state and must be activated before any debits can be processed.
HeadersRequest body
​
string
required
Full legal name of the customer.
​
string
required
Email address of the customer.
​
string
required
Customer’s bank account number to be debited.
​
string
required
Bank code for the customer’s account. Use GET /banks to retrieve valid codes.
​
string
required
The date the mandate becomes effective. Must be a future date. Format: YYYY-MM-DD.
​
string
required
The date the mandate expires. Must be at least 30 days after start_date. Format: YYYY-MM-DD.
The mandate duration must be at least 30 days.
​
number
required
Maximum total amount (in the lowest currency unit) that may be debited within a single calendar month.
​
integer
required
Maximum number of individual debit transactions allowed per calendar month.
Example request
Example response
2

Initiate Activation

Triggers the bank authorization flow for a pending mandate. The bank returns a set of authorization parameters (such as OTP prompts or PIN challenges) that the customer must complete in the next step.
Path parameters
​
string
required
The unique reference of the mandate returned when it was created.
Example response
Collect the values for param1 / param2 and their corresponding prompts from value1 / value2, then present them to the customer to complete authorization.
3

Validate Activation

Submits the customer’s authorization credentials to complete mandate activation. Use the param1, value1, param2, and value2 keys returned by the initiate step.
Path parameters
​
string
required
The unique reference of the mandate being activated.
Request body
​
string
required
Must match the mandate_reference path parameter.
​
string
required
The first authorization parameter key returned by the initiate step (e.g. "otp").
​
string
required
The customer’s response to the first authorization challenge (e.g. the OTP value).
​
string
required
The second authorization parameter key returned by the initiate step (e.g. "pin").
​
string
required
The customer’s response to the second authorization challenge (e.g. the PIN value).
Example request
Example response
If you attempt to validate before calling initiate, the API returns: 409 Mandate activation needs to be initiated first
4

Get Mandate

Retrieves the current state of a mandate, including its status, configured limits, and customer details.
Path parameters
​
string
required
The unique reference of the mandate to retrieve.
Example response
5

Cancel Mandate

Cancels an active or pending mandate. Once cancelled, no further debits may be initiated against it.
Path parameters
​
string
required
The unique reference of the mandate to cancel.
Example response

​
Error Reference