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. The requested account details must included either the IBAN or the domestic account number and bank code.

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 or the bank code 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 or the bank code for the payee account.

The OFP MUST resolve the IBAN or bank code 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: Confirm 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 or the domestic account number 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 Confirmation operation.

The OFP MUST call the Parties endpoint at the LFI to retrieve the account holder name, using the account details retrieve the party for the account being confirmed.

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. If the value of the matched indicator is UAEOF.ConfirmationOfPayee.No, the response will also contain the name that was on the account, which will be masked. 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.

UAE Confirmation of Payee Sequence Diagram.png

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/discovery 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 Confirmation Operation

3.3. The TPP Requests an Access Token to Confirm the Payee Account Name

3.3.1 Request: Access Token Request using the Client Credentials Grant Type at the LFI Authorization Server Instance

3.3.2 Response: Access Token

3.4 The TPP Invokes the Confirm Operation for the Payee Account Name

3.4.1 Request: TPP Sends Account Details as JSON Web Signature

3.4.2 Request: OFP Sends Parties Request to LFI

3.4.3 Response: Parties Response from LFI

3.4.4 Response: Name Confirmation Response

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 Confirmation operations.

Standards v1.0-draft5

This space is deprecated and no longer supported. Please use the latest available version here.

Confirmation of Payee API