Create a payment on a mandate
Learn how to create a payment on a mandate.
Refer to the API Reference for further information on Creating a Payment on a Mandate
Now that you have an authorised mandate, you can use its identifier along with a payments
scoped token to create a payment. After you've created the payment resource, you should expect to see status updates coming from TrueLayer.
A payment created using an authorised mandate does not need further authorisation, and does not require any other action as long as it is within the mandate's constraints.
Requests should be signed and need an idempotency key
All the requests in this guide should be signed on your server/backend.
All the requests in this guide should include an idempotency key. You can learn more about API idempotency.
To initiate a payment, you need to use your access token retrieved in previous steps in your Authorization
header, with the Bearer
prefix.
Make a payment initiation request
Make a POST request to the /v3/payments
endpoint with the following parameters:
Field | Description |
---|---|
amount_in_minor | The amount in minor units. Minor units are the smallest units of a currency depending on the number of decimals. For example: GBP 1 = 100 pence |
currency | Currency the payment should be made in. Values: GBP , EUR |
payment_method.type | Method of the payment. Value: mandate |
payment_method.mandate_id | ID of the mandate used to authorize the payment |
payment_method.reference | Reference to be used on the payment as EndToEndIdentification . Read more about payment references here. |
retry.type | When this feature is enabled, enable retry on failures by specifying retry type. Values: standard , smart |
retry.for | Specify how long to retry. Refer to the API Reference for the details of the format and supported range |
retry.ensure_minimum_balance_in_minor | Optionally, specify the remaining balance to ensure (in minor unit) after taking this payment. (Available when retry.type is smart ) |
For example:
curl -X POST https://api.truelayer.com/v3/payments \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(random)" \
-H "Tl-Signature: ${SIGNATURE}" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"amount_in_minor": 1000,
"currency": "GBP",
"payment_method": {
"type": "mandate",
"mandate_id": "f9b48c9d-176b-46dd-b2da-fe1a2b77350c"
"reference": "MyReference123"
},
}'
https POST api.truelayer.com/v3/payments \
Idempotency-Key:"$(random)" \
Tl-Signature:"${SIGNATURE}" \
Authorization:"Bearer ${TOKEN}" \
amount_in_minor:=1000 \
currency="GBP" \
payment_method[type]="mandate" \
payment_method[mandate_id]="f9b48c9d-176b-46dd-b2da-fe1a2b77350c" \
reference="MyReference123"
let body = {
"amount_in_minor": 1000,
"currency": "GBP",
"payment_method": {
"type": "mandate",
"mandate_id": "f9b48c9d-176b-46dd-b2da-fe1a2b77350c"
},
"reference": "MyReference123"
};
let options = {
method: "POST",
headers: {
'Content-Type': 'application/json',
'Idempotency-Key': random_value,
'Tl-Signature': signature,
'Authorization': `Bearer ${TOKEN}`
},
body: JSON.stringify(body)
};
fetch('https://api.truelayer.com/v3/payments', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
If payment initiation is successful, you'll get a response with the following fields:
Field | Description |
---|---|
id | ID of the created payment resource |
user.id | ID of the user the payment was made for. Should match the ID returned when creating the mandate |
resource_token | Short-lived (15 minutes), limited token with authorisation to interact with the created payment. This can be used on the front end to view the settlement status of the payment |
{
"id": "string",
"user": {
"id": "{UUID}"
},
"resource_token": "a-secret-token"
}
The newly-created payment will have the status authorizing
.
No more actions are required for funds to be transferred. You will receive one of the payment webhooks depending on the outcome of the payment.
Enable retry for failed payments
Retry is an opt-in feature.
This feature is optional, and is disabled by default. Contact us if you would like to enable this feature
Enable this to let us automatically retry failed payments to improve conversion.
- The type of error to retry
- How long to retry the payment for
Specify this in the fieldretry.for
Standard Retry
Any provider errors and intermittent system errors will be retried.
Smart Retry
All error types are retried including Insufficient Funds and Constraints Violations.
Optionally, specify the retry.ensure_minimum_balance_in_minor
parameter. This ensures the specified balance remains in the payment account after the transfer is complete.
Updated 2 months ago