1 1. API Flows
- 1.1 1.1 Step 1: Agree BSI Consent
- 1.2 1.2 Step 2: Authorize BSI Consent
  - 1.2.1 1.2.1 BSI Consent Types
  - 1.2.2 1.2.1 Security and Access Control
    - 1.2.2.1 Authorization Code Grant
- 1.3 1.3 Step 3: Create BSI
- 1.4 1.4 Step 4: Access the BSI Status
  - 1.4.1 1.5.1 Request Data
2 2. BSI Sequence Diagrams
3 3. BSI Examples
4 4. Further Payment Examples
5 5. Open API Specification
6 6. Payment Notes
- 6.1 6.1 Staging a Payment Consent
  - 6.1.1 6.1.1 Single Instant Payment
  - 6.1.2 6.1.2 Single Future Dated, Multi-Payment
- 6.2 6.2 Payment Consent Parameters
  - 6.2.1 6.2.1 Single Payment Consent Parameters
    - 6.2.1.1 6.2.1.1 Single Instant Payment
    - 6.2.1.2 6.2.1.2 Single Future Dated Payment
  - 6.2.2 6.2.2 Multi-Payment Consent Parameters
  - 6.2.3 6.2.3 Combined Payment Consent Parameters
- 6.3 6.3 OFP Payment Responsibilities
7 8. Security

1. API Flows

1.1 Step 1: Agree BSI Consent

The flow MUST begin with a User who provides consent to a TPP to stage a Bank Service Initiation (BSI) operation, for a LFI that they already have a relationship with.

1.2 Step 2: Authorize BSI Consent

The TPP MUST now request the User to authorize the consent. Please refer to the Authentication and Authorization , to review the supported Authorization Flows.

The TPP MUST construct a Rich Authorization Request (https://www.rfc-editor.org/rfc/rfc9396) with the authorization_details populated with the User’s payment consent

The TPP MUST include in a payment consent all mandatory data that the User intends to provide to the TPP for initiating a BSI operation.

The TPP MUST include a UUID v4 as the ConsentId as a unique identifier for the payment consent.

The TPP SHOULD, within in the BSI Consent (where applicable):

Set the AcceptedAuthorizationType field to determine if a Single or Multiple Authorizers are required.
Set the AuthorizationExpirationTimeWindow field to limit the overall time in which a Consent MUST be authorized.

1.2.1 BSI Consent Types

The TPP MUST specify a BSI consent type as one of these:

UAEOF.SingleInstantPayment
UAEOF.SingleFutureDatedPayment
UAEOF.FixedRecurringPayment
UAEOF.FixedOnDemandPayment
UAEOF.VariableRecurringPayment
UAEOF.VariableOnDemandPayment
UAEOF.VariableDefinedPayment

The OFP MUST link both PaymentId and ConsentId:

In the payment resource (PaymentId) set Links.Related to the authorized ConsentId used to create the payment.
In the payment-consents resource (ConsentId) set Links.Related to the PaymentId resource created for the Consent.

1.2.1 Security and Access Control

Authorization Code Grant

The TPP MUST use an authorization code grant to obtain a token to access all other API resources.

1.3 Step 3: Create BSI

The TPP MUST have a valid access token (with scope) from the OFP authorization server.

The TPP MUST use the valid access token to create a BSI resource with the OFP resource server.

The LFI MUST return a 201 Status Code together to acknowledge the creation of the new BSI resource when provided with a valid request from the OFP.

The OFP MUST return a 201 Status Code together to acknowledge the creation of the new BSI resource when provided with a valid access token request from the TPP.

1.4 Step 4: Access the BSI Status

1.5.1 Request Data

The TPP MUST have a valid access token (with scope) from the OFP authorization server.

The TPP MUST set their preferred Content-Type (JWT) when requesting the BSI resource from the OFP, together with the resource identifier from Step 3.

When available, the OFP MUST provide the TPP with a BSI resource, adhering to the preferred Content-Type of the TPP. Non-repudiation for data exchange SHOULD be mandated.

2. BSI Sequence Diagrams

The BSI flows illustrate the API interactions completing successfully, with no API Errors.

3. BSI Examples

The following are non-normative examples of API access and usage of the Payment API.

3.1 The TPP Redirects the User to Authorize the BSI Consent

3.1.1 Request: TPP Uses RAR (Rich Authorization Request) via a PAR (Pushed Authorization Request) Endpoint with the OFP to Obtain a Request URI

Create a RAR Request JWT.

The authorization_details contain the User’s account access consent details, and a UUID v4 which is a unique identifier for the account access consent.

{
    "typ": "JWT",
    "alg": "PS256",
    "kid": "e4ce77c498e77000a25aa7b40e4a83f9"
}
.
{
    "iss": "s6BhdRkqt3",
    "iat": 1669393154,
    "exp": 1669393496,
    "nbf": 1669393154,
    "aud": "https://server.example.com",
    "response_type": "code id_token",
    "redirect_uri": "https://openbanking.lfi.ae/auth",
    "scope": "openid accounts",
    "state": "af0ifjsldkj",
    "authorization_details": [
        {
            "Type": "PaymentConsent",
            "Data": {
              "ConsentId": "aac-69255d98-ab0e-4758-92a7-cacbf3073efa",
              "AcceptedAuthorizationType": "UAEOF.Single",
              "AuthorizationExpirationTimeWindow": "720:00:00",
              "ExpirationDateTime": "2024-10-01T00:00:00.000Z",
              "ControlParameters": {
                "IsPayByAccount": false,
                "ConsentSchedule": {
                  "MultiPayment": {
                    "Type": "UAEOF.FixedRecurringPayment",
                    "TotalNumberOfPayments": 10,
                    "PeriodicSchedule": {
                      "PeriodType": "Day",
                      "PeriodStartDate": "2023-10-01",
                      "Amount": {
                        "Amount": "100.00",
                        "Currency": "AED"
                      }
                    }
                  }
                }
              },
              "Initiation": {
                "DebtorAccount": {
                  "IdentificationType": "UAEOF.IBAN",
                  "Identification": "string",
                  "Name": {
                    "en": "string",
                    "ar": "string"
                  }
                },
                "CreditorAccount": {
                  "IdentificationType": "UAEOF.IBAN",
                  "Identification": "string",
                  "Name": {
                    "en": "string",
                    "ar": "string"
                  },
                  "TradingName": {
                    "en": "string",
                    "ar": "string"
                  }
                }
              },
              "PayerReference": "string",
              "BeneficiaryReference": "string",
              "PaymentPurposeCode": "ABCD",
              "SponsoredTPPInformation": {
                "Name": "string",
                "Identification": "string"
              }
            }
        }
    ]
}

Create the RAR Request using the signed and/or encrypted JWT. The request parameter JWT includes the ConsentId, a UUID v4 that was originally generated by the TPP.

POST /open-finance/v1/par 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
&request=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzNkJoZFJrcXQzIiwiaWF0IjoxNjY5MzkzMTU0LCJleHAiOjE2NjkzOTM0OTYsIm5iZiI6MTY2OTM5MzE1NCwiYXVkIjoiaHR0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJyZXNwb25zZV90eXBlIjoiY29kZSBpZF90b2tlbiIsInJlZGlyZWN0X3VyaSI6Imh0dHBzOi8vb3BlbmJhbmtpbmcubGZpLmFlL2F1dGgiLCJzY29wZSI6Im9wZW5pZCBhY2NvdW50cyIsInN0YXRlIjoiYWYwaWZqc2xka2oiLCJhdXRob3JpemF0aW9uX2RldGFpbHMiOlt7IlR5cGUiOiJBY2NvdW50QWNjZXNzQ29uc2VudCIsIkRhdGEiOnsiQWNjZXB0ZWRBdXRob3JpemF0aW9uVHlwZSI6IlVBRU9GLlNpbmdsZSIsIkF1dGhvcml6YXRpb25FeHBpcmF0aW9uVGltZVdpbmRvdyI6IjcyMDowMDowMCIsIkV4cGlyYXRpb25EYXRlVGltZSI6IjIwMjQtMTAtMDFUMDA6MDA6MDAuMDAwWiIsIkNvbnRyb2xQYXJhbWV0ZXJzIjp7IklzUGF5QnlBY2NvdW50IjpmYWxzZSwiQ29uc2VudFNjaGVkdWxlIjp7Ik11bHRpUGF5bWVudCI6eyJUeXBlIjoiVUFFT0YuRml4ZWRSZWN1cnJpbmdQYXltZW50IiwiVG90YWxOdW1iZXJPZlBheW1lbnRzIjoxMCwiUGVyaW9kaWNTY2hlZHVsZSI6eyJQZXJpb2RUeXBlIjoiRGF5IiwiUGVyaW9kU3RhcnREYXRlIjoiMjAyMy0xMC0wMSIsIkFtb3VudCI6eyJBbW91bnQiOiIxMDAuMDAiLCJDdXJyZW5jeSI6IkFFRCJ9fX19fSwiSW5pdGlhdGlvbiI6eyJEZWJ0b3JBY2NvdW50Ijp7IklkZW50aWZpY2F0aW9uVHlwZSI6IlVBRU9GLklCQU4iLCJJZGVudGlmaWNhdGlvbiI6InN0cmluZyIsIk5hbWUiOnsiZW4iOiJzdHJpbmciLCJhciI6InN0cmluZyJ9fSwiQ3JlZGl0b3JBY2NvdW50Ijp7IklkZW50aWZpY2F0aW9uVHlwZSI6IlVBRU9GLklCQU4iLCJJZGVudGlmaWNhdGlvbiI6InN0cmluZyIsIk5hbWUiOnsiZW4iOiJzdHJpbmciLCJhciI6InN0cmluZyJ9LCJUcmFkaW5nTmFtZSI6eyJlbiI6InN0cmluZyIsImFyIjoic3RyaW5nIn0sIkNyZWRpdG9yQWdlbnQiOiJTQVNBTUEifX0sIlBheWVyTm90ZXMiOiJzdHJpbmciLCJCZW5lZmljaWFyeUluZm9ybWF0aW9uIjp7Ik5vdGVzIjoic3RyaW5nIn0sIlBheW1lbnRQdXJwb3NlQ29kZSI6IkFCQ0QiLCJTcG9uc29yZWRUUFBJbmZvcm1hdGlvbiI6eyJOYW1lIjoic3RyaW5nIiwiSWRlbnRpZmljYXRpb24iOiJzdHJpbmcifX19XX0.Fsvm1_ffsLYqXMdLGy2Os6hMtNhXYPzFXiV8Mgd5dMs

3.1.2 Response: The OFP Provides the Request URI for the TPP

HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-cache, no-store
{
  "request_uri": "urn:ietf:params:oauth:request_uri:6esc_11ACC5bwc014ltc14eY22c",
  "expires_in": 60
}

3.4 The TPP Redirects the User to Their LFI with the Request URI to Authorize the Consent

3.5 The User Logs into Their LFI, Reviews and Authorizes the Consent

The LFI confirms the payment consent in the OFP.

3.6 The LFI Returns an Authorization Code to the TPP

3.7 The TPP Exchanges the Authorization Code for an BSI API Access Token with the OFP

3.8 The OFP Returns an Access Token, Refresh Token to the TPP

The TPP can now initiate a BSI resource using the access token.

3.9 The TPP Initiates a Payment Request with the OFP

3.9.1 Request: `payments` Resource

3.9.2 Response: `payments` Resource

3.10 The TPP Retrieves the Payment Status from the OFP Using the Resource Identifier

Get the Payment Status from the OFP as a JWT response

3.10.1 Request: /payments/{`PaymentId`} Resource

3.10.2 Response: /payments/{`PaymentId`} Resource

4. Further Payment Examples

4.1 The TPP Queries the Payments Resource Using an Expired Access Token

4.1.1 Request: payments/{`PaymentId`} Resource

4.1.2 Response: payments/{`PaymentId`} Resource

4.2 Webhooks

4.2.1 The TPP Creates a Payment Consent Request on Behalf of the User with a Webhook Subscription

4.2.1.1 Request: Payment Consent and Webhook Subscription

4.2.2 The TPP updates a Webhook Subscription preference with the OFP

4.2.2.1 Request: Activate Webhook events

4.2.2.2 Response: Webhook events activated

4.2.3 The TPP unsubscribes their Webhook Subscription with the OFP

4.2.3.1 Request: De-Activate Webhook events

4.2.3.2 Response: Webhook events de-activated

4.2.4 The TPP receives Payment Consent data from the OFP via its Webhook

4.2.4.1 The OFP generates a Self Signed JWT Authorization Token for Client Authentication with the TPP

This JWT Authorization Token MUST be set in the Authorization Header.

4.2.4.2 Request: OFP publishes signed/encrypted Payment Data to the registered Webhook Url provided by the TPP

The example below shows a signed and encrypted payload with the JWT Authorization Token set in the Authorization Header

Here, <<jwe>> is a signed and encrypted payload. The inner JWS has the structure below.

4.2.4.3 Response: TPP validates the Self Signed JWT Authorization Token from OFP, stores Payment consent data and acknowledges a success response to the OFP

4.3 Multiple Authorizations

4.3.1 Request: payment consents resource requesting Multi-Authorization

The TPP creates a Payment consent with AcceptedAuthorizationType as UAEOF.Multi denoting its support for a Multi-Authorization consent.

4.4 The TPP Queries the existence of a Payments Resource Using the X-Idempotency-Key

This is a negative scenario whereby the OFP fails to return any payments response and the TPP has no way of identifying the resource PaymentId

The PaymentId is returned within in the HTTP Location Header URL under the /payments resource.

4.4.1 Request to /payments Resource

4.4.2 Response to /payments Resource

5. Open API Specification

See Bank Service Initiation API - Swagger

6. Payment Notes

6.1 Staging a Payment Consent

6.1.1 Single Instant Payment

To manage the creation and execution of a Single Instant payment;

The TPP:

MUST provide a ConsentId in the Consent object within the authorization_details of a Rich Authorization Request.
MAY use a GET to the /payments/{PaymentId} resource to poll for Payment Statuses.

The OFP:

MUST ensure a unique ConsentId exists for a the Consent in the RAR object.
MUST validate the Consent parameters and create a Consent resource (ConsentId) that is AwaitingAuthorization when a valid RAR object is staged at the PAR endpoint.
MUST the ConsentID (using Links.Related attribute).
MUST immediately stage the payment with the LFI once a valid BSI resource is created by the TPP.
MUST send payment status events to the TPP if an active Webhook Subscription is registered within the Consent object.

The LFI:

MUST immediately stage the payment with the Payment Rails once a valid payment is staged by the OFP.
MUST emit payment status events to the OFP if an active Webhook Subscription was specified in the Consent object.

6.1.2 Single Future Dated, Multi-Payment

For Single Future Dated and Multi-Payment Consents:

The TPP:

MUST provide an ConsentId in the Consent object within the authorization_details of a Rich Authorization Request.
MAY use PATCH to manage any Webhook configurations for the entire duration of a payment consent

The OFP:

MUST validate the Consent parameters and create a Consent resource (ConsentId) that is AwaitingAuthorization when a valid RAR object is staged at the PAR endpoint.
MUST the ConsentID (using Links.Related attribute).
MUST immediately stage the payment with the LFI once a valid BSI resource is created by the TPP.
MUST send payment status events to the TPP if an active Webhook Subscription is registered within the Consent object.

The LFI:

MUST immediately stage the payment with the Payment Rails once a valid payment is staged by the OFP.
MUST emit payment status events to the OFP if an active Webhook Subscription was specified in the Consent object.

6.2 Payment Consent Parameters

6.2.1 Single Payment Consent Parameters

6.2.1.1 Single Instant Payment

A Single Instant Payment MUST meet the following criteria:

Type MUST be set to UAEOF.SingleInstantPayment
The Consent Start date is the CreationDateTime. The Consent end date (ExpirationDateTime) MUST be set to the current date.

6.2.1.2 Single Future Dated Payment

A Single Future Dated Payment MUST meet the following criteria:

Type MUST be set to UAEOF.SingleFutureDatedPayment
The Consent Start date is the CreationDateTime. The Consent end date (ExpirationDateTime) MUST NOT exceed 1 year from the current date.
RequestedExecutionDateTime MUST NOT be set to the current day. It MUST be set to a future date/time beyond the current day when the payment is to be scheduled for execution.

6.2.2 Multi-Payment Consent Parameters

6.2.2.1 Fixed Recurring Payment Consent Parameters

A Fixed Recurring Payment MUST meet the following criteria:

Type MUST be set to UAEOF.FixedRecurringPayment
UserReference MUST be set by the User
The Consent Start date is the CreationDateTime. The Consent end date (ExpirationDateTime) MUST NOT exceed 1 year from the current date.
PeriodicSchedule MUST define any period specific maximum payment numbers and/or amounts.
TotalNumberOfPayments MUST be set to confirm the total number of payments for the consent duration.

6.2.2.2 Fixed On-demand Payment Consent Parameters

A Fixed On-demand Payment MUST meet the following criteria:

Type MUST be set to UAEOF.FixedOnDemandPayment
UserReference MUST be set by the User
The Consent Start date is the CreationDateTime. The Consent end date (ExpirationDateTime) MUST NOT exceed 1 year from the current date.
Amount MUST have a fixed value that will be used for every recurring payment in the Period.
MaximumCumulativeNumberOfPayments MUST be set to confirm the total number of payments for the whole consent duration.
MaximumCumulativeValueOfPayments MUST be set to confirm the total payment amount for the whole consent duration.
PeriodicSchedule MAY define any period specific maximum payment numbers and/or amounts.

6.2.2.3 Variable Recurring Payment Consent Parameters

A Variable Recurring Payment MUST meet the following criteria:

Type MUST be set to UAEOF.VariableRecurringPayment
UserReference MUST be set by the User
The Consent Start date is the CreationDateTime. The Consent end date (ExpirationDateTime) MUST NOT exceed 1 year from the current date.
MaximumIndividualPaymentAmount MUST be set to confirm the maximum single payment amount that can be instructed.
MaximumCumulativeValueOfPayments MUST be set to confirm the total payment amount for the whole consent duration.
MaximumCumulativeNumberOfPayments MUST be set to confirm the total number of payments for the whole consent duration.
PeriodicSchedule MUST define the period start date and frequency.

6.2.2.4 Variable On-demand Payment Consent Parameters

A Variable On-demand Payment MUST meet the following criteria:

Type MUST be set to UAEOF.VariableOnDemandPayment
UserReference MUST be set by the User
The Consent Start date is the CreationDateTime. The Consent end date (ExpirationDateTime) MUST NOT exceed 1 year from the current date.
MaximumIndividualPaymentAmount MUST be set to confirm the maximum single payment amount that can be instructed.
MaximumCumulativeValueOfPayments MUST be set to confirm the total payment amount for the whole consent duration.
MaximumCumulativeNumberOfPayments MUST be set to confirm the total number of payments for the whole consent duration.
PeriodicSchedule MAY further define any period specific maximum payment numbers and/or amounts.

6.2.2.5 Variable Defined Payment Consent Parameters

A Variable Defined Payment MUST meet the following criteria for payment execution by the LFI:

Type MUST be set to UAEOF.VariableDefinedPayment
UserReference MUST be set by the User
The Consent Start date is the CreationDateTime. The Consent end date (ExpirationDateTime) MUST NOT exceed 1 year from the current date.
PaymentSchedule[] MUST define all required payments to be instructed
- .PaymentExecutionDateMUST be the exact Date when a Payment is to be debited.
- .Amount MUST be the exact Payment value to be debited.

6.2.3 Combined Payment Consent Parameters

A Combined Payment MUST be:

Any one Type of Single Payment
Any one Type of Multi-Payment

6.3 OFP Payment Responsibilities

MUST associate all TPP requests (including retries) with an X-Idempotency-Key
MUST reject all requests where an X-Idempotency-Key is not provided by the TPP for the /payments resource
On receiving the RAR request from the TPP, MUST proceed to:
- Create a Payment Consents resource (ConsentId).
- Set Consent Status to AwaitingAuthorization
- Set Meta.MultipleAuthorizers where multiple authorizations are required to authorize the Payment
On a User Authorizing the Payment, MUST set the following Consent Status to confirm Payment details:
- Set Consent Status to Authorized
On Payment rails completion, MUST set the following status based on the Payment rails outcome:
- Set PaymentStatus to either Pending, AcceptedSettlementCompleted, AcceptedCreditSettlementCompleted, AcceptedWithoutPosting, Rejected
- If a PaymentStatus is Rejected then return the PaymentStatusDetail with the appropriate Reason.Code, Reason.Detailand Message
- When all Payments have been successfully completed in a consent, the OFP MUST set the Consent Status to Finished.
MUST set the Links object across both the Payment resource and Consent resource enabling the TPP to locate those resources
MUST validate that a Payment is within any of the Consent Control parameter limits authorized by the User.
MUST send payment status Events to the TPP where a Webhook subscription has been received in the Payment request
MAY return an HTTP Location header for the 201 Status code indicating the URI of the primary resource that has been created (rfc9110)
MUST use PaymentConsumption to provide the TPP with up-to-date cumulative number and value totals of Payments associated with the Authorized Consent.

8. Security

A parameterized payments scope (with the ConsentId) is used for POST /payments.

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

Bank Service Initiation API