Recurring payment references and reconciliation

A reference is a unique string that is used to identify payments or mandates, either internally or on your users' bank statements. Your users should be able to tell what the payment is for and who they made it to or where it came from. We recommend that you use the format companyname-uniqueid for references.

Recurring payments requests include multiple fields in which you can set a reference. Below is a definition for each type:

Mandate reference

This is the reference of the mandate that is shown to the remitter in their banking app. You cannot change a mandate reference.

If your business is a regulated PISP, you can choose to specify a mandate reference when creating a mandate. If your business is not a regulated PISP, you cannot set your mandate reference.

References must:

• have a maximum length of 18 characters
• match this regex: ^[a-zA-Z0-9-:()\.,'\+ \?\/]{1,18}$

If a mandate reference is not specified, one is automatically set for you. By default, the reference is your business's name, adjusted as required to align with the above mentioned constraints.

Payment reference

This has the same value as the mandate reference. It displays in the remitter's bank app to help them identify payments belonging to a mandate. This reference cannot be changed.

End-to-end reference

This is a reference that can be used to reconcile payments. It is typically not shown to the remitter.

You can only change this reference when you are making a payment using a mandate with a beneficiary type of external account.

To change the end to end reference set the reference field inside the paymentMethod object.
If this reference is not set, one will be automatically generated.

If you choose to provide your own reference, we recommend one that is 18 alphanumeric characters or shorter to ensure banks don't reject the payment.

Reconciling VRP payments into a merchant account

We automatically handle payment reconciliation into your merchant account. When you accept a payment, the payment status changes to settled and a payment settlement webhook is sent.

Reconciling VRP payments into an external account

TrueLayer cannot change the payment_reference value. Therefore, to reconcile payments into an external account, you must use the end_to_end_reference.

To do this:

1. Create and authorize a mandate. Set the beneficiary to external_account.
2. Create a payment and pass in a reference as described above.
   We recommend that you make this a unique value for each payment.
3. Once the payment has been executed, check for new payments from your banking provider.
4. Ensure that the payment amount, currency and end_to_end_reference are the same as the payment that was just executed.

To retrieve the end_to_end_reference from the payments you receive, refer to your banking provider's documentation.