Versions Compared

Version Old Version 1 New Version Current
Changes made by

Chris Michael

Gavin Wong

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Expand
titleMENU
Table of Contents
stylenone

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.

...

  • 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:

...

  • 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 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.

...

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.

...

Code Block
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

Code Block
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

Code Block
languagebash
GET /auth?client_id=c8422787-1dff-424d-b620-356c0870bed4&request_uri=urn:ietf:params:oauth:request_uri:6esc_11ACC5bwc014ltc14eY22c
Host: openbanking.lfi.ae

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

The LFI confirms the payment consent in the OFP.

Code Block
languagebash
POST /auth/aac-69255d98-ab0e-4758-92a7-cacbf3073efa/rp/doConfirm
host: auth1.lab.openbanking.ae
Content-Type: application/x-www-form-urlencoded
DebtorAccount.IdentificationType=UAEOF.IBAN
&CreditorAccount.IdentificationType=UAEOF.IBAN
...

3.6 The LFI Returns an Authorization Code to the TPP

Code Block
languagebash
302 Found
Location: https://openbanking.tpp1.ae/simple-redirect-url?
code=ce2aeabf-599c-4475-9171-1f6d8c1a49dc
&state=2616df22-899e-468b-b7af-927145b067cc

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

Code Block
languagebash
POST /token HTTP/1.1
Host: as1.lab.openbanking.ae
Content-Type: application/x-www-form-urlencoded
Accept: application/json
grant_type=authorization_code
&code=ce2aeabf-599c-4475-9171-1f6d8c1a49dc
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJIUzI1NiJ9.ew0KICAiaXNzIjogImM4NDIyNzg3LTFkZmYtNDI0ZC1iNjIwLTM1NmMwODcwYmVkNCIsDQogICJzdWIiOiAiYzg0MjI3ODctMWRmZi00MjRkLWI2MjAtMzU2YzA4NzBiZWQ0IiwNCiAgImF1ZCI6ICJhdXRoMS5sYWIub3BlbmJhbmtpbmcuc2EiLA0KICJqdGkiOiAiYThmZDQ2ZjctYTNiMy00MGQ5LTk2ZjctNDk1YmEyMGFiMTZmIiwNCiAgImV4cCI6IDE1MTYyMzkwMjINCn0.nvY2tG7D3_ioVI55nRJ7apBzoGbP9sofMLd7Dni4YbI
&redirect_uri=https%3A%2F%2Fopenbanking.tpp1.ae%2Fsimple-redirect-url

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

Code Block
languagebash
HTTP/1.1 200 OK
Content-Type:application/json
{
    "access_token": "caa1b60d-61ff-4cd8-a4e1-2d18c8696de0",
    "expires_in": 432000,
    "token_type": "Bearer",
    "scope": "openid%20payments",
    "state": "2616df22-899e-468b-b7af-927145b067cc",
    "refresh_token": "266f5f15-eb81-4a02-bf05-e25063ca445f"
}

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

Code Block
languagebash
POST /open-finance/payment/2024.03.11-draft1/payments HTTP/1.1
Host: rs1.openfinanceplatform.ae
Content-Type: application/jwt
Accept: application/jwt
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
x-idempotency-key: 78dae4513b8847f98e2d4173b4ed0eb6
Authorization: Bearer caa1b60d-61ff-4cd8-a4e1-2d18c8696de0
{
  "alg": "PS256",
  "kid": "e1be6bf3-76e6-4e53-92b9-c46423757ab1"
}
.
{
  "iss": "string",
  "exp": 0.5,
  "nbf": 0.5,
  "aud": [
    "string"
  ],
  "iat": 0.5,
  "message": {
    "Data": {
      "ConsentId": "aac-69255d98-ab0e-4758-92a7-cacbf3073efa",
      "Type": "UAEOF.FixedRecurringPayment",
      "Instruction": {
        "Amount": {
          "Amount": "100.00",
          "Currency": "AED"
        },
        "BeneficiaryReference": "string",
        "PaymentSequenceNumber": "1"
      },
      "PaymentPurposeCode": "ABCD",
      "PayerReference": "string"
    }
  }
}
.
<<signature>>

3.9.2 Response: payments Resource

Code Block
languagebash
HTTP/1.1 201 Created
Content-Type: application/jwt
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
{
  "alg": "PS256",
  "kid": "e1be6bf3-76e6-4e53-92b9-c46423757ab1"
}
.
{
  "iss": "string",
  "exp": 0.5,
  "nbf": 0.5,
  "aud": [
    "string"
  ],
  "iat": 0.5,
  "message": {
    "Data": {
      "PaymentId": "83b47199-90c2-4c05-9ef1-aeae68b0fc7c",
      "ConsentId": "aac-69255d98-ab0e-4758-92a7-cacbf3073efa",
      "Type": "UAEOF.FixedRecurringPayment",
      "PaymentTransactionId": "string",
      "PaymentStatus": "Pending",
      "PaymentStatusUpdateDateTime": "2023-10-01T00:00:00.000Z",
      "CreationDateTime": "2023-10-01T00:00:00.000Z",
      "DebtorCharges": [
        {
          "Type": "VAT",
          "Amount": {
            "Amount": "100.00",
            "Currency": "AED"
          }
        }
      ],
      "Instruction": {
        "Amount": {
          "Amount": "100.00",
          "Currency": "AED"
        },
        "BeneficiaryReference": "string",
        "PaymentSequenceNumber": "1"
      },
      "PaymentPurposeCode": "ABCD",
      "PayerReference": "string"
    },
    "Links": {
      "Self": "/payments/83b47199-90c2-4c05-9ef1-aeae68b0fc7c",
      "Related": "/payment-consents/aac-69255d98-ab0e-4758-92a7-cacbf3073efa"
    },
    "Meta": {}
  }
}
.
<<signature>>

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

Code Block
languagebash
GET /open-finance/payment/2024.03.11-draft1/payments/83b47199-90c2-4c05-9ef1-aeae68b0fc7c HTTP/1.1
Host: rs1.openfinanceplatform.ae
Accept: application/jwt
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
Authorization: Bearer ad297304-1057-4c68-9e76-a96f300a27f1

3.10.2 Response: /payments/{PaymentId} Resource

Code Block
languagebash
HTTP/1.1 200 OK
Content-Type: application/jwt
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
{
  "alg": "PS256",
  "kid": "e1be6bf3-76e6-4e53-92b9-c46423757ab1"
}
.
{
  "iss": "string",
  "exp": 0.5,
  "nbf": 0.5,
  "aud": [
    "string"
  ],
  "iat": 0.5,
  "message": {
    "Data": {
      "PaymentId": "83b47199-90c2-4c05-9ef1-aeae68b0fc7c",
      "ConsentId": "aac-69255d98-ab0e-4758-92a7-cacbf3073efa",
      "Type": "UAEOF.FixedRecurringPayment",
      "PaymentTransactionId": "string",
      "PaymentStatus": "Pending",
      "PaymentStatusUpdateDateTime": "2023-10-01T00:00:00.000Z",
      "CreationDateTime": "2023-10-01T00:00:00.000Z",
      "DebtorCharges": [
        {
          "Type": "VAT",
          "Amount": {
            "Amount": "100.00",
            "Currency": "AED"
          }
        }
      ],
      "Instruction": {
        "Amount": {
          "Amount": "100.00",
          "Currency": "AED"
        },
        "BeneficiaryReference": "string",
        "PaymentSequenceNumber": "1"
      },
      "PaymentPurposeCode": "ABCD",
      "PayerReference": "string"
    },
    "Links": {
      "Self": "/payments/83b47199-90c2-4c05-9ef1-aeae68b0fc7c",
      "Related": "/payment-consents/aac-69255d98-ab0e-4758-92a7-cacbf3073efa"
    },
    "Meta": {}
  }
}
.
<<signature>>

4. Further Payment Examples

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

4.1.1 Request: payments/{PaymentId} Resource

Code Block
languagebash
GET /open-finance/payment/2024.03.11-draft1/payments/83b47199-90c2-4c05-9ef1-aeae68b0fc7c HTTP/1.1
Host: rs1.openfinanceplatform.ae
Accept: application/jwt
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
Authorization: Bearer ad297304-1057-4c68-9e76-a96f300a27f1

4.1.2 Response: payments/{PaymentId} Resource

Code Block
HTTP/1.1 401 Unauthorized
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
Content-Type: application/jwt
{
  "alg": "PS256",
  "kid": "e1be6bf3-76e6-4e53-92b9-c46423757ab1"
}
.
{
  "iss": "string",
  "exp": 0,
  "nbf": 0,
  "aud": [
    "string"
  ],
  "iat": 0,
  "message": {
    "Errors": [
      {
        "Code": "UAEOF.AccessToken.Unauthorized",
        "Message": "max_age_exceeded: Token has expired",
        "Path": "Authorization",
        "Url": "https://developer.openfinanceplatform.ae/api-errros/401"
      }
    ]
  }
}
.
<<signature>>

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

Code Block
{
    "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"
            }
        },
        "Subscription": {
          "Webhook": {
            "Url": "https://api.tpp.com/webhook/callbackUrl",
            "IsActive": true
          }
        }
      }
    }
  ]
}

4.2.2 The TPP updates a Webhook Subscription preference with the OFP

4.2.2.1 Request: Activate Webhook events

Code Block
languagebash
PATCH /open-finance/payment/2024.03.11-draft1/payment-consents/aac-69255d98-ab0e-4758-92a7-cacbf3073efa HTTP/1.1
Host: rs1.lab.api.openbanking.ae
Content-Type: application/jwt
Accept: application/jwt
x-fapi-interaction-id: 3424a379-8274-4686-99bd-f420d08acead
Authorization: Bearer ad297304-1057-4c68-9e76-a96f300a27f1
{
  "alg": "PS256",
  "kid": "e1be6bf3-76e6-4e53-92b9-c46423757ab1"
}
.
{
  "iss": "string",
  "exp": 0,
  "nbf": 0,
  "aud": [
    "string"
  ],
  "iat": 0,
  "message": {
    "Subscription": {
      "Webhook": {
        "IsActive": true
      }
    }
  }
}
.
<<signature>>

4.2.2.2 Response: Webhook events activated

Code Block
languagebash
x-fapi-interaction-id: 3424a379-8274-4686-99bd-f420d08acead
HTTP/1.1 204 No Content

4.2.3 The TPP unsubscribes their Webhook Subscription with the OFP

4.2.3.1 Request: De-Activate Webhook events

Code Block
languagebash
PATCH /open-finance/payment/2024.03.11-draft1/payment-consents/aac-69255d98-ab0e-4758-92a7-cacbf3073efa HTTP/1.1
Host: rs1.lab.api.openbanking.ae
Content-Type: application/jwt
x-fapi-interaction-id: 3424a379-8274-4686-99bd-f420d08acead
Authorization: Bearer ad297304-1057-4c68-9e76-a96f300a27f1
{
  "alg": "PS256",
  "kid": "e1be6bf3-76e6-4e53-92b9-c46423757ab1"
}
.
{
  "iss": "string",
  "exp": 0,
  "nbf": 0,
  "aud": [
    "string"
  ],
  "iat": 0,
  "message": {
    "Subscription": {
      "Webhook": {
        "IsActive": false
      }
    }
  }
}
.
<<signature>>

4.2.3.2 Response: Webhook events de-activated

Code Block
languagebash
x-fapi-interaction-id: 3424a379-8274-4686-99bd-f420d08acead
HTTP/1.1 204 No Content

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.

Code Block
languagebash
{
  "alg": "PS256",
  "typ": "JOSE",
  "cty": "json",
  "kid":  "e1be6bf3-76e6-4e53-92b9-c46423757ab1"
}
.
{
 "iss": "https://openbanking.masrif-ahmar.ae",
 "sub": "e75c26bf-1682-401a-a227-ec125f6636ab",
 "aud": "https://api.pisp.com/webhook/callbackUrl",
 "exp": 1661378066,
 "iat": 1661378036,
 "nbf": 1661378036,
 "jti": "274aa39d-d77a-46a9-b832-b2ced47919dd"
}
.
<<signature>>

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

...

Code Block
languagebash
{
  "alg": "PS256",
  "kid": "e1be6bf3-76e6-4e53-92b9-c46423757ab1"
}
.
{
  "iss": "string",
  "exp": 0.5,
  "nbf": 0.5,
  "aud": [
    "string"
  ],
  "iat": 0.5,
  "message": {
    "Data": {
      "ConsentId": "aac-69255d98-ab0e-4758-92a7-cacbf3073efa",
      "BaseConsentId": "abc-19877d98-ab0e-4758-92a7-vvffr1234abv",
      "AcceptedAuthorizationType": "UAEOF.Single",
      "AuthorizationExpirationTimeWindow": "720:00:00",
      "ExpirationDateTime": "2024-10-01T00:00:00.000Z",
      "ConsentStatus": "AwaitingAuthorization",
      "ConsentStatusUpdateDateTime": "2023-10-01T00:00:00.000Z",
      "CreationDateTime": "2023-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"
      },
      "IsPayByAccount": false,
      "PaymentConsumption": {
        "MaximumCumulativeNumberOfPayments": 10,
        "MaximumCumulativeValueOfPayments": "1000.00",
        "CumulativeNumberOfPayments": 0,
        "CumulativeValueOfPayments": "0.00",
        "CumulativeNumberOfPaymentsPerPeriod": 0,
        "CumulativeValueOfPaymentsPerPeriod": "0.00"
      }
    },
    "Links": {
      "Self": "/payment-consents/aac-69255d98-ab0e-4758-92a7-cacbf3073efa",
      "Related": []
    },
    "EventMeta": {
      "EventDateTime": "22023-10-01T00:00:00.000Z",
      "EventResource": "consents",
      "EventType": "UAEOF.Resource.Created",
      "ConsentId": "aac-69255d98-ab0e-4758-92a7-cacbf3073efa"
    }
  }
}
.
<<signature>>

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

Code Block
languagebash
x-fapi-interaction-id: 77b0e830-b095-4c6c-94e8-20f83eaa799f
HTTP/1.1 202 Accepted

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.

Code Block
languagebash
{
    "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.Multi",
              "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"
              }
            }
        }
    ]
}

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

Code Block
languagebash
HEAD /open-finance/payment/2024.03.11-draft1/payments HTTP/1.1
Host: rs1.lab.api.openbanking.ae
Accept: application/jwt
x-fapi-interaction-id: 942a7ee7-d29a-45aa-93b7-c5f292d86602
Authorization: Bearer ad297304-1057-4c68-9e76-a96f300a27f1
x-idempotency-key: 78dae4513b8847f98e2d4173b4ed0eb6

4.4.2 Response to /payments Resource

Code Block
languagebash
HTTP/1.1 204 No Content
x-fapi-interaction-id: 3424a379-8274-4686-99bd-f420d08acead
Location: /open-finance/payment/2024.03.11-draft1/payments/83b47199-90c2-4c05-9ef1-aeae68b0fc7c

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;

...

  • 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:

...

  • 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.

  • MaximumCumulativeNumberOfPaymentsMUST 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.

  • MaximumCumulativeNumberOfPaymentsMUST 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.