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 /payments endpoint with the following parameters :

For example:

curl -X POST https://api.truelayer-sandbox.com/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-sandbox.com/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-sandbox.com/payments', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

If the payment initiation is successful, you'll get a response with the following fields:

{
  "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. There are two retry mode that determines:

• The type of errors to retry,
• How long it can be retried (Specified in field: retry.for),

Refer to the the API Reference for further information on this.

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.