Variable Recurring Payments APIs

Introduction

This API specification provides details of the Variable Recurring Payments API and a set of REST API endpoints for executing the payments flows for the TPP.

This section describes the overall payment journey, payloads, and API endpoint details for the following:
a. Consent and Control Parameters setup
b. Payment Submission
c. Confirmation of Funds

The TPP registers a VRP consent resource with ASPSP holding PSU account, to initiate single/multiple domestic payments as per agreed control parameters with PSU. Once the consent is authorised by the PSU, the TPP can invoke the VRP submission API to initiate the payment processing with Bank of Ireland. The TPP is required to use the same payment details payload used during the consent setup. Any operation on the payment submission resource will not change the status of the consent setup resource.

Functional Overview

The diagram below provides a general outline of a VRP flow as defined by Open Banking UK.

The above flow is documented in terms of two abstract resources:

• domestic-vrp-consents: A consent created between a PSU and TPP that allows the TPP to create vrps on behalf of the PSU subject to control parameters
• vrps: A payment order created by the TPP that meets the limitations set out by an approved domestic-vrp-consents resource.

This version of the specification is limited to domestic-vrp-consents and domestic-vrps.

Payment Flow Steps with Examples

1. Request payment initiation

PSU requests Payment Initiation Service Provider (PISP) to initiate a payment.

2. Set up Client Credentials Token

To set up payment request, the Access Token must be obtained by the TPP using a Client Credentials grant type within a secure, server-side context between the TPP and the ASPSP. The scope "payments" must be used. The access token is valid for 5 minutes, after which the ASPSP will issue a refresh token that is long-lived (expires with the consent expiry) where the PISP can use it to request an access token.

3. Set up VRP consent request

A TPP begins the Payment Initiation journey by registering their intent to make a payment on behalf of PSU. The TPP must then obtain consent from the PSU to authorise the request, enabling the TPP to submit the payment.

The TPP connects with the API Platform to setup a domestic-vrp-consents request. On successful creation of the domestic-vrp-consents resource, the TPP receives a ConsentId as evidence of their intent.

The TPP can retrieve the status of a domestic-vrp-consent using this ConsentId.

4. Authorise Consent

Once the Payment Initiation is set up successfully, the TPP can then request the PSU to perform SCA and then authorise the consent with Bank of Ireland.

The TPP will redirect the PSU to the Bank of Ireland API Platform to initiate the SCA followed by consent authorisation flow. The redirection includes the Consent ID generated in the previous step, which allows the API Platform to correlate the payment initiation request that was set up.

The VRP consent is a long-lived consent, and it will require only one time authorisation of consent by PSU. The Bank of Ireland API Platform requests the PSU to authenticate using SCA. The type of credentials required is based on the channel (i.e., B365, BOL) selected by the PSU. The consent needs to be associated with the debtor account chosen by the PSU. There are two scenarios possible for selecting the accounts:

1. Where no debtor account details are provided in the initial setup request, the SCA page displays the details of the PSU’s accounts and requests them to select the payment accounts to which the consent should be applied. Based on the PSU’s action the consent details summary is displayed to the user and upon final confirmation the API Platform marks the consent as authorised or rejected.
2. Where debtor account details are provided in the initial setup request, the SCA page displays the provided account and the consent details to the user.

On successful authorisation of consent, the TPP will receive an Auth Code which they can use to request an Access Token. The TPP can use this Access Token to invoke payment submission API. An Access Token is short lived(valid for 5 mins) and is used while accessing the payment submission. Example of the Auth Code (code) sent on the redirect URL can be seen below:

https://{redirect_url}#code=VHAdx9ztWJtR-qd318PZS0xxZ3mY8fQnQIAjMNLc&id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6InhsMTZCRHh3NTdKTi0zUHR2cm15QS16V1RnTSJ9.eyJzdWIiOiI0ODMxZTg4NC0zMzk3LTQ3MzQtODkwMS0yYzNkM2RkZWU5ZjkiLCJhdWQiOiJjNTI4OTgyYi01MjQ2LTQ2MzQtODczYi03OWU3NGYxNzk2YWIiLCJqdGkiOiJ6Y1lqV3JPMklIUTUxSjdjUnRmUE1ZIiwiaXNzIjoiaHR0cHM6Ly9hdXRoLXNhbmRib3guYm9pY2xvdWR0ZXN0Lm5ldCIsImlhdCI6MTU0NzIyMDk3MiwiZXhwIjoxNTQ3MjU2OTcyLCJhY3IiOiJ1cm46b3BlbmJhbmtpbmc6cHNkMjpzY2EiLCJvcGVuYmFua2luZ19pbnRlbnRfaWQiOiI0ODMxZTg4NC0zMzk3LTQ3MzQtODkwMS0yYzNkM2RkZWU5ZjkiLCJub25jZSI6Im4tMFM2X1d6QTJNaiIsImF1dGhfdGltZSI6MTU0NzIyMDg2OSwiY19oYXNoIjoieC05Umt1VHp1cjRBRnhoVmZiZ3lXZyIsInNfaGFzaCI6ImJPaHRYOEY3M0lNalNQZVZBcXh5VFEifQ.eQdeiowGPsJNq0M_1qbd5u3duX-u-kkdigdWxLkmYtwhCadWu2qXSzq3O2R-mt0IfPyaSf-fgUoZ-euAH8J1btQYJ9rvOidfVSr25uhSRGUG3Fe4ngrePJ32AeGgcn-6iLozTKm5XVEeGbBlulGMvZN2oSfov2FB-Up-dWp5KPyfIZrpi4ISqtHDKx-fbNuW7GdebRuOY8TQQo_L7yyo72P4941oJONoGzt4EGmVXmmoUmAXeTrK-acwgkWFcX5VodUSxaKwVg-gZiMEF10Owu94BFU8uEEB5BKncjbSzt6GgCxM3rvdYp-1J-jVdhkZajG6uu1xGILkz7NKJrz2Kw=af0ifjsldkj

5. Get Access Token to invoke TPP APIs

For accessing confirm funds "POST" APIs and domestic-vrp submission "POST" APIs, the Access Token must be obtained by TPP using an Authorization Code grant type within a secure, server-side context between the TPP and the ASPSP.

6. Confirm Funds (TPP confirms the availability of specific amount in PSU's account)

Once the PSU is authenticated and authorised the domestic-vrp-consents using SCA, the TPP can check whether funds are available to make the payment.

The TPP can request the funds-confirmation operation on the domestic-vrp-consents resource.

7. Create domestic-vrp submission

Once the TPP has the required Access Token, it can invoke the payment submission API to initiate one or more VRPs for processing the payment with Bank of Ireland.

On successful submission of the domestic-vrp the TPP receives one or more Payment Id which it can use to retrieve the status of the domestic-vrp submission.

For more details on Open Banking's initiative and Variable Recurring Payments API specifications:

https://openbankinguk.github.io/read-write-api-site3/v3.1.10/profiles/vrp-profile.html

Examples

This section provides examples of API invocation to execute the payment flow for all domestic-vrp types using the Payment APIs as defined by Open Banking UK.

Prerequisite for API invocation

• For the API endpoints Open Banking Directory Sandbox certificates are used. TPP is required to trust Open Banking Directory Sandbox certificates while calling APIs.

1. Set up Client Credentials Token

POST Request: client credentials grant type token endpoint

curl -k -X POST \
--key ./{network.key} \
--cert ./{network.pem} \
 https://api-sandbox.bankofireland.com/oauth/as/token.oauth2 \
-H 'accept: application/json' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&scope=payments&client_id=1OEwYAKIgMtefvOKfSEdAS'

Request parameters:

Parameter	Example value	Description
grant_type	client_credentials	The grant type being requested.
scope	payments	Generic payment scope

POST response: client credentials grant type token endpoint

{
    "access_token": "VS6VAWqqfI2sKOh4iuwgEgPPgduw",
    "token_type": "Bearer",
    "expires_in": 299
}

2. Set up payment-order consent request

This is the first API that a TPP invokes to create a domestic-vrp-consents resource using the POST request. This resource allows the TPP to send a copy of the consent (between PSU and TPP) to the ASPSP for the PSU to authorise. After successful creation of the consent resource the TPP can use the generated Consent Id to retrieve the status of the consent using the GET request.

3. Authorise Consent

TPP receives a Consent Id. The TPP then creates an Authorisation request (using a signed JWT request containing the ConsentId as a claim) for the PSU to consent to the payment consent request with BOI. The request is an OIDC Hybrid Flow (requesting for Code and ID token).

Invoke below URL from web browser.

https://auth-sandbox.bankofireland.com/oauth/as/b365/authorization.oauth2?client_id=1OEwYAKIgMtefvOKfSEdAS&response_type=code id_token&scope=openid payments&state=af0ifjsldkj&nonce=n-0S6_WzA2Mj&request=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjZwSXp3bDBILWF6X2g5Y0VPejQ4UXdfT0tuOCJ9.eyJpc3MiOiIxT0V3WUFLSWdNdGVmdk9LZlNFZEFTIiwiYXVkIjoiaHR0cHM6Ly9hdXRoLXNhbmRib3guYXBpYm9pdGVzdC5jb20iLCJyZXNwb25zZV90eXBlIjoiY29kZSBpZF90b2tlbiIsImNsaWVudF9pZCI6IjFPRXdZQUtJZ010ZWZ2T0tmU0VkQVMiLCJyZWRpcmVjdF91cmkiOiJodHRwczovL3d3dy5nZXRwb3N0bWFuLmNvbS9vYXV0aDIvY2FsbGJhY2siLCJzY29wZSI6Im9wZW5pZCBwYXltZW50cyIsInN0YXRlIjoiYWYwaWZqc2xka2oiLCJub25jZSI6Im4tMFM2X1d6QTJNaiIsIm1heF9hZ2UiOjg2NDAwLCJjbGFpbXMiOnsiaWRfdG9rZW4iOnsib3BlbmJhbmtpbmdfaW50ZW50X2lkIjp7InZhbHVlIjoiNWQyYjhjZTUtNjgxYS00Njc5LWE3OWEtZTY0ZWYxZjk5YWI3IiwiZXNzZW50aWFsICI6dHJ1ZX19fX0.ixb_5CFU5St6GMVxgN5-piN5YUYl6KQPnsiyEbxXkhKEPwMbD7PMthvHCuKfOsFNNTnB5FIleUIDbuWrQUdMWCCA_XJPh9DwjmQagvYbuv-1W2nBrqQTCSPAB_eNCoIBujlY5JXHoIaWKqfe3mrt-b4Q874SHHlkskhw0YVwjPTTY9EPszhWYztVL6_EelQH11UA5rhg_5MaRTw_XKR-I6qvDmToU6f3PI6KNoSTONX-f9MjVuN8P3u9hNSbcArvEchYxD5ShFZ8VH14zx9cV7ewbAJQjaE0sFbacvfdhOaP8kfDn1Jgk1Gf1Hmb_n48jZFiKA9PBaGTnDTku9uW1g&redirect_uri=https://www.getpostman.com/oauth2/callback

URL parameters :

Parameter	Example value	Description
response_type	code id_token	The OAuth flow type
client_id	1OEwYAKIgMtefvOKfSEdAS	The client ID of the application registered in the TPP portal
state	af0ifjsldkj	The state as specified by the TPP
scope	openid payments	The scope being requested.
redirect_uri	https://www.getpostman.com/oauth2/callback	The redirect URL of the application registered in the TPP portal
nonce	n-0S6_WzA2Mj	The nonce as specified by the TPP
request payload	{ "iss": "1OEwYAKIgMtefvOKfSEdAS", "aud": "https://auth-sandbox.bankofireland.com", "response_type": "code id_token", "client_id": "1OEwYAKIgMtefvOKfSEdAS", "redirect_uri": "https://www.getpostman.com/oauth2/callback", "scope": "openid payments", "state": "af0ifjsldkj", "nonce": "n-0S6_WzA2Mj", "max_age": 86400, "claims": { "id_token": { "openbanking_intent_id": { "value": "5d2b8ce5-681a-4679-a79a-e64ef1f99ab7", "essential ": true } } } }	Refer to the sample JWT payload structure provided in example value column and create a signed jwt. For KID and TPP's signing private key details refer to test data file available in Developer hub. Parameters of payload are: "iss" is issuer of the token i.e. same as clientid. "aud" is audience that the ID token intended, should be same as the issuer value from the /.well-known endpoint configuration URL. "redirect_uri" is any valid https URL. "value" is Consent ID(in response of Step 2).

4. Get Access Token to invoke APIs

TPPs must use an authorisation code grant to obtain a token to access all other resources.

POST request: get access token endpoint

curl -X POST \
--key ./{network.key} \
--cert ./{network.pem} \
--url https://api-sandbox.bankofireland.com/oauth/as/token.oauth2 \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data 'grant_type=authorization_code&code=60fz5pcnuvTOZh6zv9TK_vEkRVxjsVW2BA1RvDtU&redirect_uri=https://www.getpostman.com/oauth2/callback&client_id=1OEwYAKIgMtefvOKfSEdAS'

Request parameters:

Parameter	Example value	Description
grant_type	authorization_code	The grant type being requested.
redirect_uri	https://www.getpostman.com/oauth2/callback	The redirect URL must be same as redirect url of the application registered in the developerportal.
code	60fz5pcnuvTOZh6zv9TK_vEkRVxjsVW2BA1RvDtU	The authorization code obtained in step 3 (Consent Autorization).

Response : Access Token

{
    "access_token": "GExRm6odmyvi4KkLLPQ6gkZl5Vwc",
    "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InhsMTZCRHh3NTdKTi0zUHR2cm15QS16V1RnTSJ9.eyJzdWIiOiI1ZDJiOGNlNS02ODFhLTQ2NzktYTc5YS1lNjRlZjFmOTlhYjciLCJhY3IiOiJ1cm46b3BlbmJhbmtpbmc6cHNkMjpzY2EiLCJvcGVuYmFua2luZ19pbnRlbnRfaWQiOiI1ZDJiOGNlNS02ODFhLTQ2NzktYTc5YS1lNjRlZjFmOTlhYjciLCJhdWQiOiIxT0V3WUFLSWdNdGVmdk9LZlNFZEFTIiwianRpIjoiaWxMZ0hSc3JxTWFmNHh2cXhtbWJVWCIsImlzcyI6Imh0dHBzOlwvXC9hdXRoLXNhbmRib3guYXBpYm9pdGVzdC5jb20iLCJpYXQiOjE1NDQ3ODgyNTgsImV4cCI6MTU0NDgyNDI1OCwibm9uY2UiOiJuLTBTNl9XekEyTWoiLCJhdXRoX3RpbWUiOjE1NDQ3ODc3NjQsImNfaGFzaCI6Im9qUnhaU21CMElqazJZSGh1ODl5dnciLCJzX2hhc2giOiJiT2h0WDhGNzNJTWpTUGVWQXF4eVRRIn0.np320xaOfroF9G-bxxFuqNioYbm9TPNG1OdKyafNEVl5M0J5ov6C2pkLIpY0pQwvx0TimQahbKF8QpJdyLJjaB8-0seV3avf3InjAvUP3MAgWOQljAfAY3QwAFZ8SBCiIAnTCjzkSov-Y9D-UavEsijk3n1HYc-mrQu7crmiZfPNtMds9fKhAGg5xBw_9EQ7iN8sZycNlmj4F9j5P_FQv_lRll5jZf3HgfKlgu6OamB0Se-05vdeacULkD3W8syzDMCcoW0mPx7M7ckCMr9CcD1nQFBoGsjdQGxZi37mObKb6FYEcugtYDl9c0_5QODSnO0CXT_Io83BoZwhOniPBA",
    "token_type": "Bearer",
    "expires_in": 299
}

5. Confirm Funds

Once the PSU is authenticated and authorised the VRP Consent, the TPP can check whether funds are available to make the payment.

This API endpoint allows the TPP to get confirmation of funds on a domestic-vrp-consents resource by making a POST request.

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

POST Request: Confirm Funds on domestic-vrp-consents

POST /domestic-vrp-consents HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-idempotency-key: FRESCO.21302.GFX.20
x-jws-signature: TGlmZSdzIGEgam91cm5leSBub3QgYSBkZXN0aW5hdGlvbiA=..T2ggZ29vZCBldmVuaW5nIG1yIHR5bGVyIGdvaW5nIGRvd24gPw==
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json

6. Create domestic-vrp submission

This API is invoked by a TPP initiating the processing of a payment-order for one or more VRPs created, using the POST request. The payment orders must adhere to the control parameters specified by the VRP Consent. After successful submission, the TPP can use one or more Payment ID generated to retrieve the status of the submission using the GET request.

Event Notifications

The Event Notification API allows TPP to receive event notifications in case the PSU revokes consent.

The Event Notification Subscription API allows TPPs to register to receive all or specific event types via the Aggregated Polling API.

Event notifications for cancellation of a VRP Consent

When a VRP consent is cancelled by a PSU at the ASPSP, the ASPSP must inform the TPP through event notification about cancellation. The TPP can do this by subscribing to this event using an aggregated polling mechanism.

Versioning

This API Specification conforms to Open Banking UK Payment Initiation API Specification – v3.1.10