1. API Flows

1.1 Step 1: Agree Service Initiation Consent

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

1.2 Step 2: Authorize Service Initiation Consent

The TPP MUST now request the User to authorize the consent. Please refer to the Authentication and Authorization page , 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 Service Initiation consent

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

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

The TPP MAY, within in the Service Initiation Consent (where applicable):

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

1.2.1 Service Initiation Consent Types

The OFP MUST link both PaymentId and ConsentId:

In the Service Initiation resource (PaymentId) set Links.Related to the authorized ConsentId used to create the Service Initiation.
In the Service Initiation consent 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 Service Initiation

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 Service Initiation resource with the OFP resource server.

The LFI MUST return a 201 Status Code together to acknowledge the creation of the new Service Initiation 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 Service Initiation resource when provided with a valid access token request from the TPP.

1.4 Step 4: Access the Service Initiation 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 the Content-Type as application/jwt when creating a Service Initiation resource with the OFP, together with the resource identifier from Step 3.

The OFP MUST respond with the TPP request with a signed JWT with a Service Initiation resource. This ensures non-repudiation for Service Initiation.

2. Service Initiation Sequence Diagrams

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

3. Service Initiation Examples

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

3.1 The TPP Redirects the User to Authorize the Service Initiation 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 with these values:

kid is a valid signing key ID for the TPP on the Open Finance Directory
iss is client id (UUID v4)
state is a UUID v4 value
response_type MUST be code
redirect_uri is the TPP’s redirect URI

The authorization_details contain the User’s service initiation consent details, and a UUID v4 which is a unique identifier for the Service Initiation consent.

{
    "typ": "JWT",
    "alg": "PS256",
    "kid": "e4ce77c498e77000a25aa7b40e4a83f9"
}
.
{
    "iss": "s6BhdRkqt3",
    "aud": "https://server.example.com",
    "response_type": "code",
    "redirect_uri": "https://openbanking.tpp1.ae/simple-redirect-url",
    "scope": "openid payments",
    "state": "2616df22-899e-468b-b7af-927145b067cc",
    "authorization_details": [
        {
            "type": "urn:openfinanceuae:service-initiation-consent:v1.0-draft2",
            "consent": {
              "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": {
                    "MaximumCumulativeNumberOfPayments": 10,
                    "PeriodicSchedule": {
                      "Type": "UAEOF.VariablePeriodicSchedule",
                      "PeriodType": "Day",
                      "PeriodStartDate": "2023-10-01",
                      "MaximumCumulativeValueOfPaymentsPerPeriodType": {
                        "Amount": "100.00",
                        "Currency": "AED"
                      }
                    }
                  }
                }
              },
              "PersonalIdentifiableInformation": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ.UGhIOguC7...aQeF_PXwJZ4g.48V1_ALb6US04U3b.5eym5T...QzAAE=.XFBoMY...wifLw",
              "PayerReference": "string",
              "BeneficiaryReference": "string",
              "PaymentPurposeCode": "ABCD",
              "SponsoredTPPInformation": {
                "Name": "string",
                "Identification": "string"
              }
            }
        }
    ]
}

Create the RAR Request using the signed JWT, and authenticated using private_key_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 Service Initiation 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 Service Initiation 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 Service Initiation resource using the access token.

3.9 The TPP Initiates a Service Initiation Request with the OFP

3.9.1 Request: `payments` Resource

3.9.2 Response: `payments` Resource

3.10 The TPP Retrieves the Service Initiation Status from the OFP Using the Resource Identifier

Get the Service Initiation Status from the OFP as a JWT response

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

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

4. Further Service Initiation Examples

4.1 The TPP Queries the Service Initiation 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 Service Initiation Consent Request on Behalf of the User with a Webhook Subscription

4.2.1.1 Request: Service Initiation 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 Service Initiation 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 Service Initiation 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: Service Initiation consent resource requesting Multi-Authorization

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

4.4 The TPP Queries the existence of a Service Initiation 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 the Bank Service Initiation API - Swagger page.

6. Service Initiation Notes

6.1 Staging a Service Initiation Consent

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 PATCH to manage any Webhook configurations for the entire duration of a payment consent
MAY use a GET to the /payments/{PaymentId} resource to poll for Payment Statuses.

The OFP:

MUST reject the Service Initiation consent if a globally unique UUID v4 ConsentId does not exist 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 immediately stage the payment with the LFI once a valid Service Initiation 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.

6.2 Service Initiation 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

These consent parameters are defined to control the limits for a long lived Multi-Payment consent:

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.
Amount MUST be used if there is a fixed value that will be used for every recurring payment in the Period.
PeriodicSchedule MAY further define any period specific maximum payment numbers and/or amounts, and is one of these Types:
- UAEOF.DefinedSchedule - a Payment Schedule denoting a list of pre-defined future dated payments all with fixed amounts and dates.
- UAEOF.FixedPeriodicSchedule - Payment Controls that apply to all payments in a given period with a fixed payment amount.
- UAEOF.VariablePeriodicSchedule - Payment Controls that apply to all payments in a given period with a variable payment amount..

6.2.3 Combined Payment Consent Parameters

A Combined Service Initiation MUST be:

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

6.3 OFP Service Initiation 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 Service Initiation Consents resource (ConsentId).
- Set Consent Status to AwaitingAuthorization
- Set Meta.MultipleAuthorizers where multiple authorizations are required to authorize the Service Initiation
On a User Authorizing the Service Initiation, MUST set the following Consent Status to confirm Service Initiation 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
- When all Service Initiations have been successfully completed in a consent, the OFP MUST set the Service Initiation Consent Status to Completed.
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.

7. Security

A 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