Variable Recurring Payments API

The Variable Recurring Payments API Profile describes the flows and common functionality for setting up VRP Consents and subsequently creating one or more payment orders that meet the limitations set by the VRP Consent.

The functionality includes the ability to:

• Stage a VRP Consent.
• Optionally confirm available funds for a VRP of a specified amount
• Subsequently submit the VRP for processing.
• Optionally retrieve the status of VRP Consents and VRPs.

This profile should be read in conjunction with a compatible Read/Write Data API Profile which provides a description of the elements that are common across all the Read/Write Data APIs.

#Resources

Each of the Payment Initiation API resources are documented in the Resources and Data Models area of the specification. Each resource is documented with:

• Endpoints
• Data Model
• Usage Examples

POST /domestic-vrp-consents

The API endpoint allows the TPP to ask an ASPSP to create a new domestic-vrp-consents resource.

The request payload may contain Debtor Accounts, but the PSU may not have been identified by the ASPSP.

The endpoint allows the TPP to send a copy of the consent (between PSU and TPP) to the ASPSP for the PSU to authorise.

The ASPSP creates the resource and responds with a unique ConsentId to refer to the resource.

The default/initial Status of the resource is set to AwaitingAuthorisation.

If the parameters specified by the TPP in this resource are not valid, or fail any rules, the ASPSP must return a 400 Bad Request. In such a situation a resource is not created.

The ASPSP must allow a PSU to have multiple VRP consents for a given account. This could include multiple consents with the same PISP.

The ASPSP must reject a consent request that has Data.ControlParameters.SupplementaryData that it cannot process.

#GET /domestic-vrp-consents/{ConsentId}

A TPP can retrieve a VRP consent resource that they have created to check its status at any point of time using this API.

#DELETE /domestic-vrp-consents/{ConsentId}

A TPP can delete a VRP consent resource that they have created by calling this API.

#POST /domestic-vrp-consents/{ConsentId}/funds-confirmation

This API endpoint allows the TPP to ask an ASPSP to confirm funds on the DebtorAccount associated with the domestic-vrp-consent.

An ASPSP can only respond to a funds confirmation request if the resource has a Status of Authorised.

If resource has any other Status, the ASPSP must respond with a 400 (Bad Request) and a UK.OBIE.Resource.InvalidConsentStatus error code.

#State Model - VRP consents

The state model for the VRP consents resource follows the generic consent state model. However, it does not use the Consumed status.

POST /domestic-vrps

Once a domestic-vrp-consents has been authorised by the PSU, the TPP can proceed to submitting a domestic-vrps for processing.

This is done by making a POST request to the domestic-vrps endpoint.

This request is an instruction to the ASPSP to begin the domestic single immediate payment journey. The domestic payment must be executed immediately, however, there are some scenarios where the domestic payment may not be executed immediately (e.g., busy periods at the ASPSP).

The TPP must ensure that the Initiation and Risk section matches the values specified in the consent.

The ASPSP must ensure that the payment instruction adheres to the limitations set by the corresponding VRP consent's ControlParameters.

When a payment would breach a limitation set by one or more ControlParameters, the ASPSP must return an error with code UK.OBIE.Rules.FailsControlParameters and pass in the control parameter field that caused the error in the Field field of the error message.

If the CreditorAccount was not specified in the the consent, the CreditorAccount must be specified in the instruction.

The TPP must ensure that the end-point is called with the same scope as the one used for the corresponding consent.

The ASPSP must reject a payment that has Data.Instruction.SupplementaryData that it cannot process.

#Status

A domestic-vrps can only be created if its corresponding domestic-vrp-consents resource has the status of Authorised.

The domestic-vrps resource that is created successfully must have one of the following PaymentStatusCode values

• Pending
• Rejected
• AcceptedSettlementInProcess
• AcceptedSettlementCompleted
• AcceptedWithoutPosting
• AcceptedCreditSettlementCompleted

#GET /domestic-vrps/{DomesticVRPId}

Once the domestic vrp is created, a TPP can retrieve the domestic-vrps to check its status by using this endpoint.

The domestic-vrp resource must have one of the following PaymentStatusCode code-set enumerations:

• Pending
• Rejected
• AcceptedSettlementInProcess
• AcceptedSettlementCompleted
• AcceptedWithoutPosting
• AcceptedCreditSettlementCompleted

#GET /domestic-vrps/{DomesticVRPId}/payment-details

A TPP can retrieve the details of the underlying payment transaction via this endpoint. This resource allows ASPSPs to return a richer list of Payment Statuses, and if available payment scheme related statuses.

The API must return one of the following status codes:

• Accepted
• AcceptedCancellationRequest
• AcceptedTechnicalValidation
• AcceptedCustomerProfile
• AcceptedFundsChecked
• AcceptedWithChange
• Pending
• Rejected
• AcceptedSettlementInProcess
• AcceptedSettlementCompleted
• AcceptedWithoutPosting
• AcceptedCreditSettlementCompleted
• Cancelled
• NoCancellationProcess
• PartiallyAcceptedCancellationRequest
• PartiallyAcceptedTechnicalCorrect
• PaymentCancelled
• PendingCancellationRequest
• Received
• RejectedCancellationRequest