Initiate a VRP payment

Initiate a sweeping VRP payment using the authorised consent


VRP payments

VRP payments can only be initiated once the user has successfully set up their consent

Initiating a VRP payment

The diagram below provides a high-level overview of the VRP payment process.

Step 1: Initiate a VRP payment

This request initiates a new Variable Recurring Payment using an existing authorised consent.

VRP Payment initiation will only be available against an Authorised consent. Request that are made when the consent is in Awaiting Authorisation / Revoke / Rejected / Error state will return an unsuccessful response.

A user will only be able to use the consent ID that belongs to them. If an incorrect consent ID is used, the VRP payment initiation will return an unsuccessful response.

  "consentId": "string",
  "payment": {
    "currency": "string",
    "amount": 0,
    "reference": "string"

Consent parameter definitions

consentIdThe id of the consent being used to make this payment. Note that if the consent is not authorised, the payment will not be initiated.String 10Consent id specified must belong to the user making the API call and also be in an authorised state (per the status in our DB).
PaymentPayment amount and currency.Object-
payment.amountAmount.StringPositive amounts with a maximum of two decimal places.
payment.currencyCurrency of the payment, specified in ISO 4217 format.StringOnly allowable value is GBP.

Must be specified in ISO 4217 format.
payment.referenceA reference used to unambiguously refer to the payment transaction. Min 6 to max 18 characters. Can contain alphanumeric, '-', '.', '&', '/' and space.StringMin 6 to max 18 characters. Can contain alphanumeric, '-', '.', '&', '/' and space.

If the reference field on the consent is present, this field has to match it.

Example showing when VRP has been initiated:

  "id": "string",
  "status": "SUBMITTED"

Example showing when the payment has not been processed because the consent does not exist:

  "field": "string",
  "code": "GENERAL",
  "errorCode": "string",
  "message": "string",
  "sourceService": "string"

Confirm the availability of funds in an account (optional)


Availability of funds

This is an optional step, however confirming funds in the account that money is being swept from prior to making the payment reduces the likelihood of a failed payment due to lack of funds.

Use the Consent ID to confirm the availability of funds in an account, prior to initiating a Variable Recurring Payment.

"currency": "GBP",
"amount": "1.00"

If the fund availability request is successful, you’ll get a response with the following fields:

  "fundsAvailable": true,
  "fundsAvailabilityCheckDateTime": "2024-04-25T12:00:50.047Z"


External balance

Note - the user is not able to view the balance of the crediting account, only whether the funds are available based on the value the user wishes to sweep.

Get the status of a VRP payment (optional)

Fetch the details of a payment initiated using VRP based on a unique Payment ID.

The GET /vrp/{id} endpoint is used to retrieve the specific VRP payment details. This includes all the information tied to that payment such as consentId, payment and status. The unique payment ID, which is a required path parameter, identifies the specific payment to be retrieved. This API is essential for clients who want to verify the initiated payment and provide their end users with detailed information which will help them track the payment's progress. The endpoint responds with the full payment details in a JSON format if the payment ID is valid and exists in the system.

  "consentId": "string",
  "payment": {
    "currency": "string",
    "amount": 0,
    "reference": "string"
  "status": "string"

Payment Status Model

StateCompletion state?Description
SUBMITTEDNoPayment instruction submitted, status pending
ACCEPTEDSETTLEMENTINPROCESSNoAll preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution
ACCEPTEDCREDITSETTLMENTCOMPLETEDYesSettlement on the creditor's account has been completed
ACCEPTEDSETTLEMENTCOMPLETEDYesSettlement on the debtor's account has been completed
ACCEPTEDWITHOUTPOSTINGNoPayment instruction included in the credit transfer is accepted without being posted to the creditor customer’s account
PENDINGNoPayment initiation or individual transaction included in the payment initiation is pending. Further checks and status update will be performed
REJECTEDNoPayment initiation or individual transaction included in the payment initiation has been rejected
ER_GENERALNoGeneric error occurred when processing the payment initiation
ER_EXTSYSNoThe payment initiation failed because there was a problem communicating with the bank’s systems