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.

POST /vrp

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

Consent parameter definitions

Field	Description	Type	Validation
consentId	The 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 10	Consent id specified must belong to the user making the API call and also be in an authorised state (per the status in our DB).
Payment	Payment amount and currency.	Object	-
payment.amount	Amount.	String	Positive amounts with a maximum of two decimal places.
payment.currency	Currency of the payment, specified in ISO 4217 format.	String	Only allowable value is GBP. Must be specified in ISO 4217 format.
payment.reference	A reference used to unambiguously refer to the payment transaction. Min 6 to max 18 characters. Can contain alphanumeric, '-', '.', '&', '/' and space.	String	Min 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:

POST /vrp

{
  "id": "string",
  "status": "SUBMITTED"
}

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

POST /vrp

{
  "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.

POST /vrp-consents/{consentId}/fund-confirmation

{
"currency": "GBP",
"amount": "1.00"
}

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

POST /vrp-consents/{consentId}/funds-confirmation

{
  "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.

GET /vrp/{id}

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

Payment Status Model

State	Completion state?	Description
SUBMITTED	No	Payment instruction submitted, status pending
ACCEPTEDSETTLEMENTINPROCESS	No	All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution
ACCEPTEDCREDITSETTLMENTCOMPLETED	Yes	Settlement on the creditor's account has been completed
ACCEPTEDSETTLEMENTCOMPLETED	Yes	Settlement on the debtor's account has been completed
ACCEPTEDWITHOUTPOSTING	No	Payment instruction included in the credit transfer is accepted without being posted to the creditor customer’s account
PENDING	No	Payment initiation or individual transaction included in the payment initiation is pending. Further checks and status update will be performed
REJECTED	No	Payment initiation or individual transaction included in the payment initiation has been rejected
ER_GENERAL	No	Generic error occurred when processing the payment initiation
ER_EXTSYS	No	The payment initiation failed because there was a problem communicating with the bank’s systems