Payment Initiation APIs

Download
(1 review)

home

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.

6c6d7dd7-f0df-4443-b84d-3f09bb889181-image.png

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:

  1. Domestic payments

  2. Domestic scheduled payments

  3. Domestic standing orders

  4. File payments

  5. International payments

  6. International scheduled payments

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.

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.

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 the 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. 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://www.openbanking.org.uk

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 The scope being requested.

POST response: client credentials grant type token endpoint

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

This is the first API that an 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.

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://openbanking.atlassian.net/wiki/spaces/DZ/pages/83919096/Open+Banking+Security+Profile+-+Implementer+s+Draft+v1.1.2

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. 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.0.0**


Reviews

Payment Initiation APIs doesn't have any reviews yet