Delegated SCA — API Guide 18 min read

Before implementing Delegated SCA, 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.
• Delegated SCA beneficiary models advertised — For each beneficiary model you support, the corresponding flag MUST be set to true on your authorisation server entry in the Trust Framework: ApiMetadata.DelegatedAuthentication.SingleBeneficiarySupported (consents carrying exactly 1 creditor), ApiMetadata.DelegatedAuthentication.MultipleBeneficiariesSupported (consents carrying 2–10 creditors), and/or ApiMetadata.DelegatedAuthentication.OpenBeneficiariesSupported (consents that omit Initiation.Creditor). A consent for a model the LFI has not advertised MUST be rejected at consent validation.

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, beneficiary-model support, PII conformance, creditor checks — is enumerated in Delegated SCA Requirements — Consent Validation. The two parts that need a code walkthrough are decrypting the PII and validating the creditor list; 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 Delegated SCA consent — shown here in the 2-creditor "multiple beneficiaries" shape — looks like:

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

In the "open beneficiaries" shape, Initiation.Creditor is omitted entirely and the creditor is supplied fresh on each payment at POST/payments time.

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

Validating the Creditor list

For Delegated SCA the creditor shape depends on the beneficiary model the TPP chose:

• Single beneficiary — Initiation.Creditor is an array of exactly 1 entry (ApiMetadata.DelegatedAuthentication.SingleBeneficiarySupported)
• Multiple beneficiaries — Initiation.Creditor is an array of 2–10 entries (ApiMetadata.DelegatedAuthentication.MultipleBeneficiariesSupported)
• Open beneficiaries — Initiation.Creditor is omitted entirely (ApiMetadata.DelegatedAuthentication.OpenBeneficiariesSupported). The creditor is supplied and validated at payment time — see Validating an open-beneficiary creditor at payment time

The full Creditor rules — cardinality, mandatory fields, BIC derivation — are in Creditor. This section walks through the consent-time validation in code. Each entry in the list is checked independently against the same four-part rule:

• Cardinality — 1–10 entries if present; if absent, the beneficiary model is "open" and per-entry validation is deferred to payment time
• 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 2–4 are universal; step 1 depends on the advertised beneficiary model. The snippet below covers all three models.

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 validateCreditorList(
  creditor: Array<CreditorEntry> | undefined,
  supported: {
    singleBeneficiary: boolean
    multipleBeneficiaries: boolean
    openBeneficiaries: boolean
  }
): Promise<InvalidResponse | null> {
  // Open beneficiaries — creditor omitted
  if (creditor === undefined) {
    return supported.openBeneficiaries
      ? null
      : invalid('PaymentTypeNotSupported',
          'LFI does not support open beneficiaries for Delegated SCA.')
  }

  // 1. Cardinality
  if (!Array.isArray(creditor) || creditor.length < 1 || creditor.length > 10) {
    return invalid('InvalidCreditor',
      'Initiation.Creditor must contain between 1 and 10 entries.')
  }
  if (creditor.length === 1 && !supported.singleBeneficiary) {
    return invalid('PaymentTypeNotSupported',
      'LFI does not support single-beneficiary Delegated SCA.')
  }
  if (creditor.length > 1 && !supported.multipleBeneficiaries) {
    return invalid('PaymentTypeNotSupported',
      'LFI does not support multiple-beneficiary Delegated SCA.')
  }

  // 2-4. Validate each entry
  for (const [i, c] of creditor.entries()) {
    const err = await validateSingleCreditor(c, i)
    if (err) return err
  }
  return null
}

async function validateSingleCreditor(
  c: CreditorEntry,
  index: number
): Promise<InvalidResponse | null> {
  const at = `Initiation.Creditor[${index}]`

  // 2. Mandatory fields
  if (c.CreditorAccount.SchemeName !== 'IBAN') {
    return invalid('InvalidCreditor',
      `${at}.CreditorAccount.SchemeName MUST be "IBAN" for domestic payments.`)
  }
  if (!isValidUaeIban(c.CreditorAccount.Identification)) {
    return invalid('InvalidCreditor',
      `${at}.CreditorAccount.Identification is not a valid UAE IBAN.`)
  }
  if (!c.CreditorAccount.Name?.en && !c.CreditorAccount.Name?.ar) {
    return invalid('InvalidCreditor',
      `${at}.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',
      `${at}.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',
      `${at}: creditor bank is not reachable on AANI or UAEFTS.`)
  }
  if (r.canDetermineAccountState && !r.accountCanReceive) {
    return invalid('UnreachableCreditorAccount',
      `${at}: creditor account cannot currently receive payments.`)
  }

  return null
}

interface CreditorEntry {
  CreditorAccount: {
    SchemeName: string
    Identification: string
    Name?: { en?: string; ar?: string }
  }
  CreditorAgent?: { SchemeName: string; Identification: string }
}

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 validateCreditorList (or the DebtorAccount checks) returns a non-null result, return it inside data on the validate response:

{
  "data": {
    "status": "invalid",
    "code": "InvalidCreditor",
    "description": "Initiation.Creditor[3].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 payment under an authorized Delegated SCA consent. Your LFI MUST decrypt and validate the PII, match it against the consent's creditor list (or validate the freshly-supplied creditor for open-beneficiary consents), verify the delegated-SCA assertion in Risk.DebtorIndicators.Authentication, run the synchronous validations listed in POST /payments Requirements — including the duplicate-in-flight check that is specific to on-demand consent types — 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": "125.50", "Currency": "AED" }
      },
      "PaymentPurposeCode": "GDDS",
      "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-fapi-auth-date": "Fri, 18 Apr 2026 10:14:05 GMT",
    "x-fapi-customer-ip-address": "203.0.113.42",
    "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 — each payment pays exactly one creditor, whether or not a list was fixed at consent time
• DebtorAccount is absent — the debtor was selected and pinned during consent authorisation
• Risk.DebtorIndicators.Authentication is present — the delegated-SCA assertion evidencing that the customer authenticated at the TPP for this specific payment. This field is unique to Delegated SCA
• 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 — including Risk.DebtorIndicators.Authentication for Delegated SCA — wrong type, or additional property), reject with 400 Body.InvalidFormat.

A decrypted payment-time PII for Delegated SCA looks like:

{
  "Initiation": {
    "Creditor": {
      "CreditorAccount": {
        "SchemeName": "IBAN",
        "Identification": "AE220331234567890876543",
        "Name": { "en": "Fatima Al Zaabi" }
      },
      "CreditorAgent": {
        "SchemeName": "BICFI",
        "Identification": "BARBAEAAXXX"
      }
    }
  },
  "Risk": {
    "PaymentContextCode": "EcommerceGoods",
    "MerchantCategoryCode": "5732",
    "DebtorIndicators": {
      "Authentication": {
        "Method": "MFA",
        "Factors": ["Knowledge", "Possession"],
        "AuthenticatedAt": "2026-04-18T10:14:05Z",
        "AssertionId": "tpp-sca-4d1b2e93-61a7-4c2b-9e81-f21a7d0c4e55"
      }
    }
  },
  "iat": 1745020800,
  "exp": 1745021100,
  "iss": "tpp-client-id"
}

Validating the delegated-SCA authentication assertion

Risk.DebtorIndicators.Authentication carries the proof that the customer authenticated at the TPP with Strong Customer Authentication for this specific payment. Your LFI MUST verify this block before creating the payment record — without a valid SCA assertion, the payment has no authorisation to debit the selected account.

The full rule set — Method values, required Factors, AuthenticatedAt freshness window, AssertionId uniqueness — is in Delegated SCA Requirements — Authentication Validation. The check has four parts:

• Method — MUST be MFA. Any other value → 400 Consent.FailsControlParameters
• Factors — MUST list at least two distinct SCA categories from Knowledge, Possession, Inherence
• AuthenticatedAt freshness — MUST be within 5 minutes of the current server time. Stale assertions → 400 Consent.FailsControlParameters. This MUST also be consistent with the x-fapi-auth-date FAPI header
• AssertionId — MUST be present, and MUST not have been seen under this consentId before (replay prevention). A duplicate → 400 Consent.FailsControlParameters

async function validateDelegatedScaAssertion(
  consentId: string,
  auth: {
    Method: string
    Factors: string[]
    AuthenticatedAt: string
    AssertionId: string
  }
): Promise<void> {
  // 1. Method
  if (auth.Method !== 'MFA') {
    throw httpError(400, 'Consent.FailsControlParameters',
      'Risk.DebtorIndicators.Authentication.Method MUST be "MFA".')
  }

  // 2. Factors — at least two distinct categories from the allowed set
  const allowed = new Set(['Knowledge', 'Possession', 'Inherence'])
  const factors = new Set(auth.Factors?.filter(f => allowed.has(f)))
  if (factors.size < 2) {
    throw httpError(400, 'Consent.FailsControlParameters',
      'Risk.DebtorIndicators.Authentication.Factors MUST contain at least two distinct categories from Knowledge, Possession, Inherence.')
  }

  // 3. AuthenticatedAt freshness (5-minute window)
  const authenticatedAt = Date.parse(auth.AuthenticatedAt)
  if (Number.isNaN(authenticatedAt)) {
    throw httpError(400, 'Consent.FailsControlParameters',
      'Risk.DebtorIndicators.Authentication.AuthenticatedAt is not a valid ISO 8601 timestamp.')
  }
  const ageMs = Date.now() - authenticatedAt
  if (ageMs < 0 || ageMs > 5 * 60 * 1000) {
    throw httpError(400, 'Consent.FailsControlParameters',
      'Delegated-SCA assertion is outside the 5-minute freshness window.')
  }

  // 4. AssertionId replay prevention
  const seen = await scaAssertionStore.hasSeen(consentId, auth.AssertionId)
  if (seen) {
    throw httpError(400, 'Consent.FailsControlParameters',
      'Delegated-SCA AssertionId has already been used under this consent.')
  }
  await scaAssertionStore.record(consentId, auth.AssertionId)
}

Your LFI MAY apply additional risk-based checks — e.g. correlating x-fapi-customer-ip-address with the customer's known device profile, or rejecting assertions from IPs outside permitted geographies. Failures of such checks MUST also be returned as 400 Consent.FailsControlParameters (the consent's control parameters include "the customer has performed SCA"), not as 403.

Matching the PII against the consent

Per POST /payments Requirements rule 2, Delegated SCA splits into two flows at payment time depending on whether the consent fixed a list of creditors or left beneficiaries open:

• Consent fixed a creditor list (1–10 entries) — the submitted creditor MUST exactly match one of the consent-time entries. Mismatch → 400 Consent.FailsControlParameters
• Consent left beneficiaries open — there is nothing to match against; the deferred creditor validation runs here instead. A failed check → 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). The fixed-list flow has two implementation patterns; the open-beneficiaries flow is a single path covered in the next subsection.

Pattern A — LFI persisted the decrypted creditor list at consent time

The most common pattern. At consent validation, after you decrypted and validated the consent-time PII, you persisted the creditor list keyed by consentId. At payment time you fetch it and search for an exact match against the payment-time creditor.

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

  // Open beneficiaries — no list to match against; validate fresh instead.
  if (stored.beneficiaryModel === 'open') {
    await validateOpenBeneficiaryCreditor(paymentPii.Initiation.Creditor)
    return
  }

  // Fixed list (1-10 entries) — the payment creditor must match exactly one.
  const matched = stored.creditorList.some(c =>
    isExactMatch(c, paymentPii.Initiation.Creditor)
  )
  if (!matched) {
    throw httpError(400, 'Consent.FailsControlParameters',
      'Payment creditor does not match any 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 matching logic: for a fixed list, some(isExactMatch, paymentCreditor) against Initiation.Creditor; for an open-beneficiary consent (the field is absent), fall through to the open-beneficiary validation below.

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

Validating an open-beneficiary creditor at payment time

When the consent omitted Initiation.Creditor, the creditor validation that would normally run at consent-validate time is deferred to POST/payments. The checks are the same four-part rule from consent validation — mandatory fields, BIC consistency, domestic rail reachability. The only differences are the error shape (HTTP 400 with errorCode: Consent.FailsControlParameters, rather than the invalid JSON body) and the fact that only a single creditor is being checked.

async function validateOpenBeneficiaryCreditor(
  creditor: CreditorEntry
): Promise<void> {
  if (creditor.CreditorAccount.SchemeName !== 'IBAN') {
    throw httpError(400, 'Consent.FailsControlParameters',
      'CreditorAccount.SchemeName MUST be "IBAN" for domestic payments.')
  }
  if (!isValidUaeIban(creditor.CreditorAccount.Identification)) {
    throw httpError(400, 'Consent.FailsControlParameters',
      'CreditorAccount.Identification is not a valid UAE IBAN.')
  }
  if (!creditor.CreditorAccount.Name?.en && !creditor.CreditorAccount.Name?.ar) {
    throw httpError(400, 'Consent.FailsControlParameters',
      'CreditorAccount.Name MUST include at least one of "en" or "ar".')
  }

  const derivedBic = deriveBicFromIban(creditor.CreditorAccount.Identification)
  if (creditor.CreditorAgent?.Identification && creditor.CreditorAgent.Identification !== derivedBic) {
    throw httpError(400, 'Consent.FailsControlParameters',
      'CreditorAgent.Identification does not match the BIC derived from the IBAN.')
  }

  const r = await lookupRailReachability(derivedBic)
  if (!r.reachableOnAani && !r.reachableOnUaefts) {
    throw httpError(400, 'Consent.FailsControlParameters',
      'Creditor bank is not reachable on AANI or UAEFTS.')
  }
  if (r.canDetermineAccountState && !r.accountCanReceive) {
    throw httpError(400, 'Consent.FailsControlParameters',
      'Creditor account cannot currently receive payments.')
  }
}

Duplicate-in-flight check

Per POST /payments Requirements rule 6, Delegated SCA payments are subject to a duplicate-in-flight check that on-demand consent types carry but one-off and scheduled payments do not. Before the payment record is created, your LFI MUST check whether another payment under the same consent, with the same creditor and the same instructed amount, is currently in Pending status. If so, reject the new request with 409 Payment.DuplicateInFlight.

This is distinct from x-idempotency-key handling: the idempotency key catches TPP retries of the same HTTP request, while this rule catches genuinely separate payment intents that happen to duplicate a still-in-flight one.

async function rejectIfDuplicateInFlight(
  consentId: string,
  paymentCreditor: any,
  amount: { Amount: string; Currency: string }
): Promise<void> {
  const inFlight = await paymentStore.findInFlight({
    consentId,
    status: 'Pending',
    creditorIban: paymentCreditor.CreditorAccount.Identification,
    amount: amount.Amount,
    currency: amount.Currency,
  })
  if (inFlight) {
    throw httpError(409, 'Payment.DuplicateInFlight',
      'A payment with the same creditor and amount is already in flight under this consent.')
  }
}

Once the prior payment has left Pending (reached AcceptedSettlementCompleted, AcceptedCreditSettlementCompleted, AcceptedWithoutPosting, or Rejected), a subsequent identical payment is permitted.

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": "125.50", "currency": "AED" }
    },
    "paymentPurposeCode": "GDDS",
    "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 / Error409 enums.

400 — Bad request

403 — Forbidden

409 — Conflict

500

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

Example error response

{
  "errorCode": "Consent.FailsControlParameters",
  "errorMessage": "Delegated-SCA assertion is outside the 5-minute freshness window."
}

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.