openapi: 3.0.0
info:
title: UAE Confirmation of Payee API
description: '## UAE Open Finance Confirmation of Payee API Specification'
version: v1.0-draft4
tags:
- name: Discovery
- name: Verification
paths:
/confirmation-of-payee/v1/discovery:
post:
tags:
- Discovery
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/DiscoverVerificationSourceResponseBodySigned
'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/DiscoverVerificationSourceRequestBodySigned'
security:
- TPPOAuth2Security:
- openid
- confirmation-of-payee
/confirmation-of-payee/v1/verification:
post:
tags:
- Verification
operationId: ConfirmationOfPayeeVerification_signedVerificationRequest
summary: Verify the account details 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 IBAN. 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/NameVerificationResponseBodySigned'
'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/NameVerificationRequestBodySigned'
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:
AEAccountDiscovery:
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
AEAccountNameMatchIndicators:
type: string
enum:
- UAEOF.ConfirmationOfPayee.Yes
- UAEOF.ConfirmationOfPayee.No
AEAccountNameVerificationProperties:
oneOf:
- $ref: '#/components/schemas/AEPersonalAccountNameVerificationProperties'
- $ref: '#/components/schemas/AEBusinessAccountNameVerificationProperties'
AEAccountVerificationProperties:
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:
type$ref: string'#/components/schemas/AEAccountNameVerificationProperties'
additionalProperties: false
minLengthAEBusinessAccountNameVerificationProperties: 1
type: object
maxLength: 70 required:
description: >- BusinessName
properties:
The account name is theBusinessName:
name or names of the User account owner(s) type: string
minLength: 1
maxLength: 140
description: The representedbusiness name atof anthe account levelholder, as understood by the payer
description: The properties required to verify a business account
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
AENameVerificationRequest:
type: object
required:
- Data
properties:
Data:
$ref: '#/components/schemas/AEAccountVerificationProperties'
additionalProperties: false
AENameVerificationResponse:
type: object
required:
- Data
- Links
- Meta
properties:
Data:
$ref: '#/components/schemas/AEVerifiedProperties'
Links:
$ref: '#/components/schemas/LinksSelf'
Meta:
$ref: '#/components/schemas/Meta'
additionalProperties: false
AEPersonalAccountNameVerificationProperties:
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
AEVerificationDiscovery:
$ref: '#/components/schemas/AEAccountDiscovery'
AEVerificationDiscoveryRequest:
type: object
required:
- Data
properties:
Data:
$ref: '#/components/schemas/AEVerificationDiscovery'
additionalProperties: false
AEVerificationDiscoveryResponse:
type: object
required:
- Data
- Links
- Meta
properties:
Data:
$ref: '#/components/schemas/AEVerificationSourceProperties'
Links:
$ref: '#/components/schemas/LinksSelf'
Meta:
$ref: '#/components/schemas/Meta'
additionalProperties: false
AEVerificationSourceProperties:
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
AEVerifiedProperties:
type: object
required:
- AccountNameMatchIndicator
properties:
AccountNameMatchIndicator:
allOf:
- $ref: '#/components/schemas/AEAccountNameMatchIndicators'
description: >-
Indicator for whether the payee name is matched with the account
name held at the LFI
additionalProperties: false
DiscoverVerificationSourceRequestBodySigned:
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/AEVerificationDiscoveryRequest'
additionalProperties: false
DiscoverVerificationSourceResponseBodySigned:
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/AEVerificationDiscoveryResponse'
additionalProperties: false
DiscoverVerificationSourceSignedRequest:
type: object
required:
- requestBody
properties:
requestBody:
$ref: '#/components/schemas/DiscoverVerificationSourceRequestBodySigned'
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
NameVerificationRequestBodySigned:
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/AENameVerificationRequest'
additionalProperties: false
NameVerificationResponseBodySigned:
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/AENameVerificationResponse'
additionalProperties: false
NameVerificationSignedRequest:
type: object
required:
- requestBody
properties:
requestBody:
$ref: '#/components/schemas/NameVerificationRequestBodySigned'
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
|