Fixed Periodic Schedule — API Guide 14 min read

Before implementing Fixed Periodic Schedule, ensure the following are in place:

• API Hub onboarded — Your API Hub instance is provisioned and your environment-specific configuration is complete.
• Enc1 key pair generated and registered — The TPP encrypts PII to your LFI's Enc1 public key. Your LFI MUST hold the corresponding private key and be able to look it up by kid.
• Consent Journey implemented — The Consent Journey API Guide MUST be implemented first. A payment cannot be initiated without an authorized consent.
• Ozone Connect connectivity verified — Bidirectional mTLS connectivity is confirmed between the API Hub and your Ozone Connect base URL. See Connectivity & Certificates.
• Fixed Periodic Schedule advertised — ApiMetadata.FixedPeriodicSchedule.Supported is set to true on your authorisation server entry in the Trust Framework.

When a TPP creates a payment consent, the API Hub calls your POST/consent/action/validate endpoint before the consent is created. Your LFI MUST validate the consent and respond with data.status: "valid" or data.status: "invalid". An invalid response prevents the consent being created and the TPP receives an error.

The full set of validation rules — standardVersion, Initiation.DebtorAccount, BaseConsentId, CurrencyRequest, payment-type support, PII conformance, creditor checks — is enumerated in Fixed Periodic Schedule Requirements — Consent Validation. The two parts that need a code walkthrough are decrypting the PII and validating the creditor; both are covered below.

Decrypting and validating the PII

The consent.PersonalIdentifiableInformation field arrives as a JWE compact string encrypted by the TPP to your LFI's Enc1 public key. The API Hub passes it through unchanged — it cannot inspect the contents and has not validated them. Decryption, schema validation, and field-level checks are entirely the LFI's responsibility.

The end-to-end flow is:

• Read the kid from the JWE protected header and look up the matching Enc1 private key
• Decrypt the JWE → recover the inner JWS
• Decode the JWS payload (signature verification is optional — the outer Ozone Connect request is itself a JWS that the API Hub has already verified, so the PII cannot have been tampered with in transit)
• Validate the decoded payload against the consent-time PII schema — AEBankServiceInitiationRichAuthorizationRequests.AEDomesticPaymentPII in uae-api-hub-consent-manager-openapi.yaml. additionalProperties: false is set at every level, so any unexpected field fails validation

Happy-path snippet:

import { compactDecrypt, importPKCS8, decodeJwt } from 'jose'

async function decryptAndValidateConsentPII(
  piiJwe: string
): Promise<Record<string, unknown>> {
  // 1. kid → private key
  const [headerB64] = piiJwe.split('.')
  const { kid } = JSON.parse(Buffer.from(headerB64, 'base64url').toString())
  const privateKey = await importPKCS8(
    enc1KeyStore.getPrivateKeyPem(kid),
    'RSA-OAEP-256'
  )

  // 2. JWE → JWS
  const { plaintext } = await compactDecrypt(piiJwe, privateKey)

  // 3. JWS → payload (signature verification is optional)
  const pii = decodeJwt(new TextDecoder().decode(plaintext))

  // 4. Schema validation against AEDomesticPaymentPII
  validateConsentPiiSchema(pii)

  return pii
}

For the per-step deep dive — kid lookup conventions, key import options, the optional JWS signature verification, building the ajv / jsonschema validator with all $ref schemas registered — see How to Decrypt PII.

The decrypted consent-time PII for a Fixed Periodic Schedule consent looks like:

{
  "Initiation": {
    "Creditor": [
      {
        "CreditorAccount": {
          "SchemeName": "IBAN",
          "Identification": "AE220331234567890876543",
          "Name": { "en": "Fatima Al Zaabi" }
        },
        "CreditorAgent": {
          "SchemeName": "BICFI",
          "Identification": "BARBAEAAXXX"
        }
      }
    ],
    "DebtorAccount": {
      "SchemeName": "IBAN",
      "Identification": "AE070331234567890123456"
    }
  },
  "Risk": {
    "PaymentContextCode": "BillPayment",
    "MerchantCategoryCode": "6012"
  },
  "iat": 1745020800,
  "exp": 1745021100,
  "iss": "tpp-client-id"
}

If decryption fails, schema validation fails, or any required field is missing, respond with invalid per Rejecting an invalid consent.

Validating the Creditor

For Fixed Periodic Schedule, Initiation.Creditor MUST be an array of exactly one entry — every periodic payment under this consent pays the same creditor. The full Creditor rules — cardinality, mandatory fields, BIC derivation — are in Creditor. This section walks through the validation in code.

The validation breaks into four parts:

• Cardinality — exactly one entry
• Mandatory fields — CreditorAccount.SchemeName == "IBAN", Identification is a syntactically valid UAE IBAN, at least one of Name.en or Name.ar is present
• BIC consistency — derive the BIC from the IBAN; if CreditorAgent.Identification was supplied it MUST match
• Domestic rail reachability — the receiving bank is reachable on AANI or UAEFTS, and (where the LFI can determine it) the receiving account is in a state that can accept a payment

Steps 1–3 are universal. Step 4 depends on each LFI's BIC directory and rail integration — the snippet below uses a stubbed lookupRailReachability(bic) interface that your LFI replaces with its own implementation.

function isValidUaeIban(iban: string): boolean {
  // UAE IBAN: AE + 21 digits = 23 chars
  if (!/^AE\d{21}$/.test(iban)) return false
  // ISO 13616 mod-97 check
  const rearranged = iban.slice(4) + iban.slice(0, 4)
  const numeric = rearranged
    .split('')
    .map(c => (/[A-Z]/.test(c) ? (c.charCodeAt(0) - 55).toString() : c))
    .join('')
  let remainder = 0
  for (const digit of numeric) {
    remainder = (remainder * 10 + Number(digit)) % 97
  }
  return remainder === 1
}

function deriveBicFromIban(iban: string): string {
  // UAE IBAN positions 5-7 (0-indexed 4-6) carry the bank code.
  return bicDirectory.lookupByUaeBankCode(iban.slice(4, 7))
}

interface InvalidResponse { status: 'invalid'; code: string; description: string }

async function validateCreditor(
  creditor: Array<{
    CreditorAccount: {
      SchemeName: string
      Identification: string
      Name?: { en?: string; ar?: string }
    }
    CreditorAgent?: { SchemeName: string; Identification: string }
  }>
): Promise<InvalidResponse | null> {
  // 1. Cardinality
  if (!Array.isArray(creditor) || creditor.length !== 1) {
    return invalid('InvalidCreditor',
      'Fixed Periodic Schedule requires exactly one creditor entry.')
  }
  const c = creditor[0]

  // 2. Mandatory fields
  if (c.CreditorAccount.SchemeName !== 'IBAN') {
    return invalid('InvalidCreditor',
      'CreditorAccount.SchemeName MUST be "IBAN" for domestic payments.')
  }
  if (!isValidUaeIban(c.CreditorAccount.Identification)) {
    return invalid('InvalidCreditor',
      'CreditorAccount.Identification is not a valid UAE IBAN.')
  }
  if (!c.CreditorAccount.Name?.en && !c.CreditorAccount.Name?.ar) {
    return invalid('InvalidCreditor',
      'CreditorAccount.Name MUST include at least one of `en` or `ar`.')
  }

  // 3. BIC consistency
  const derivedBic = deriveBicFromIban(c.CreditorAccount.Identification)
  if (c.CreditorAgent?.Identification && c.CreditorAgent.Identification !== derivedBic) {
    return invalid('InvalidCreditor',
      'CreditorAgent.Identification does not match the BIC derived from the IBAN.')
  }

  // 4. Domestic rail reachability + receiving account state
  const r = await lookupRailReachability(derivedBic)
  if (!r.reachableOnAani && !r.reachableOnUaefts) {
    return invalid('UnreachableCreditorAccount',
      'Creditor bank is not reachable on AANI or UAEFTS.')
  }
  if (r.canDetermineAccountState && !r.accountCanReceive) {
    return invalid('UnreachableCreditorAccount',
      'Creditor account cannot currently receive payments.')
  }

  return null
}

const invalid = (code: string, description: string): InvalidResponse =>
  ({ status: 'invalid', code, description })

Validating the DebtorAccount

If the TPP supplied Initiation.DebtorAccount in the consent PII, your LFI MUST also validate it before approving the consent: SchemeName is IBAN, the IBAN corresponds to an account held at this LFI and reachable through this API Hub integration, and the account is in a state that permits payment initiation (not blocked, dormant, or closed). Customer ownership of the account is not checked here — it is checked later during the authorisation journey, once the customer has authenticated.

The full check list and the invalid response shape (with code: InvalidDebtorAccount) are in Debtor Account.

Returning the validate response

If validateCreditor (or the DebtorAccount checks) returns a non-null result, return it inside data on the validate response:

{
  "data": {
    "status": "invalid",
    "code": "InvalidCreditor",
    "description": "CreditorAccount.Identification is not a valid UAE IBAN."
  },
  "meta": {}
}

See Consent Events & Actions — API Guide for the full validate request and response schema.

POST/payments is the central endpoint your LFI implements for payment execution. The API Hub calls it each time the TPP submits a periodic payment under an authorized Fixed Periodic Schedule consent. Your LFI MUST decrypt and validate the PII, match it against the consent, run the synchronous validations listed in POST /payments Requirements, create the payment record, and return 201 with the assigned PaymentId.

Screening, rail submission, and status propagation happen after the 201 response — see After returning 201.

Common request headers

Request body

Content-Type: application/json. The Hub sends a plain JSON payload (not a JWS) containing the payment details, the headers the TPP supplied, and the TPP's directory record.

Top-level fields

request.Data

For the full schema — including tpp and decodedSsa field-by-field — see the POST /payments API Reference.

Request example

{
  "requestUrl": "https://rs1.[LFICode].apihub.openfinance.ae/open-finance/payment/v2.1/payments",
  "paymentType": "cbuae-payment",
  "request": {
    "Data": {
      "ConsentId": "cac2381a-7111-4c5f-bc2f-4319a93da7c5",
      "Instruction": {
        "Amount": { "Amount": "1500.00", "Currency": "AED" }
      },
      "PaymentPurposeCode": "LOAN",
      "PersonalIdentifiableInformation": "eyJhbGciOiJSU0EtT0FFUC0yNTYi...",
      "OpenFinanceBilling": { "Type": "Collection" }
    }
  },
  "requestHeaders": {
    "o3-provider-id": "lfi-123",
    "o3-caller-org-id": "tpp-456",
    "o3-caller-client-id": "client-789",
    "o3-api-uri": "/open-finance/payment/v2.1/payments",
    "o3-api-operation": "POST",
    "o3-ozone-interaction-id": "ozone-xyz",
    "o3-consent-id": "cac2381a-7111-4c5f-bc2f-4319a93da7c5",
    "o3-psu-identifier": "eyJwczoi...",
    "x-fapi-interaction-id": "0f4d3a16-9e27-4f8d-9a5a-3a2f7e9c1b22",
    "x-idempotency-key": "idem-2026-04-18-001"
  },
  "tpp": {
    "clientId": "1675793e-d6e3-4954-96c8-acb9aaa83c53",
    "orgId": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
    "tppId": "fdd6e0ac-ba7a-4bc4-a986-c45c5daaaf00",
    "tppName": "Example TPP",
    "softwareStatementId": "XvAjPeeYZAdWwrFF..",
    "decodedSsa": {
      "client_id": "1675793e-d6e3-4954-96c8-acb9aaa83c53",
      "client_name": "Example TPP",
      "roles": ["BSIP"]
    }
  },
  "supplementaryInformation": {}
}

Reading the PII at payment time

The payment-time PII follows a different shape from the consent-time PII:

• Initiation.Creditor is a single object, not an array — the consent fixed exactly one creditor at consent time
• DebtorAccount is absent — the debtor was selected and pinned during consent authorisation
• The schema to validate against is AEBankServiceInitiation.AEDomesticPaymentPIIProperties in uae-ozone-connect-bank-service-initiation-openapi.yaml — not the consent-time schema

The decrypt + decode flow is identical to consent time — read the kid, decrypt with the matching Enc1 private key, decode the JWS payload. Re-use the helper from Decrypting and validating the PII; only swap the schema:

async function decryptAndValidatePaymentPII(piiJwe: string) {
  const pii = await decryptPii(piiJwe) // shared decrypt helper
  validatePaymentPiiSchema(pii)         // AEDomesticPaymentPIIProperties
  return pii
}

If decryption fails, reject with 400 JWE.DecryptionError. If schema validation fails (missing required field, wrong type, additional property), reject with 400 Body.InvalidFormat.

Matching the PII against the consent

Per POST /payments Requirements rule 2, the submitted creditor at payment time MUST exactly match the single creditor entry that was on the consent at consent time. Mismatch → 400 Consent.FailsControlParameters.

The link between the payment and the consent is the o3-consent-id request header (also surfaced as request.Data.ConsentId in the body). Two implementation patterns are valid; pick whichever matches your LFI's persistence model:

Pattern A — LFI persisted the decrypted creditor at consent time

The most common pattern. At consent validation, after you decrypted and validated the consent-time PII, you persisted the single creditor entry keyed by consentId. At payment time you fetch it and deep-compare against the payment-time creditor.

async function matchPaymentCreditorToConsent(
  consentId: string,
  paymentPii: { Initiation: { Creditor: ConsentTimeCreditor } }
): Promise<void> {
  const consentCreditor = await consentStore.getCreditor(consentId)
  if (!consentCreditor) {
    throw httpError(400, 'Consent.Invalid', `No stored consent for ${consentId}.`)
  }

  if (!isExactMatch(consentCreditor, paymentPii.Initiation.Creditor)) {
    throw httpError(400, 'Consent.FailsControlParameters',
      'Payment creditor does not match the creditor authorised on the consent.')
  }
}

function isExactMatch(consentCreditor: any, paymentCreditor: any): boolean {
  // Compare every field that was authorised — case-sensitive.
  return (
    consentCreditor.CreditorAccount.SchemeName === paymentCreditor.CreditorAccount.SchemeName &&
    consentCreditor.CreditorAccount.Identification === paymentCreditor.CreditorAccount.Identification &&
    consentCreditor.CreditorAccount.Name?.en === paymentCreditor.CreditorAccount.Name?.en &&
    consentCreditor.CreditorAccount.Name?.ar === paymentCreditor.CreditorAccount.Name?.ar &&
    consentCreditor.CreditorAgent?.SchemeName === paymentCreditor.CreditorAgent?.SchemeName &&
    consentCreditor.CreditorAgent?.Identification === paymentCreditor.CreditorAgent?.Identification
  )
}

Pattern B — LFI did not persist the consent-time PII

If your LFI did not persist the decrypted PII at consent time, fetch the consent from the API Hub via GET/consents/{consentId}, decrypt the consent's PersonalIdentifiableInformation field, and run the same isExactMatch comparison against Initiation.Creditor[0] (the consent-time creditor is an array of one).

Pattern B trades a stored creditor for a network round-trip and a second decryption on every payment. Choose Pattern A unless persistence is not an option for your LFI.

Response

Content-Type: application/json. Return 201 on successful payment record creation.

Example — successful initiation

{
  "data": {
    "id": "5ff155ea-853f-480c-ac74-1eaed7c1201f",
    "consentId": "cac2381a-7111-4c5f-bc2f-4319a93da7c5",
    "status": "Pending",
    "statusUpdateDateTime": "2026-04-18T10:14:23Z",
    "creationDateTime": "2026-04-18T10:14:23Z",
    "instruction": {
      "Amount": { "amount": "1500.00", "currency": "AED" }
    },
    "paymentPurposeCode": "LOAN",
    "openFinanceBilling": { "Type": "Collection" }
  },
  "meta": {}
}

Error responses

Only return an error when the request is invalid or a server condition prevents you from responding. All error bodies MUST include errorCode and errorMessage. The errorCode values are drawn from the POST /payments OpenAPI schemaError400 / Error403 enums.

400 — Bad request

403 — Forbidden

500

500 for transient/unrecoverable server errors. Use GenericRecoverableError if the Hub may retry, GenericError otherwise.

Example error response

{
  "errorCode": "Consent.FailsControlParameters",
  "errorMessage": "Payment creditor does not match the creditor authorised on the consent."
}

This endpoint updates the payment status on the API Hub. The Hub uses the update to send asynchronous notifications to TPPs and to maintain accurate state for billing and limit calculations. The LFI calls it for every Open Finance-relevant status transition after the 201 has been returned to the Hub on POST/payments.

Request headers

Path parameters

Request body

Content-Type: application/json. The PATCH body uses literal flat-key JSON (the dots are part of the key, not nested objects):

Example — successful settlement

{
  "paymentResponse.status": "AcceptedSettlementCompleted",
  "paymentResponse.paymentTransactionId": "de857816-3016-4567-86b6-8f418e36fb27"
}

Example — rail rejection

{
  "paymentResponse.status": "Rejected",
  "paymentResponse.paymentTransactionId": "de857816-3016-4567-86b6-8f418e36fb27",
  "paymentResponse.RejectReasonCode": [
    {
      "Code": "AANI.AM04",
      "Message": "Payment request cannot be executed as insufficient funds at debtor account."
    }
  ]
}

Example — LFI screening rejection

{
  "paymentResponse.status": "Rejected",
  "paymentResponse.RejectReasonCode": [
    {
      "Code": "LFI.ScreeningRejected",
      "Message": "Payment rejected by LFI screening controls."
    }
  ]
}

Response

Content-Type: application/json. A successful PATCH returns 204 No Content with no body. See the PATCH /payment-log/:id API Reference for the full schema.