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

FieldDescription
amount_in_minorThe 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
currencyCurrency the payment should be made in. Values: GBP, EUR
payment_method.typeMethod of the payment. Value: mandate
payment_method.mandate_idID of the mandate used to authorize the payment
referenceReference to be used on the payment as EndToEndIdentification. Read more about payment references here.
retry.typeWhen this feature is enabled, enable retry on failures by specifying retry type. Values: standard, smart
retry.forSpecify how long to retry. Refer to the API Reference for the details of the format and supported range
retry.ensure_minimum_balance_in_minorOptionally, 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-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:

FieldDescription
idID of the created payment resource
user.idID of the user the payment was made for. Should match the ID returned when creating the mandate
resource_tokenShort-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. 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.