Confirmation of Funds APIs
home
Introduction
This API specification provides details of the Confirmation of Funds API and a set of REST API endpoints for executing the flow for the card-based payment instrument issuers ('CBPII').
This section describes the overall confirmation of funds journey, payloads and API endpoint details for the consent setup and submission element that allow a CBPII to:
- Register an intent to confirm funds by creating a "funds confirmation consent" resource with BOI, for agreement between the PSU and BOI. This consent is a long lived consent, and contains the length of time (expiration date) the customer (PSU) would like to provide to the CBPII, and
- Subsequently make a request to confirm funds are available (funds can only be confirmed against the currency of the account).
Functional Overview
The diagram below provides a general outline of a confirmation of funds request and flow using the Confirmation of Funds APIs as defined by Open Banking UK.
Confirmation of Funds Flow Steps with Examples
1. Agree Funds Confirmation
This flow begins with a PSU committing to give explicit consent to their ASPSP to respond to confirmation of funds requests from the CBPII.
2. Set up Client Credentials Token
To create a funds confirmation consent resource the Access Token must be obtained by a CBPII using a Client Credentials grant type within a secure server side context between the CBPII and BOI. The scope "fundsconfirmations" must be used. When an Access Token expires the CBPII should request another Access Token using the request payload.
3. Set up Funds Confirmation Consent
The CBPII connects to the ASPSP that services the PSU's account(s) and creates a funds confirmation consent resource. This informs BOI that one of its PSUs would like to grant access to confirm the availability of funds to a CBPII. BOI responds with an identifier for the resource - Consent ID.
This step is carried out by making a POST request to /funds-confirmation-consents endpoint, under a client credentials grant.
The CBPII can retrieve the status of the funds confirmation consent using the Consent ID.
4. Authorise Consent
Once the Funds Confirmation Consent is set up successfully, the CBPII can then request the PSU to perform SCA and then authorise the consent with Bank of Ireland.
The CBPII 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 funds confirmation consents resource that was set up.
The Bank of Ireland API PClatform 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.
On successful authorisation of consent, the TPP will receive an Auth Code which they can then use to request an Access Token. The TPP can use this Access Token to invoke Confirmation of Funds API. An Access Token is short lived and to be used while accessing the Confirmation of Funds API. Example of the Auth Code (code) sent on the redirect URL can be seen below:
https://{redirect_url}#code=VHAdx9ztWJtR-qd318PZS0xxZ3mY8fQnQIAjMNLc=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 Funds Confirmation API
For accessing the Confirmation of Funds APIs the Access Token must be obtained by the CBPII using a Authorization Code grant type within a secure, server side context between the CBPII and the ASPSP.
6. Create confirmation of funds resource
If the CBPII would like to confirm funds with BOI it should create a new funds confirmation resource, and check the funds available flag in the response.
The CBPII must use a token issued via authorization code grant and specify the Consent ID in the request payload. The CBPII must use the currency of the account.
On successful creation of the funds confirmation resource, BOI responds with a unique FundsConfirmationId to refer to the resource, and a flag confirming if funds are available.
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 confirmation of funds flow using the CBPII 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=fundsconfirmations=1OEwYAKIgMtefvOKfSEdAS'
Request parameters :
Parameter | Example value | Description |
---|---|---|
grant_type | client_credentials | The grant type being requested. |
scope | fundsconfirmations | Funds confirmation entitlement. |
POST response: client credentials grant type token endpoint
{
"access_token": "YCnmtqFb0S24Hr3zytY9TJOSzd1g",
"token_type": "Bearer",
"expires_in": 299
}
2. Funds Confirmation Consents Setup
This API allows the CBPII to ask BOI to create a new funds confirmation-consent resource and BOI creates the funds confirmation-consent resource and responds with a unique Consent ID to refer to the resource. The CBPII must have an access token issued by BOI using a client credentials grant to invoke this endpoint.
POST request: funds confirmation consents
curl -X POST \
https://api-sandbox.bankofireland.com/1/api/open-banking/v3.1.8/cbpii/funds-confirmation-consents \
-H 'Authorization: Bearer Qlqrdrtjpbu2c6Mt9uirQTcZlt3t' \
-H 'Content-Type: application/json' \
-H 'Postman-Token: 9017c9dc-7ce0-495e-9687-525dd6c71e34' \
-H 'cache-control: no-cache' \
-d ' {
"Data": {
"DebtorAccount": {
"SchemeName": "UK.OBIE.IBAN",
"Identification": "IE31BOFI90102812345678",
"Name": "Test"
},
"ExpirationDateTime": "2019-08-02T00:00:00+00:00"
}
} '
**POST response: funds confirmation consents
HTTP/1.1 201 Created
Content-Type: application/json
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
{
"Data": {
"Consent ID": "32b38fdb-6707-434f-94d8-8274702c8cc7",
"CreationDateTime": "2019-02-07T07:11:11+00:00",
"Status": "AwaitingAuthorisation",
"StatusUpdateDateTime": "2019-02-07T07:11:11+00:00",
"ExpirationDateTime": "2019-08-02T00:00:00+00:00",
"DebtorAccount": {
"SchemeName": "UK.OBIE.IBAN",
"Identification": "IE31BOFI90102812345678",
"Name": "Test"
}
},
"Links": {
"Self": "https://api-sandbox.bankofireland.com/1/api/open-banking/v3.1.8/cbpii/funds-confirmation-consents/32b38fdb-6707-434f-94d8-8274702c8cc7"
},
"Meta": {}
}
A CBPII may use this endpoint along with the Consent ID to retrieve the funds confirmation consent resource that they have created to check its status.
GET request: funds confirmation consents
curl -X GET \
https://api-sandbox.bankofireland.com/1/api/open-banking/v3.1.8/cbpii/funds-confirmation-consents/32b38fdb-6707-434f-94d8-8274702c8cc7 \
-H 'Authorization: Bearer Qlqrdrtjpbu2c6Mt9uirQTcZlt3t' \
-H 'Content-Type: application/json' \
-H 'Postman-Token: 188e8949-515b-4e8a-8e68-9d56657c5121' \
-H 'cache-control: no-cache' \
GET response: funds confirmation consents
{
"Data": {
"Consent Id": "32b38fdb-6707-434f-94d8-8274702c8cc7",
"CreationDateTime": "2019-02-07T07:11:11+00:00",
"Status": "Authorised",
"StatusUpdateDateTime": "2019-02-07T07:16:45+00:00",
"ExpirationDateTime": "2019-08-02T00:00:00+00:00",
"DebtorAccount": {
"SchemeName": "UK.OBIE.IBAN",
"Identification": "IE31BOFI90102812345678",
"Name": "Test"
}
},
"Links": {
"Self": "https://api-sandbox.bankofireland.com/1/api/open-banking/v3.1.8/cbpii/funds-confirmation-consents/32b38fdb-6707-434f-94d8-8274702c8cc7"
},
"Meta": {}
}
DELETE /funds-confirmation-consents
If the PSU revokes consent to confirm funds with the CBPII, the CBPII must delete the funds confirmation consent resource using this endpoint.
DELETE request: funds confirmation consents
curl -X DELETE \
https://api-sandbox.bankofireland.com/1/api/open-banking/v3.1.8/cbpii/funds-confirmation-consents/32b38fdb-6707-434f-94d8-8274702c8cc7 \
-H 'Authorization: Bearer Qlqrdrtjpbu2c6Mt9uirQTcZlt3t' \
-H 'Content-Type: application/json' \
-H 'Postman-Token: 34a9a45e-7a11-4b4d-8024-414c332cf18d' \
-H 'cache-control: no-cache' \
DELETE response: funds confirmation consents
204 OK
3. Authorise Consent
CBPII receives a Consent ID. The CBPII then creates an Authorisation request (using a signed JWT request containing the Consent ID as a claim) for the PSU to give explicit consent to BOI to respond to confirmation of funds requests from the CBPII. 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=code id_token=openid fundsconfirmations=af0ifjsldkj=n-0S6_WzA2Mj=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjZwSXp3bDBILWF6X2g5Y0VPejQ4UXdfT0tuOCJ9.eyJpc3MiOiIxT0V3WUFLSWdNdGVmdk9LZlNFZEFTIiwiYXVkIjoiaHR0cHM6Ly9hdXRoLXNhbmRib3guYXBpYm9pdGVzdC5jb20iLCJyZXNwb25zZV90eXBlIjoiY29kZSBpZF90b2tlbiIsImNsaWVudF9pZCI6IjFPRXdZQUtJZ010ZWZ2T0tmU0VkQVMiLCJyZWRpcmVjdF91cmkiOiJodHRwczovL3d3dy5nZXRwb3N0bWFuLmNvbS9vYXV0aDIvY2FsbGJhY2siLCJzY29wZSI6Im9wZW5pZCBwYXltZW50cyIsInN0YXRlIjoiYWYwaWZqc2xka2oiLCJub25jZSI6Im4tMFM2X1d6QTJNaiIsIm1heF9hZ2UiOjg2NDAwLCJjbGFpbXMiOnsiaWRfdG9rZW4iOnsib3BlbmJhbmtpbmdfaW50ZW50X2lkIjp7InZhbHVlIjoiNWQyYjhjZTUtNjgxYS00Njc5LWE3OWEtZTY0ZWYxZjk5YWI3IiwiZXNzZW50aWFsICI6dHJ1ZX19fX0.ixb_5CFU5St6GMVxgN5-piN5YUYl6KQPnsiyEbxXkhKEPwMbD7PMthvHCuKfOsFNNTnB5FIleUIDbuWrQUdMWCCA_XJPh9DwjmQagvYbuv-1W2nBrqQTCSPAB_eNCoIBujlY5JXHoIaWKqfe3mrt-b4Q874SHHlkskhw0YVwjPTTY9EPszhWYztVL6_EelQH11UA5rhg_5MaRTw_XKR-I6qvDmToU6f3PI6KNoSTONX-f9MjVuN8P3u9hNSbcArvEchYxD5ShFZ8VH14zx9cV7ewbAJQjaE0sFbacvfdhOaP8kfDn1Jgk1Gf1Hmb_n48jZFiKA9PBaGTnDTku9uW1g=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 application registered in the Tpp portal |
state | af0ifjsldkj | The state as specified by the TPP |
scope | openid fundsconfirmations | 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 fundsconfirmations", "state": "af0ifjsldkj", "nonce": "n-0S6_WzA2Mj", "max_age": 86400, "claims": { "id_token": { "openbanking_intent_id": { "value": "5d2b8ce5-681a-4679-a79a-e64ef1f99ab7", "essential ": true } } } } | Refer 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 portal.
Parameters of payload are:
|
For more details on request object creation follow below link:
https://openbankinguk.github.io/read-write-api-site3/v3.1.8/profiles/confirmation-of-funds-api-profile.html
4. Get Access Token to invoke APIs
CBPIIs must use a 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=60fz5pcnuvTOZh6zv9TK_vEkRVxjsVW2BA1RvDtU=https://www.getpostman.com/oauth2/callback=1OEwYAKIgMtefvOKfSEdAS'
Request Parameters :
Parameter | Example value | Description |
---|---|---|
grant_type | authorisation_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. Funds Confirmation
POST: funds confirmations
CBPII may use this endpoint to confirm funds with BOI, create a new funds confirmation resource, and check the funds available flag in the response.
POST request: funds confirmations
curl -X POST \
https://api-sandbox.bankofireland.com/1/api/open-banking/v3.1.8/cbpii/funds-confirmations \
-H 'Authorization: Bearer 82jSFsx9C313vHvYeQGooUSHasxf' \
-H 'Content-Type: application/json' \
-H 'Postman-Token: b4d305f5-0b35-4f8e-9254-a0de14190a31' \
-H 'cache-control: no-cache' \
-H 'x-idempotency-key: PRESssCgrgdxgseg.52343' \
-d '{
"Data": {
"Reference":"sdfgdfg",
"ConsentId": "32b38fdb-6707-434f-94d8-8274702c8cc7",
"InstructedAmount": {
"Amount": "400.50",
"Currency": "GBP"
}
}
}'
POST response: funds confirmations
{
"Data": {
"FundsConfirmationId": "66a2ce9c-217e-4651-aa09-6b6695c74927",
"ConsentId": "32b38fdb-6707-434f-94d8-8274702c8cc7",
"CreationDateTime": "2019-02-07T07:18:28+00:00",
"FundsAvailable": true,
"Reference": "sdfgdfg",
"InstructedAmount": {
"Amount": "400.50",
"Currency": "GBP"
}
},
"Links": {
"Self": "https://api-sandbox.bankofireland.com/1/api/open-banking/v3.1.8/cbpii/funds-confirmations/66a2ce9c-217e-4651-aa09-6b6695c74927"
},
"Meta": {}
}
Versioning
This API specification conforms to Open Banking UK ,Confirmation of Funds API Specification – v3.1.8