Recurring payment references and reconciliation

Learn about recurring payment references and how to reconcile variable recurring payments.

Open banking references

Recurring payments have multiple fields that can be referred to as a reference. Here is a definition for each type:

mandate_referenceMandate reference shown to the remitter.
payment_referencePayment reference shown to the remitter and beneficiary.
end_to_end_referencePayment reference that is not typically shown to the remitter. This is used for reconciliation. This field is also know as End To End Identification within the faster payment system.

Mandate reference

This is the reference of the mandate that is shown to the remitter in their banking app.

Mandate references are not able to be changed.

Regulated customers can optionally specify a mandate reference when creating a mandate. Its value must respect the following constraints:

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

Unregulated customers trying to set a custom mandate reference will get a validation error.

If a mandate reference is not specified, one is automatically set to be the clients name, adjusted as required to align with the above mentioned constraints.

Payment reference

This has the same value as the mandate reference and is shown to the remitter in their 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, this is typically not shown to the remitter.

This reference can only be changed when 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.

Reconciliation for merchant accounts is automatically handled for you.

The payment status will change to settled and a payment settlement webhook will be sent.

Reconciling VRP payments into an external account.

As we are unable to change the payment_reference , we must use the end_to_end_reference to reconcile payments.

The typical flow for this is:

  1. Create and authorize a mandate with an external account as the payment method.
  2. Create a payment and pass in a reference as described above. We recommend this is a unique value to allow for easier reconciliation.
  3. Once the payment has been executed check for new payments from your banking provider.
  4. Ensure that payment amount, currency and end_to_end_reference are the same as the payment that was just executed.

Note: Please, consult your own banking provider's documentation to find out exactly how to retrieve the end_to_end_reference from the payments you will receive.