1. API Flows
1.1 Step 1: Solicit or Retrieve Payee account details
The flow MUST begin with the TPP either:
Prompting the User for the Payee account details, where the account details are solicited from the User.
Retrieving the Payee account details where they are stored by the TPP
In both cases the TPP will agree with the User that the details appear to correlate with the intended Payee before invoking any Confirmation of Payee operation.
1.2 Step 2: Discover LFI that holds the Payee account
The TPP MUST have a valid access token (with scope), solicited using the Client Credentials grant type, from the OFP Authorization Server to call the Discover operation.
The TPP MUST create a request payload that contains the IBAN for the Payee account, signed and encoded as a JSON Web Signature (JWS) for purposes of non-repudiation. The Content-type header field will be set to application/jwt to indicate that request is a JWS.
The TPP MUST call the Discover operation to retrieve the correct OFP Authorization Server and Resource Server URLs for the LFI that holds the account. The request body must include the IBAN for the payee account.
The OFP MUST resolve the IBAN sent by the TPP to the correct OFP Authorization Server and Resource URLs for the LFI that holds the payee account. The Authorization Server and Resource Server URLs will be used to create the response body, which will be signed and encoded as a JWS for purposes of non-repudiation.
The OFP MUST return a 200 OK together with the response body containing the Authorization Server and Resource Server URLs. The Content-type header field will be set to application/jwt to indicate that response is a JWS.
1.3 Step 3: Verify Payee Account Details at the LFI
The TPP MUST have a valid access token (with scope), solicited using the Client Credentials grant type, using the OFP Authorization Server URL returned in Step 2.
The TPP MUST create a request payload that contains the IBAN for the Payee account and the account name as understood by the User, signed and encoded as a JSON Web Signature (JWS) for purposes of non-repudiation. The Content-type header field will be set to application/jwt to indicate that request is a JWS.
The TPP MUST use the Resource Server URL, together with the request payload, returned from Step 2 to call the Verify operation.
The OFP MUST resolve the IBAN to the correct AccountId value at the LFI.
The OFP MUST call the Parties endpoint at the LFI to retrieve the account holder name, using the AccountId value to address the correct account.
The LFI MUST respond with 200 OK together with the properties of the account holder.
The OFP MUST check the account name provided in the request and name returned by the LFI match, setting the match indicator according to the outcome. The indicator will be used to create the response body, which will be signed and encoded as a JWS for purposes of non-repudiation.
The OFP MUST return a 200 OK together with the response body containing the account name match indicator. The Content-type header field will be set to application/jwt to indicate that response is a JWS.
2. Confirmation of Payee Sequence Diagrams
The Confirmation of Payee flows illustrate the API interactions completing successfully, with no API Errors.
3. Confirmation of Payee Examples
The following are non-normative examples of API access and usage of the Service Initiation API.
3.1 The TPP Requests an Access Token to Discover the Account-Holding LFI
3.1.1 Request: Access Token Request using the Client Credentials Grant Type
POST /open-finance/auth/v1/as HTTP/1.1 Host: auth1.openfinanceplatform.ae Content-Type: application/x-www-form-urlencoded Accept: application/json client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer &client_assertion=eyJhbGciOiJIUzI1NiJ9.ew0KICAiaXNzIjogImM4NDIyNzg3LTFkZmYtNDI0ZC1iNjIwLTM1NmMwODcwYmVkNCIsDQogICJzdWIiOiAiYzg0MjI3ODctMWRmZi00MjRkLWI2MjAtMzU2YzA4NzBiZWQ0IiwNCiAgImF1ZCI6ICJhdXRoMS5sYWIub3BlbmJhbmtpbmcuc2EiLA0KICJqdGkiOiAiYThmZDQ2ZjctYTNiMy00MGQ5LTk2ZjctNDk1YmEyMGFiMTZmIiwNCiAgImV4cCI6IDE1MTYyMzkwMjINCn0.nvY2tG7D3_ioVI55nRJ7apBzoGbP9sofMLd7Dni4YbI &grant_type=client_credentials &scope=openid%20confirmation-of-payee
3.1.2 Response: Access Token
HTTP/1.1 200 OK
Content-Type:application/json
{
"access_token": "54234c74-8ab7-4633-bc3d-ce050695751c",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "openid confirmation-of-payee"
}
3.2 The TPP Invokes the Discovery Operation to Discover the Account-Holding LFI
3.2.1 Request: Discover Authorization Server and Resource Server URLs for Account-Holding LFI
POST /open-finance/confirmation-of-payee/v1/discover HTTP/1.1
Host: rs1.openfinanceplatform.ae
Content-Type: application/jwt
Accept: application/jwt
x-fapi-interaction-id: 8b92e2c6-e0b6-4bc2-92e7-dae085a8141c
Authorization: Bearer 54234c74-8ab7-4633-bc3d-ce050695751c
{
"alg": "PS256",
"kid": "44310147-3249-40cf-a85f-d197a29f9b1b"
}
.
{
"iss": "string",
"exp": 0.5,
"nbf": 0.5,
"aud": [
"string"
],
"iat": 0.5,
"message": {
"Data": {
"IdentificationType": "UAEOF.IBAN",
"Identification": "AE070331234567890123456"
}
}
}
.
<<signature>>
3.2.2 Response: Authorization Server and Resource Server URLs to Invoke Verify Operation
HTTP/1.1 200 OK
Content-Type:application/jwt
x-fapi-interaction-id: 8b92e2c6-e0b6-4bc2-92e7-dae085a8141c
{
"alg": "PS256",
"kid": "c3cce1fa-e3c1-4901-bf70-e3bd33c42bfb"
}
.
{
"iss": "string",
"exp": 0.5,
"nbf": 0.5,
"aud": [
"string"
],
"iat": 0.5,
"message": {
"Data": {
"AuthorizationServerUrl": "https:/lfi1.openfinance.ae/open-finance/auth/v1/as",
"ResourceServerUrl": "https:/lfi1.openfinance.ae/open-finance/confirmation-of-payee/v1/verification"
}
}
}
.
<<signature>>
3.3. The TPP Requests an Access Token to Verify the Payee Account Name
3.3.1 Request: Access Token Request using the Client Credentials Grant Type at the LFI Authorization Server Instance
POST /open-finance/auth/v1/as HTTP/1.1 Host: lfi1.openfinanceplatform.ae Content-Type: application/x-www-form-urlencoded Accept: application/json client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer &client_assertion=eyJhbGciOiJIUzI1NiJ9.ew0KICAiaXNzIjogImM4NDIyNzg3LTFkZmYtNDI0ZC1iNjIwLTM1NmMwODcwYmVkNCIsDQogICJzdWIiOiAiYzg0MjI3ODctMWRmZi00MjRkLWI2MjAtMzU2YzA4NzBiZWQ0IiwNCiAgImF1ZCI6ICJhdXRoMS5sYWIub3BlbmJhbmtpbmcuc2EiLA0KICJqdGkiOiAiYThmZDQ2ZjctYTNiMy00MGQ5LTk2ZjctNDk1YmEyMGFiMTZmIiwNCiAgImV4cCI6IDE1MTYyMzkwMjINCn0.nvY2tG7D3_ioVI55nRJ7apBzoGbP9sofMLd7Dni4YbI &grant_type=client_credentials &scope=openid%20confirmation-of-payee
3.3.2 Response: Access Token
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "77c38589-a158-4eda-8b9f-279dc98d1635",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "openid confirmation-of-payee"
}
3.4 The TPP Invokes the Verify Operation for the Payee Account Name
3.4.1 Request: TPP Sends Account Details as JSON Web Signature
POST /open-finance/confirmation-of-payee/v1/verification HTTP/1.1
Host: lfi1.openfinanceplatform.ae
Content-Type: application/jwt
Accept: application/jwt
x-fapi-interaction-id: 1a1f0c67-1120-4b4b-abf3-7f5cd5979189
Authorization: Bearer 77c38589-a158-4eda-8b9f-279dc98d1635
{
"alg": "PS256",
"kid": "44310147-3249-40cf-a85f-d197a29f9b1b"
}
.
{
"iss": "string",
"exp": 0.5,
"nbf": 0.5,
"aud": [
"string"
],
"iat": 0.5,
"message": {
"Data": {
"IdentificationType": "UAEOF.IBAN",
"Identification": "AE070331234567890123456",
"Name": {
"GivenName": "Mohammed",
"FamilyName": "Al-Nakheel"
}
}
}
}
.
<<signature>>
3.4.2 Request: OFP Sends Parties Request to LFI
GET /accounts/277a98ef-ae29-49f0-9b25-08c4479f94fc/party Host: api.examplebank.ae Accept: application/json
3.4.3 Response: Parties Response from LFI
HTTP/1.1 200 OK
Content-Type: application/json
{
"Data": {
"Party": [
...
"Claims": {
"GivenName": "Mohammed",
"FamilyName": "Al-Nakheel"
}
]
}
}
3.4.4 Response: Name Verification Response
HTTP/1.1 200 OK
Content-Type: application/jwt
{
"alg": "PS256",
"kid": "29b362fc-c46c-460e-98b5-2a8af073e6aa"
}
.
{
"iss": "string",
"exp": 0.5,
"nbf": 0.5,
"aud": [
"string"
],
"iat": 0.5,
"message": {
"Data": {
"AccountNameMatchIndicator": "UAEOF.ConfirmationOfPayee.Yes"
}
}
}
.
<<signature>>
5. OpenAPI Specification
See the Confirmation of Payee - OpenAPI Documentation page.
6. Confirmation of Payee Notes
The Confirmation of Payee API only supports signed requests and responses. All request and response payloads must be encoded as a JWS.
The examples of retrieving the Party information from the LFI only show the bare payloads and do not include the security approach implemented between the OFP and LFI, which varies based on LFI preferences.
7. Security
A confirmation-of-payee scope is used for the Discover and Verify operations.