Confirmation of Funds APIs

4.0.x
(0 reviews)

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:

  1. 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
  2. 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.

85963dd4-203b-4e52-98ac-548a222566e9-image.png

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.

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.

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

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:
  • "iss" is issuer of the token i.e same as clientid.
  • "aud" is audience that the ID token intended, should be same as issuer value from /.well-known end point 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/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

Reviews