OBIE Read/Write Confirmation of Funds (CBPII) API v3.1.2 - lets FCA-authorised card-based payment instrument issuers set up a funds confirmation consent and confirm whether a specified amount is available on a consenting YBS or Chelsea Building Society account. FAPI-secured (OAuth2/OIDC, mTLS, PSD2 SCA).
openapi: 3.0.1
info:
title: Confirmation of Funds API Specification
description: OpenAPI for Confirmation of Funds API Specification
termsOfService: 'https://www.openbanking.org.uk/terms'
contact:
name: Service Desk
email: ServiceDesk@openbanking.org.uk
license:
name: open-licence
url: 'https://www.openbanking.org.uk/open-licence'
version: v3.1.2
paths:
/funds-confirmation-consents:
post:
tags:
- Funds Confirmations
summary: Create Funds Confirmation Consent
operationId: CreateFundsConfirmationConsents
parameters:
- $ref: '#/components/parameters/x-fapi-auth-date'
- $ref: '#/components/parameters/x-fapi-customer-ip-address'
- $ref: '#/components/parameters/x-fapi-interaction-id'
- $ref: '#/components/parameters/Authorization'
responses:
'201':
$ref: '#/components/responses/201FundsConfirmationConsentsCreated'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'405':
$ref: '#/components/responses/405Error'
'406':
$ref: '#/components/responses/406Error'
'429':
$ref: '#/components/responses/429Error'
'500':
$ref: '#/components/responses/500Error'
security:
- TPPOAuth2Security:
- fundsconfirmations
requestBody:
$ref: '#/components/requestBodies/OBFundsConfirmationConsent1Param'
'/funds-confirmation-consents/{ConsentId}':
get:
tags:
- Funds Confirmations
summary: Get Funds Confirmation Consent
operationId: GetFundsConfirmationConsentsConsentId
parameters:
- $ref: '#/components/parameters/ConsentId'
- $ref: '#/components/parameters/x-fapi-auth-date'
- $ref: '#/components/parameters/x-fapi-customer-ip-address'
- $ref: '#/components/parameters/x-fapi-interaction-id'
- $ref: '#/components/parameters/Authorization'
responses:
'200':
$ref: '#/components/responses/200FundsConfirmationConsentsConsentIdRead'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'405':
$ref: '#/components/responses/405Error'
'406':
$ref: '#/components/responses/406Error'
'429':
$ref: '#/components/responses/429Error'
'500':
$ref: '#/components/responses/500Error'
security:
- TPPOAuth2Security:
- fundsconfirmations
delete:
tags:
- Funds Confirmations
summary: Delete Funds Confirmation Consent
operationId: DeleteFundsConfirmationConsentsConsentId
parameters:
- $ref: '#/components/parameters/ConsentId'
- $ref: '#/components/parameters/x-fapi-auth-date'
- $ref: '#/components/parameters/x-fapi-customer-ip-address'
- $ref: '#/components/parameters/x-fapi-interaction-id'
- $ref: '#/components/parameters/Authorization'
responses:
'204':
$ref: '#/components/responses/204FundsConfirmationConsentsConsentIdDeleted'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'405':
$ref: '#/components/responses/405Error'
'406':
$ref: '#/components/responses/406Error'
'429':
$ref: '#/components/responses/429Error'
'500':
$ref: '#/components/responses/500Error'
security:
- TPPOAuth2Security:
- fundsconfirmations
/funds-confirmations:
post:
tags:
- Funds Confirmations
summary: Create Funds Confirmation
operationId: CreateFundsConfirmations
parameters:
- $ref: '#/components/parameters/x-fapi-auth-date'
- $ref: '#/components/parameters/x-fapi-customer-ip-address'
- $ref: '#/components/parameters/x-fapi-interaction-id'
- $ref: '#/components/parameters/Authorization'
responses:
'201':
$ref: '#/components/responses/201FundsConfirmationsCreated'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'405':
$ref: '#/components/responses/405Error'
'406':
$ref: '#/components/responses/406Error'
'429':
$ref: '#/components/responses/429Error'
'500':
$ref: '#/components/responses/500Error'
security:
- PSUOAuth2Security:
- fundsconfirmations
requestBody:
$ref: '#/components/requestBodies/OBFundsConfirmation1Param'
components:
parameters:
ConsentId:
name: ConsentId
in: path
description: ConsentId
required: true
schema:
type: string
Authorization:
in: header
name: Authorization
required: true
description: 'An Authorisation Token as per https://tools.ietf.org/html/rfc6750'
schema:
type: string
x-customer-user-agent:
in: header
name: x-customer-user-agent
description: Indicates the user-agent that the PSU is using.
required: false
schema:
type: string
x-fapi-customer-ip-address:
in: header
name: x-fapi-customer-ip-address
required: false
description: The PSU's IP address if the PSU is currently logged in with the TPP.
schema:
type: string
x-fapi-auth-date:
in: header
name: x-fapi-auth-date
required: false
description: >-
The time when the PSU last logged in with the TPP.
All dates in the HTTP headers are represented as RFC 7231 Full Dates. An
example is below:
Sun, 10 Sep 2017 19:43:31 UTC
schema:
type: string
pattern: >-
^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2}
(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4}
\d{2}:\d{2}:\d{2} (GMT|UTC)$
x-fapi-interaction-id:
in: header
name: x-fapi-interaction-id
required: false
description: An RFC4122 UID used as a correlation id.
schema:
type: string
x-idempotency-key:
name: x-idempotency-key
in: header
description: |
Every request will be processed only once per x-idempotency-key. The
Idempotency Key will be valid for 24 hours.
required: true
schema:
type: string
pattern: ^(?!\s)(.*)(\S)$
maxLength: 40
x-jws-signature:
in: header
name: x-jws-signature
required: true
description: A detached JWS signature of the body of the payload.
schema:
type: string
requestBodies:
OBFundsConfirmationConsent1Param:
description: Default
content:
application/json:
schema:
$ref: '#/components/schemas/OBFundsConfirmationConsent1'
required: true
OBFundsConfirmation1Param:
description: Default
content:
application/json:
schema:
$ref: '#/components/schemas/OBFundsConfirmation1'
required: true
responses:
201FundsConfirmationConsentsCreated:
description: Funds Confirmation Consent Created
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/OBFundsConfirmationConsentResponse1'
200FundsConfirmationConsentsConsentIdRead:
description: Funds Confirmation Consent Read
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/OBFundsConfirmationConsentResponse1'
204FundsConfirmationConsentsConsentIdDeleted:
description: Funds Confirmation Consent Deleted
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
schema:
type: string
201FundsConfirmationsCreated:
description: Funds Confirmation Created
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/OBFundsConfirmationResponse1'
400Error:
description: Bad request
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/OBErrorResponse1'
401Error:
description: Unauthorized
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
schema:
type: string
403Error:
description: Forbidden
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/OBErrorResponse1'
404Error:
description: Not found
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
schema:
type: string
405Error:
description: Method Not Allowed
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
schema:
type: string
406Error:
description: Not Acceptable
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
schema:
type: string
415Error:
description: Unsupported Media Type
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
schema:
type: string
429Error:
description: Too Many Requests
headers:
Retry-After:
description: Number in seconds to wait
schema:
type: integer
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
schema:
type: string
500Error:
description: Internal Server Error
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/OBErrorResponse1'
schemas:
ISODateTime:
description: >-
All dates in the JSON payloads are represented in ISO 8601 date-time
format.
All date-time fields in responses must include the timezone. An example
is below:
2017-04-05T10:43:07+00:00
type: string
format: date-time
Links:
type: object
description: Links relevant to the payload
properties:
Self:
type: string
format: uri
First:
type: string
format: uri
Prev:
type: string
format: uri
Next:
type: string
format: uri
Last:
type: string
format: uri
additionalProperties: false
required:
- Self
Meta:
title: MetaData
type: object
description: Meta Data relevant to the payload
properties:
TotalPages:
type: integer
format: int32
FirstAvailableDateTime:
$ref: '#/components/schemas/ISODateTime'
LastAvailableDateTime:
$ref: '#/components/schemas/ISODateTime'
additionalProperties: false
OBError1:
type: object
properties:
ErrorCode:
description: 'Low level textual error code, e.g., UK.OBIE.Field.Missing'
type: string
x-namespaced-enum:
- UK.OBIE.Field.Expected
- UK.OBIE.Field.Invalid
- UK.OBIE.Field.InvalidDate
- UK.OBIE.Field.Missing
- UK.OBIE.Field.Unexpected
- UK.OBIE.Header.Invalid
- UK.OBIE.Header.Missing
- UK.OBIE.Reauthenticate
- UK.OBIE.Resource.ConsentMismatch
- UK.OBIE.Resource.InvalidConsentStatus
- UK.OBIE.Resource.InvalidFormat
- UK.OBIE.Resource.NotFound
- UK.OBIE.Rules.AfterCutOffDateTime
- UK.OBIE.Rules.DuplicateReference
- UK.OBIE.Signature.Invalid
- UK.OBIE.Signature.InvalidClaim
- UK.OBIE.Signature.Malformed
- UK.OBIE.Signature.Missing
- UK.OBIE.Signature.MissingClaim
- UK.OBIE.Signature.Unexpected
- UK.OBIE.UnexpectedError
- UK.OBIE.Unsupported.AccountIdentifier
- UK.OBIE.Unsupported.AccountSecondaryIdentifier
- UK.OBIE.Unsupported.Currency
- UK.OBIE.Unsupported.Frequency
- UK.OBIE.Unsupported.LocalInstrument
- UK.OBIE.Unsupported.Scheme
Message:
description: >-
A description of the error that occurred. e.g., 'A mandatory field
isn't supplied' or 'RequestedExecutionDateTime must be in future'
OBIE doesn't standardise this field
type: string
minLength: 1
maxLength: 500
Path:
description: >-
Recommended but optional reference to the JSON Path of the field
with error, e.g., Data.Initiation.InstructedAmount.Currency
type: string
minLength: 1
maxLength: 500
Url:
description: >-
URL to help remediate the problem, or provide more information, or
to API Reference, or help etc
type: string
required:
- ErrorCode
- Message
additionalProperties: false
minProperties: 1
OBErrorResponse1:
description: >-
An array of detail error codes, and messages, and URLs to documentation
to help remediation.
type: object
properties:
Code:
description: 'High level textual error code, to help categorize the errors.'
type: string
minLength: 1
maxLength: 40
Id:
description: >-
A unique reference for the error instance, for audit purposes, in
case of unknown/unclassified errors.
type: string
minLength: 1
maxLength: 40
Message:
description: >-
Brief Error message, e.g., 'There is something wrong with the
request parameters provided'
type: string
minLength: 1
maxLength: 500
Errors:
items:
$ref: '#/components/schemas/OBError1'
type: array
minItems: 1
required:
- Code
- Message
- Errors
additionalProperties: false
OBFundsConfirmation1:
type: object
required:
- Data
properties:
Data:
type: object
required:
- ConsentId
- Reference
- InstructedAmount
properties:
ConsentId:
description: >-
Unique identification as assigned by the ASPSP to uniquely
identify the funds confirmation consent resource.
type: string
minLength: 1
maxLength: 128
Reference:
description: >-
Unique reference, as assigned by the CBPII, to unambiguously
refer to the request related to the payment transaction.
type: string
minLength: 1
maxLength: 35
InstructedAmount:
type: object
required:
- Amount
- Currency
description: >-
Amount of money to be confirmed as available funds in the debtor
account. Contains an Amount and a Currency.
properties:
Amount:
description: >-
A number of monetary units specified in an active currency
where the unit of currency is explicit and compliant with
ISO 4217.
type: string
pattern: '^\d{1,13}\.\d{1,5}$'
Currency:
description: >-
A code allocated to a currency by a Maintenance Agency under
an international identification scheme, as described in the
latest edition of the international standard ISO 4217 "Codes
for the representation of currencies and funds".
type: string
pattern: '^[A-Z]{3,3}$'
OBFundsConfirmationConsent1:
type: object
required:
- Data
properties:
Data:
type: object
required:
- DebtorAccount
properties:
ExpirationDateTime:
description: >-
Specified date and time the funds confirmation authorisation
will expire.
If this is not populated, the authorisation will be open ended.All dates in the JSON payloads are represented in ISO 8601 date-time format.
All date-time fields in responses must include the timezone. An
example is below:
2017-04-05T10:43:07+00:00
type: string
format: date-time
DebtorAccount:
type: object
required:
- SchemeName
- Identification
description: >-
Unambiguous identification of the account of the debtor to which
a confirmation of funds consent will be applied.
properties:
SchemeName:
description: >-
Name of the identification scheme, in a coded form as
published in an external list.
type: string
x-namespaced-enum:
- UK.OBIE.BBAN
- UK.OBIE.IBAN
- UK.OBIE.PAN
- UK.OBIE.Paym
- UK.OBIE.SortCodeAccountNumber
Identification:
description: >-
Identification assigned by an institution to identify an
account. This identification is known by the account owner.
type: string
minLength: 1
maxLength: 256
Name:
description: >-
Name of the account, as assigned by the account servicing
institution.
Usage: The account name is the name or names of the account
owner(s) represented at an account level. The account name
is not the product name or the nickname of the account.
type: string
minLength: 1
maxLength: 70
SecondaryIdentification:
description: >-
This is secondary identification of the account, as assigned
by the account servicing institution.
This can be used by building societies to additionally
identify accounts with a roll number (in addition to a sort
code and account number combination).
type: string
minLength: 1
maxLength: 34
OBFundsConfirmationConsentResponse1:
type: object
required:
- Data
properties:
Data:
type: object
required:
- ConsentId
- CreationDateTime
- Status
- StatusUpdateDateTime
- DebtorAccount
properties:
ConsentId:
description: >-
Unique identification as assigned to identify the funds
confirmation consent resource.
type: string
minLength: 1
maxLength: 128
CreationDateTime:
description: >-
Date and time at which the resource was created.All dates in the
JSON payloads are represented in ISO 8601 date-time format.
All date-time fields in responses must include the timezone. An
example is below:
2017-04-05T10:43:07+00:00
type: string
format: date-time
Status:
description: Specifies the status of consent resource in code form.
type: string
enum:
- Authorised
- AwaitingAuthorisation
- Rejected
- Revoked
StatusUpdateDateTime:
description: >-
Date and time at which the resource status was updated.All dates
in the JSON payloads are represented in ISO 8601 date-time
format.
All date-time fields in responses must include the timezone. An
example is below:
2017-04-05T10:43:07+00:00
type: string
format: date-time
ExpirationDateTime:
description: >-
Specified date and time the funds confirmation authorisation
will expire.
If this is not populated, the authorisation will be open
ended.All dates in the JSON payloads are represented in ISO 8601
date-time format.
All date-time fields in responses must include the timezone. An
example is below:
2017-04-05T10:43:07+00:00
type: string
format: date-time
DebtorAccount:
type: object
required:
- SchemeName
- Identification
description: >-
Unambiguous identification of the account of the debtor to which
a confirmation of funds consent will be applied.
properties:
SchemeName:
description: >-
Name of the identification scheme, in a coded form as
published in an external list.
type: string
x-namespaced-enum:
- UK.OBIE.BBAN
- UK.OBIE.IBAN
- UK.OBIE.PAN
- UK.OBIE.Paym
- UK.OBIE.SortCodeAccountNumber
Identification:
description: >-
Identification assigned by an institution to identify an
account. This identification is known by the account owner.
type: string
minLength: 1
maxLength: 256
Name:
description: >-
Name of the account, as assigned by the account servicing
institution.
Usage: The account name is the name or names of the account
owner(s) represented at an account level. The account name
is not the product name or the nickname of the account.
type: string
minLength: 1
maxLength: 70
SecondaryIdentification:
description: >-
This is secondary identification of the account, as assigned
by the account servicing institution.
This can be used by building societies to additionally
identify accounts with a roll number (in addition to a sort
code and account number combination).
type: string
minLength: 1
maxLength: 34
Links:
$ref: '#/components/schemas/Links'
Meta:
$ref: '#/components/schemas/Meta'
OBFundsConfirmationResponse1:
type: object
required:
- Data
properties:
Data:
type: object
required:
- FundsConfirmationId
- ConsentId
- CreationDateTime
- FundsAvailable
- Reference
- InstructedAmount
properties:
FundsConfirmationId:
description: >-
Unique identification as assigned by the ASPSP to uniquely
identify the funds confirmation resource.
type: string
minLength: 1
maxLength: 40
ConsentId:
description: >-
Unique identification as assigned by the ASPSP to uniquely
identify the funds confirmation consent resource.
type: string
minLength: 1
maxLength: 128
CreationDateTime:
description: >-
Date and time at which the resource was created.All dates in the
JSON payloads are represented in ISO 8601 date-time format.
All date-time fields in responses must include the timezone. An
example is below:
2017-04-05T10:43:07+00:00
type: string
format: date-time
FundsAvailable:
description: Flag to indicate the result of a confirmation of funds check.
type: boolean
Reference:
description: >-
Unique reference, as assigned by the CBPII, to unambiguously
refer to the request related to the payment transaction.
type: string
minLength: 1
maxLength: 35
InstructedAmount:
type: object
required:
- Amount
- Currency
description: >-
Amount of money to be confirmed as available funds in the debtor
account. Contains an Amount and a Currency.
properties:
Amount:
description: >-
A number of monetary units specified in an active currency
where the unit of currency is explicit and compliant with
ISO 4217.
type: string
pattern: '^\d{1,13}\.\d{1,5}$'
Currency:
description: >-
A code allocated to a currency by a Maintenance Agency under
an international identification scheme, as described in the
latest edition of the international standard ISO 4217 "Codes
for the representation of currencies and funds".
type: string
pattern: '^[A-Z]{3,3}$'
Links:
$ref: '#/components/schemas/Links'
Meta:
$ref: '#/components/schemas/Meta'
securitySchemes:
TPPOAuth2Security:
type: oauth2
description: TPP client credential authorisation flow with the ASPSP
flows:
clientCredentials:
tokenUrl: 'https://authserver.example/token'
scopes:
fundsconfirmations: Funds confirmation entitlement
PSUOAuth2Security:
type: oauth2
description: >-
OAuth flow, it is required when the PSU needs to perform SCA with the
ASPSP when a TPP wants to access an ASPSP resource owned by the PSU
flows:
authorizationCode:
authorizationUrl: 'https://authserver.example/authorization'
tokenUrl: 'https://authserver.example/token'
scopes:
fundsconfirmations: Funds confirmation entitlement