openapi: 3.0.0
info:
title: UAE Confirmation of Payee API
description: '## UAE Open Finance Confirmation of Payee API Specification'
version: v1.0-draft5
tags:
- name: Discovery Operations
description: Discovery operations and resources
- name: Confirmation Operations
description: Payee confirmation operations and resources
paths:
/confirmation:
post:
tags:
- Confirmation Operations
operationId: ConfirmationOfPayeeConfirmation_signedConfirmationRequest
summary: Confirm the account details are correct based on the parameters supplied
description: >-
Provide the properties that can be used to verify the payee account.
At version 1.0.0 this will be the account name and either IBAN or
Account Number. Future version of this API may support verification
through other identifiers.
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/x-customer-user-agent'
- $ref: '#/components/parameters/x-fapi-auth-date'
- $ref: '#/components/parameters/x-fapi-customer-ip-address'
- $ref: '#/components/parameters/x-fapi-interaction-id'
responses:
'200':
description: The request has succeeded.
headers:
x-fapi-interaction-id:
required: false
description: An RFC4122 UID used as a correlation id.
schema:
type: string
content:
application/jwt:
schema:
$ref: '#/components/schemas/NameConfirmationResponseBodySigned'
'400':
description: Bad request
headers:
x-fapi-interaction-id:
required: true
description: An RFC4122 UID used as a correlation id.
schema:
type: string
content:
application/jwt:
schema:
$ref: '#/components/schemas/AEErrorSignedResponse'
'401':
description: Unauthorized
headers:
x-fapi-interaction-id:
required: true
description: An RFC4122 UID used as a correlation id.
schema:
type: string
'403':
description: Forbidden
headers:
x-fapi-interaction-id:
required: true
description: An RFC4122 UID used as a correlation id.
schema:
type: string
content:
application/jwt:
schema:
$ref: '#/components/schemas/AEErrorSignedResponse'
'404':
description: Not found
headers:
x-fapi-interaction-id:
required: true
description: An RFC4122 UID used as a correlation id.
schema:
type: string
'405':
description: Method Not Allowed
headers:
x-fapi-interaction-id:
required: true
description: An RFC4122 UID used as a correlation id.
schema:
type: string
'406':
description: Not Acceptable
headers:
x-fapi-interaction-id:
required: true
description: An RFC4122 UID used as a correlation id.
schema:
type: string
'415':
description: Unsupported Media Type
headers:
x-fapi-interaction-id:
required: true
description: An RFC4122 UID used as a correlation id.
schema:
type: string
'429':
description: Too Many Requests
headers:
retry-after:
required: true
description: Number in seconds to wait
schema:
type: integer
format: int64
x-fapi-interaction-id:
required: true
description: An RFC4122 UID used as a correlation id.
schema:
type: string
'500':
description: Internal Server Error
headers:
x-fapi-interaction-id:
required: true
description: An RFC4122 UID used as a correlation id.
schema:
type: string
content:
application/jwt:
schema:
$ref: '#/components/schemas/AEErrorSignedResponse'
requestBody:
required: true
content:
application/jwt:
schema:
$ref: '#/components/schemas/NameConfirmationRequestBodySigned'
security:
- TPPOAuth2Security:
- openid
- confirmation-of-payee
/discovery:
post:
tags:
- Discovery Operations
operationId: ConfirmationOfPayeeDiscovery_signedDiscoveryRequest
summary: Discover the LFI that will confirm the payee attributes
description: >-
Before a Confirmation of Payee (CoP) operation takes place the TPP will
need to resolve the LFI that will service the account properties
request. This requirement is based on the separation of concerns
implemented in the OFP, which ensures that the APIs for a given LFI are
always physically separated.
At version 1.0.0 the TPP will call this endpoint with the account IBAN,
which will be used to resolve the correct URL with which to make the CoP
operation.
parameters:
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/x-customer-user-agent'
- $ref: '#/components/parameters/x-fapi-auth-date'
- $ref: '#/components/parameters/x-fapi-customer-ip-address'
- $ref: '#/components/parameters/x-fapi-interaction-id'
responses:
'200':
description: The request has succeeded.
headers:
x-fapi-interaction-id:
required: false
description: An RFC4122 UID used as a correlation id.
schema:
type: string
content:
application/jwt:
schema:
$ref: >-
#/components/schemas/DiscoverConfirmationSourceResponseBodySigned
'400':
description: Bad request
headers:
x-fapi-interaction-id:
required: true
description: An RFC4122 UID used as a correlation id.
schema:
type: string
content:
application/jwt:
schema:
$ref: '#/components/schemas/AEErrorSignedResponse'
'401':
description: Unauthorized
headers:
x-fapi-interaction-id:
required: true
description: An RFC4122 UID used as a correlation id.
schema:
type: string
'403':
description: Forbidden
headers:
x-fapi-interaction-id:
required: true
description: An RFC4122 UID used as a correlation id.
schema:
type: string
content:
application/jwt:
schema:
$ref: '#/components/schemas/AEErrorSignedResponse'
'404':
description: Not found
headers:
x-fapi-interaction-id:
required: true
description: An RFC4122 UID used as a correlation id.
schema:
type: string
'405':
description: Method Not Allowed
headers:
x-fapi-interaction-id:
required: true
description: An RFC4122 UID used as a correlation id.
schema:
type: string
'406':
description: Not Acceptable
headers:
x-fapi-interaction-id:
required: true
description: An RFC4122 UID used as a correlation id.
schema:
type: string
'415':
description: Unsupported Media Type
headers:
x-fapi-interaction-id:
required: true
description: An RFC4122 UID used as a correlation id.
schema:
type: string
'429':
description: Too Many Requests
headers:
retry-after:
required: true
description: Number in seconds to wait
schema:
type: integer
format: int64
x-fapi-interaction-id:
required: true
description: An RFC4122 UID used as a correlation id.
schema:
type: string
'500':
description: Internal Server Error
headers:
x-fapi-interaction-id:
required: true
description: An RFC4122 UID used as a correlation id.
schema:
type: string
content:
application/jwt:
schema:
$ref: '#/components/schemas/AEErrorSignedResponse'
requestBody:
required: true
content:
application/jwt:
schema:
$ref: '#/components/schemas/DiscoverConfirmationSourceRequestBodySigned'
security:
- TPPOAuth2Security:
- openid
- confirmation-of-payee
components:
parameters:
Authorization:
name: authorization
in: header
required: true
description: An authorization Token as per https://tools.ietf.org/html/rfc6750
schema:
type: string
x-customer-user-agent:
name: x-customer-user-agent
in: header
required: false
description: Indicates the user-agent that the User is using.
schema:
type: string
x-fapi-auth-date:
name: x-fapi-auth-date
in: header
required: false
description: >-
The time when the User 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-customer-ip-address:
name: x-fapi-customer-ip-address
in: header
required: false
description: The User's IP address if the User is currently logged in with the TPP.
schema:
type: string
x-fapi-interaction-id:
name: x-fapi-interaction-id
in: header
required: false
description: An RFC4122 UID used as a correlation id.
schema:
type: string
schemas:
AEAccountConfirmationRequest:
type: object
required:
- Data
properties:
Data:
$ref: '#/components/schemas/AEAccountConfirmationRequestProperties'
additionalProperties: false
AEAccountConfirmationRequestProperties:
oneOf:
- $ref: '#/components/schemas/AEIbanConfirmationProperties'
- $ref: '#/components/schemas/AEAccountNumberConfirmationProperties'
discriminator:
propertyName: IdentificationType
mapping:
UAEOF.IBAN: '#/components/schemas/AEIbanConfirmationProperties'
UAEOF.AccountNumber: '#/components/schemas/AEAccountNumberConfirmationProperties'
AEAccountConfirmationResponse:
type: object
required:
- Data
- Links
- Meta
properties:
Data:
$ref: '#/components/schemas/AEAccountConfirmationResponseProperties'
Links:
$ref: '#/components/schemas/LinksSelf'
Meta:
$ref: '#/components/schemas/Meta'
additionalProperties: false
AEAccountConfirmationResponseProperties:
type: object
required:
- AccountNameMatchIndicator
properties:
AccountNameMatchIndicator:
$ref: '#/components/schemas/AEAccountNameMatchIndicators'
MaskedAccountName:
type: string
minLength: 1
maxLength: 70
description: >-
The masked matched account name. This is provided to allow the User
to review the account name return from the Confirmation operation.
additionalProperties: false
AEAccountDiscoveryByBankCode:
type: object
required:
- IdentificationType
- BankCode
properties:
IdentificationType:
type: string
enum:
- UAEOF.BankCode
BankCode:
type: string
pattern: ^[0-9]{3}$
description: >-
Bank identification code issued by CBUAE that identifies the LFI at
which the account is held
additionalProperties: false
AEAccountDiscoveryByIban:
type: object
required:
- IdentificationType
- Identification
properties:
IdentificationType:
type: string
enum:
- UAEOF.IBAN
Identification:
type: string
minLength: 1
maxLength: 400
description: >-
Identification for the account assigned by the LFI based on the
Account Scheme Name, and as understood by the payer. This
identification is known by the User account owner. For IBAN, refer
to the ISO Standard 13616.
additionalProperties: false
AEAccountNameConfirmationProperties:
oneOf:
- $ref: '#/components/schemas/AEPersonalAccountNameConfirmationProperties'
- $ref: '#/components/schemas/AEBusinessAccountNameConfirmationProperties'
AEAccountNameMatchIndicators:
type: string
enum:
- UAEOF.ConfirmationOfPayee.Yes
- UAEOF.ConfirmationOfPayee.No
description: >-
Indicator for whether the payee name is matched with the account name
held at the LFI
AEAccountNumberConfirmationProperties:
type: object
required:
- IdentificationType
- Identification
- BankCode
- Name
properties:
IdentificationType:
type: string
enum:
- UAEOF.AccountNumber
Identification:
type: string
minLength: 1
maxLength: 400
description: >-
Identification for the account assigned by the LFI based on the
Account Scheme Name, and as understood by the payer. This
identification is known by the User account owner. For IBAN, refer
to the ISO Standard 13616.
BankCode:
type: string
pattern: ^[0-9]{3}$
description: >-
Bank identification code issued by CBUAE that identifies the LFI at
which the account is held
Name:
$ref: '#/components/schemas/AEAccountNameConfirmationProperties'
additionalProperties: false
AEBusinessAccountNameConfirmationProperties:
type: object
required:
- BusinessName
properties:
BusinessName:
type: string
minLength: 1
maxLength: 140
description: The business name of the account holder, as understood by the payer
description: The properties required to verify a business account
additionalProperties: false
AEConfirmationDiscovery:
oneOf:
- $ref: '#/components/schemas/AEAccountDiscoveryByIban'
- $ref: '#/components/schemas/AEAccountDiscoveryByBankCode'
discriminator:
propertyName: IdentificationType
mapping:
UAEOF.IBAN: '#/components/schemas/AEAccountDiscoveryByIban'
UAEOF.BankCode: '#/components/schemas/AEAccountDiscoveryByBankCode'
AEConfirmationDiscoveryRequest:
type: object
required:
- Data
properties:
Data:
$ref: '#/components/schemas/AEConfirmationDiscovery'
additionalProperties: false
AEConfirmationDiscoveryResponse:
type: object
required:
- Data
- Links
- Meta
properties:
Data:
$ref: '#/components/schemas/AEConfirmationSourceProperties'
Links:
$ref: '#/components/schemas/LinksSelf'
Meta:
$ref: '#/components/schemas/Meta'
additionalProperties: false
AEConfirmationSourceProperties:
type: object
required:
- AuthorizationServerUrl
- ResourceServerUrl
properties:
AuthorizationServerUrl:
type: string
minLength: 1
maxLength: 500
description: >-
Authorization Server URL at which an Access Token to invoke the
Confirmation of Payee operation should be sought
ResourceServerUrl:
type: string
minLength: 1
maxLength: 500
description: >-
Resource Server URL at which the Confirmation of Payee operation
should be invoked
additionalProperties: false
AEError:
type: object
required:
- Code
- Message
properties:
Code:
allOf:
- $ref: '#/components/schemas/AEErrorCode'
description: Low level textual error code, e.g., UAEOF.Field.Missing
Message:
type: string
minLength: 1
maxLength: 500
description: >-
A description of the error that occurred. e.g., 'A mandatory field
isn't supplied' or 'RequestedExecutionDateTime must be in future'
UAEOF doesn't standardise this field
Path:
type: string
minLength: 1
maxLength: 500
description: >-
Recommended but optional reference to the JSON Path of the field
with error, e.g., Data.Initiation.InstructedAmount.Currency
Url:
type: string
description: >-
URL to help remediate the problem, or provide more information, or
to API Reference, or help etc
description: Error
additionalProperties: false
AEErrorCode:
type: string
enum:
- UAEOF.AccessToken.Unauthorized
- UAEOF.AccessToken.InvalidScope
- UAEOF.Consent.Revoked
- UAEOF.Consent.TransientAccountAccessFailure
- UAEOF.Consent.AccountTemporarilyBlocked
- UAEOF.Consent.PermanentAccountAccessFailure
- UAEOF.Consent.Invalid
- UAEOF.JWS.InvalidSignature
- UAEOF.JWS.Malformed
- UAEOF.JWS.InvalidClaim
- UAEOF.JWS.InvalidHeader
- UAEOF.GenericRecoverableError
- UAEOF.GenericError
- UAEOF.JWE.DecryptionError
- UAEOF.JWE.InvalidHeader
- UAEOF.Event.UnexpectedEvent
- UAEOF.Body.InvalidFormat
- UAEOF.Resource.InvalidResourceId
- UAEOF.Resource.InvalidFormat
- UAEOF.Consent.BusinessRuleViolation
AEErrorResponse:
type: object
required:
- Errors
properties:
Errors:
type: array
items:
$ref: '#/components/schemas/AEError'
minItems: 1
description: >-
An array of detail error codes, and messages, and URLs to documentation
to help remediation.
additionalProperties: false
AEErrorSignedResponse:
type: object
required:
- iss
- exp
- nbf
- message
properties:
iss:
type: string
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1)
exp:
type: number
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4)
nbf:
type: number
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5)
aud:
type: array
items:
type: string
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3)
iat:
type: number
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6)
message:
$ref: '#/components/schemas/AEErrorResponse'
description: Signed error response payload
additionalProperties: false
AEIbanConfirmationProperties:
type: object
required:
- IdentificationType
- Identification
- Name
properties:
IdentificationType:
type: string
enum:
- UAEOF.IBAN
Identification:
type: string
minLength: 1
maxLength: 400
description: >-
Identification for the account assigned by the LFI based on the
Account Scheme Name, and as understood by the payer. This
identification is known by the User account owner. For IBAN, refer
to the ISO Standard 13616.
Name:
$ref: '#/components/schemas/AEAccountNameConfirmationProperties'
additionalProperties: false
AEPersonalAccountNameConfirmationProperties:
type: object
required:
- GivenName
- LastName
properties:
GivenName:
type: string
minLength: 1
maxLength: 70
description: >-
The given or first name of the account holder, as understood by the
payer
LastName:
type: string
minLength: 1
maxLength: 70
description: >-
The family or surname of the account holder, as understood by the
payer
description: The properties required to verify a personal account
additionalProperties: false
DiscoverConfirmationSourceRequestBodySigned:
type: object
required:
- iss
- exp
- nbf
- message
properties:
iss:
type: string
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1)
exp:
type: number
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4)
nbf:
type: number
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5)
aud:
type: array
items:
type: string
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3)
iat:
type: number
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6)
message:
$ref: '#/components/schemas/AEConfirmationDiscoveryRequest'
additionalProperties: false
DiscoverConfirmationSourceResponseBodySigned:
type: object
required:
- iss
- exp
- nbf
- message
properties:
iss:
type: string
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1)
exp:
type: number
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4)
nbf:
type: number
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5)
aud:
type: array
items:
type: string
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3)
iat:
type: number
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6)
message:
$ref: '#/components/schemas/AEConfirmationDiscoveryResponse'
additionalProperties: false
LinksSelf:
type: object
required:
- Self
properties:
Self:
$ref: '#/components/schemas/Self'
description: Links relevant to the resource
additionalProperties: false
Meta:
type: object
description: Metadata relevant to the resource
additionalProperties: false
NameConfirmationRequestBodySigned:
type: object
required:
- iss
- exp
- nbf
- message
properties:
iss:
type: string
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1)
exp:
type: number
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4)
nbf:
type: number
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5)
aud:
type: array
items:
type: string
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3)
iat:
type: number
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6)
message:
$ref: '#/components/schemas/AEAccountConfirmationRequest'
additionalProperties: false
NameConfirmationResponseBodySigned:
type: object
required:
- iss
- exp
- nbf
- message
properties:
iss:
type: string
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1)
exp:
type: number
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4)
nbf:
type: number
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5)
aud:
type: array
items:
type: string
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3)
iat:
type: number
description: >-
[https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6)
message:
$ref: '#/components/schemas/AEAccountConfirmationResponse'
additionalProperties: false
Self:
type: string
format: uri
description: A link to the current resource
securitySchemes:
TPPOAuth2Security:
type: oauth2
description: >-
TPP confidential client authorization with the LFI to stage a consent.
**Please refer to [OpenID FAPI Security Profile 1.0 -Part 2
Advanced](https://openid.net/specs/openid-financial-api-part-2-1_0.html#authorization-server)
- 5.2.2 point 14 - shall authenticate the confidential client using one
of the following methods private_key_jwt and [OpenID Connect Core
1.0](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication)
9. Client Authentication private_key_jwt**
flows:
clientCredentials:
tokenUrl: https://authserver.example/token
scopes:
openid: Activates OpenID Connect Support
confirmation-of-payee: Right to invoke a Confirmation of Payee operation
accounts: Ability to read Accounts Information
insurance: Right to read insurance policies
servers:
- url: /open-finance/confirmation-of-payee/v1.0-draft5
description: Default URL
variables: {}
| 