Version | Date | Author | Comments |
---|---|---|---|
3.0 | OB R/W API Team | This is the baseline version. No change from RC3. Swagger URLs updated to point to latest stable version. | |
3.1-draft1 | OB R/W API Team | This is the initial draft version for 3.1 Errata:
| |
3.1-draft2 | OB R/W API Team | No Changes | |
3.1-draft3 | OB R/W API Team | Swagger Specification links updated | |
3.1-draft4 | OB R/W API Team | Swagger Specification links updated | |
3.1-RC1 | OB R/W API Team | Swagger Specification links updated | |
3.1 | OB R/W API Team | Version 3.1 final release. No changes from Version 3.1 RC1. Updated swagger links to latest release candidate. |
This specification describes the Confirmation of Funds API flows and payloads.
The API endpoints described here allow a Card Based Payment Instrument Issuer ('CBPII') to:
This specification should be read in conjunction with the Read/Write Data API Specification which provides a description of the elements that are common across all the Read/Write Data APIs.
This document consists of the following parts:
Overview: Provides an overview of the scope of the API and the key decisions and principles that contributed to the specification.
Basics: Identifies the resources, operations that are permitted on those resources, and various special cases.
Endpoints: Provides the list of endpoints for the API specification.
Security & Access Control: Specifies the means for CBPIIs to authenticate themselves and provide consent.
Swagger Specifications: Provides links to the swagger specifications for the APIs.
Resources (sub pages): Describes endpoints and data models for individual resources.
Usage Examples (sub page): Examples for normal flows, and alternate flows.
The diagram below provides a general outline of a confirmation of funds request and flow using the Confirmation of Funds APIs. It assumes a CBPII has issued a card to a PSU, and the PSU would like to use a PSD2 in-scope account as a funding mechanism for that card.
The Consent model for the Confirmation of Funds API differs to the Payments API and the Account and Transactions API, as the consent is held between the PSU and the ASPSP, rather than between the PSU and the TPP. Whilst the flow follows the same process, the context for each step has a different meaning and is detailed below.
Step 1: Agree Funds Confirmation
Step 2: Setup Funds Confirmation Consent
Step 3: Agree Funds Confirmation Consent
Step 4: Initiate Card Payment
Step 5: Confirm Funds
Step 6: Get Funds Confirmation Consent Status
participant PSU participant CBPII participant ASPSP Authorisation Server participant ASPSP Resource Server autonumber note over PSU, ASPSP Resource Server Step 1: Onboard with CBPII (Outside scope of CoF API) end note PSU -> CBPII: Onboard with CBPII and consent to Confirmation of Funds note over PSU, ASPSP Resource Server Step 2: Setup Funds Confirmation Consent end note note right of CBPII Retrieve an access-token under the Client Credentials Flow. end note CBPII -> ASPSP Authorisation Server: Initiate Client Credentials Grant ASPSP Authorisation Server --> CBPII: access-token note right of CBPII Create a funds-confirmation-consent with Status=AwaitingAuthorisation. Include access-token retrieved in [3]. end note CBPII -> ASPSP Resource Server: POST /funds-confirmation-consents state over ASPSP Resource Server: Consent Status: AwaitingAuthorisation ASPSP Resource Server --> CBPII: HTTP 201 (Created), ConsentId note right of CBPII Respond to PSU with redirection to initiate authorisation of the funds-confirmation-consent. end note note over PSU, ASPSP Resource Server Step 3: Agree Funds Confirmation Consent end note alt Redirection (Using Authorization Code Grant) CBPII --> PSU: HTTP 302 (Found), Redirect (ConsentId) PSU -> ASPSP Authorisation Server: Follow redirect (ConsentId) PSU <-> ASPSP Authorisation Server: authenticate (and SCA if required) ASPSP Authorisation Server -> ASPSP Resource Server: Update funds-confirmation-consent Status to Authorised state over ASPSP Resource Server: Consent Status: Authorised ASPSP Resource Server --> ASPSP Authorisation Server: OK note right of ASPSP Authorisation Server Create and distribute an authorization-code under the Authorization Flow. end note ASPSP Authorisation Server --> PSU: HTTP 302 (Found), Redirect (authorization-code) PSU -> CBPII: Follow redirect (authorization-code) note right of CBPII Retrieve an access-token under the Authorization Flow. This token can then be used for the funds-confirmation POST requests in step [16]. end note CBPII -> ASPSP Authorisation Server: Exchange authorization-code for access token ASPSP Authorisation Server --> CBPII: access-token else Decoupled (Using CIBA) CBPII -> ASPSP Authorisation Server: POST /bc-authorize (login_hint_token) ASPSP Authorisation Server -> CBPII: OK PSU -> ASPSP Authorisation Server: Authorise (Consent Id) PSU <-> ASPSP Authorisation Server: authenticate PSU <-> ASPSP Authorisation Server: SCA if required PSU <-> ASPSP Authorisation Server: select accounts state over ASPSP Resource Server: Consent Status: Authorised alt Using callback ASPSP Authorisation Server -> CBPII: Callback (authorization-code) CBPII <-> ASPSP Authorisation Server: Establish TLS 1.2 MA CBPII -> ASPSP Authorisation Server: Exchange authorization-code for access token ASPSP Authorisation Server -> CBPII: access-token else Using polling CBPII <-> ASPSP Authorisation Server: Establish TLS 1.2 MA CBPII -> ASPSP Authorisation Server: Poll at /token using auth-req-id ASPSP Authorisation Server -> CBPII: access-token end alt end alt note over PSU, ASPSP Resource Server Step 4: Initiate card payment (Outside scope of CoF API) end note PSU -> CBPII: Initiate card payment note over PSU, ASPSP Resource Server Step 5: Confirm Funds end note note right of CBPII Create a funds-confirmation resource. Include access-token retrieved in [14]. end note CBPII -> ASPSP Resource Server: POST /funds-confirmations ASPSP Resource Server -> ASPSP Resource Server: Validate funds-confirmation against funds-confirmation-consent ASPSP Resource Server -> ASPSP Resource Server: Establish if funds are available. ASPSP Resource Server --> CBPII: HTTP 201 (Created), FundsConfirmationId, FundsAvailable (true/false) note over PSU, ASPSP Resource Server Step 6: Get Funds Confirmation Consent Status end note CBPII -> ASPSP Resource Server: GET /funds-confirmation-consents/{FundsConfirmationRequestId} ASPSP Resource Server --> CBPII: HTTP 200 (OK) funds-confirmation-consent resource option footer=bar |
The API endpoints for creating funds-confirmation-consent and funds-confirmation resources are not idempotent.
If a time-out error occurs, we would expect a CBPII to create a new resource, rather than try with the same resource. This is particularly relevant for the funds-confirmation resource, where the availability of funds may have changed between requests.
This section overviews the release management and versioning strategy for the Account And Transaction API.
This section looks at the list of available API endpoints to access Confirmation of Funds data and optionality (definitions of mandatory, conditional or optional are defined in the Design Principles section in Read/Write Data API Specification).
For detail on the request and response objects refer to the Data Model section of the specification.
We have specified the "mandatory" endpoints for the functioning of the Confirmation of Funds APIs.
The access tokens required for accessing the Confirmation of Funds APIs must have at least the following scope:
fundsconfirmations |
CBPIIs must use a client credentials grant to obtain a token to make POST requests to the funds-confirmation-consent endpoint. In the specification, this grant type is referred to as "Client Credentials".
CBPIIs must use an authorization code grant using a redirect or decoupled flow to obtain a token to make POST requests to the funds-confirmation endpoint. When accessing, the intent-id in the token must match the ConsentId in the message payload. In the specification, this grant type is referred to as "Authorization Code".
CBPIIs must use a client credentials grant to obtain a token to make GET requests.
The CBPII must create a funds-confirmation-consent resource through a POST operation. This resource outlines the consent that the CBPII claims the PSU has committed to agreeing with the ASPSP, to retrieve confirmation of funds information. At this stage, the consent is not yet agreed between the PSU and the ASPSP.
The ASPSP responds with a ConsentId. This is the intent-id that is used when initiating the authorization code grant (as described in the Trust Framework).
As part of the authorization code grant:
Once these steps are complete, the consent is considered to have been agreed between the ASPSP and the PSU.
The funds-confirmation-consent resource consists of the following fields, which together form the elements of the consent provided by the PSU to the CBPII:
The funds-confirmation-consent resource may have one of the following status codes after authorisation has taken place:
Status | Description | |
---|---|---|
1 | Authorised | The Funds Confirmation Consent has been successfully authorised. |
2 | Rejected | The Funds Confirmation Consent has been rejected. |
3 | Revoked | The Funds Confirmation Consent has been revoked via the ASPSP interface. |
The funds-confirmation-consent resource is a long lived consent. A funds-confirmation-consent can be re-authenticated if:
Authorised and
ExpirationDateTime
, if specified, has not elapsed A PSU may revoke consent for confirming funds at any point in time.
The PSU may request the ASPSP to revoke consent that it has authorised. The mechanisms for this are in the competitive space and are up to each ASPSP to implement in the ASPSP's banking interface.
The PSU may request the CBPII to revoke consent that it has authorised. If consent is revoked with the CBPII:
The Swagger Specification for Confirmation of Funds APIs can be downloaded from the following links: