Payment Initiation APIs

Introduction

This API specification provides details of the Payment Initiation API and a set of REST API endpoints for executing the payments flow for the PISP.

This section describes the overall payment journey, payloads and API endpoint details for the consent setup element of the Payment Initiation API.

Once the consent setup is created and is authorised by the customer/payment service user (PSU), a PISP can invoke the Payment Submission API to initiate the payment processing with Bank of Ireland. The PISP 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.

Note: Currently BOI does not support credit card payments.

Functional Overview

The diagram below provides a general outline of a payment flow for all payment order types using the Payment APIs as defined by Open Banking UK and ROI.

The payment-order consent and payment-order resource in the above flow generalises for the different payment-order types e.g. for a domestic payment, the payment-order consent resource is domestic-payment-consents; and the payment-order resource is domestic-payments.

The payment-order types covered in this specification include:

S No	Payment Type	Jurisdiction
1	Domestic payments	UK and ROI
2	Domestic scheduled payments	UK and ROI
3	Domestic standing orders	UK and ROI
4	File payments	UK and ROI
5	International payments	UK and ROI
6	International scheduled payments	UK and ROI
7	Same Day Money Transfer Payments	ROI

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 PISP using a Client Credentials grant type within a secure, server side context between the PISP and the ASPSP. The scope "payments" must be used. When an Access Token expires, the PISP should request another Access Token using the request payload.

3. Set up payment-order consent request

A PISP begins the Payment Initiation journey by registering their intent to make a payment on behalf of the customer/payment service user (PSU). The PISP must then obtain consent from the PSU in order to authorise the request, enabling the PISP to submit the payment.

The PISP connects with the API Platform to setup a payment-order consent request. On successful creation of the payment-order resource, the PISP receives an Intent ID/ ConsentId as evidence of their intent.

The PISP can retrieve the status of a payment-order consent using this Intent ID/ConsentId.

4. Authorise Consent

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

The PISP will redirect the PSU to the Bank of Ireland API Platform to initiate the SCA followed by consent authorisation flow. The redirect 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 Bank of Ireland API Platform requests the PSU to authenticate using SCA. The type of credentials required is based on the financial institution (FI) and the selected channel (i.e., B365, BOL) chosen by the PSU. The consent needs to be associated with the accounts held by the PSU. There are two scenarios possible for selecting the accounts:

1. Where no account is 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 are displayed to the user and upon final confirmation the API Platform marks the consent as authorised or rejected.

2. Where an account is 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 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

In case where PSU has not provided any account details in the payment setup request, the user is displayed the details of the PSU’s accounts and requests them to select the payment accounts to which the consent should be applied.

5. Get Access Token to invoke PISP APIs

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

6. Confirm Funds (Domestic Payments and International Payments)

Once the PSU authenticated and authorised the payment-order-consent using SCA, the PISP can check whether funds are available to make the payment.
The PISP can request the funds-confirmation operation on the payment-order-consent resource.

7. Create payment-order submission

Once the TPP has the required Access Token it can invoke the payment submission API to initiate payment processing with Bank of Ireland. Each token can be used only once to submit a payment.

On successful submission of the payment-order the PISP receives a Payment Id which it can use to retrieve the status of the payment-order submission.

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

https://openbankinguk.github.io/read-write-api-site3/v3.1.8/profiles/

Examples

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

Prerequisite for API invocation

• For the API endpoints we are using Open Banking Directory Sandbox certificates. You need to trust Open Banking Directory Sandbox certificates while calling our 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 PISP invokes in order to create a payment-order consent resource using the POST request. This resource allows the PISP to send a copy of the consent (between PSU and PISP) to the ASPSP for the PSU to authorise. After successful creation of the consent resource the PISP can use the generated Intent ID/ Consent Id to retrieve the status of the consent using the GET request. Examples of the different payment-order consent APIs can be viewed here.

3. Authorise Consent

PISP receives a Consent Id. The PISP 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).

For more details on request object creation follow below link:
https://openbankinguk.github.io/read-write-api-site3/v3.1.8/profiles/payment-initiation-api-profile.html

4. Get Access Token to invoke APIs

PISPs 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 developer portal.
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

5.1 This API endpoint allows the PISP to get confirmation of funds on a domestic-payment-consent
resource.

GET /domestic-payment-consents/{ConsentId}/funds-confirmation

Get Request: Confirm Funds on Domestic Payment Order Consent

GET /domestic-payment-consents/58923/funds-confirmation HTTP/1.1
Authorization: Bearer Jhingapulaav
x-fapi-auth-date: Sun, 10 Sep 2017 19:43:31 GMT
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

5.2 This API endpoint allows the PISP to get confirmation of funds on an international-payment-consent
resource.

GET /international-payment-consents/{ConsentId}/funds-confirmation

Get Request: Confirm Funds on International Payment Order Consent

GET /international-payment-consents/58923/funds-confirmation HTTP/1.1
Authorization: Bearer Jhingapulaav
x-fapi-auth-date: Sun, 10 Sep 2017 19:43:31 GMT
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

6. Create payment-order submission

This API is invoked by a PISP initiating the processing of a payment-order using the POST request. After successful submission the PISP can use the Payment ID generated to retrieve the status of the submission using the GET request. Examples of the different payment-order submission APIs can be viewed here.

Versioning

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