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
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:
{
"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
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 |
Updated 4 months ago