Version Changelog

Every consent gains an append-only attestations sub-resource. Once a consent reaches a terminal status — Revoked, Expired, or Consumed — the TPP reviews the data it holds under that consent and POSTs an Attestation Event confirming what it did with it. Rejected consents are out of scope: no data was ever shared under them.

The sub-resource is added to all three consent types, each scoped to its own API family:

POST /account-access-consents/{ConsentId}/attestations (scope accounts), POST /payment-consents/{ConsentId}/attestations (scope payments), and POST /insurance-consents/{ConsentId}/attestations (scope insurance).

A payment consent is not empty for this purpose — it carries debtor and creditor details, amounts, references, and any account data the TPP retrieved to set the payment up, so it falls under the same obligation as a data sharing consent.

The event body carries an envelope — AttestationType (today only DataRetentionDeletion), AttestationStatusAppliedDateTime, DataAccessCeasedDateTime, and ConsentRevocationDateTime where the customer revoked at the TPP — plus a DataActions array with one entry per category of data held. Each entry declares whether that category was Deleted, Retained, Anonymised, or ArchivedRestricted; anything kept also requires a retention reason, a retained-until date, and an access restriction.

The event must reach the API Hub within 45 days of the consent becoming terminal. The API Hub returns 201 with a receipt — AttestationId, AttestationReceivedDateTime, and RegulatoryDeadlineMetIndicator, which reports whether that deadline was met. A late event is still recorded, not rejected. A failed technical or rule validation returns 400 with code Attestation.ValidationError.

The sub-resource is append-only and stateless. Each POST records a new immutable event, the API Hub applies no de-duplication, and there is no correction endpoint — a restatement is simply another event. AttestationType is the extension point: a future obligation to attest to something else against a consent becomes a new type rather than a new API.

The full specification — field tables, enum values, validation rules, and worked examples — is on the Data Deletion Confirmation page linked below.

GET /psu/{userId}/consents filters an end user's consents by status. In v2.1 the status parameter is a single untyped string, so an LFI building a Consent Management Interface that shows, say, every consent still in use has to issue one request per status and merge the results itself.

In v2.2 the parameter becomes a comma-separated list — ?status=Authorized,Suspended — evaluated as a union: a consent is returned if its status matches any value in the list. A single value behaves exactly as it does in v2.1, and omitting the parameter still returns consents of every status. Order is not significant and duplicates are ignored.

The parameter is also now typed. In v2.1 its schema is a bare string with no enum, so the specification places no constraint on what may be sent and an unrecognised value simply returns an empty array. In v2.2 each list item MUST be a member of AEConsentStatus — AwaitingAuthorization, Authorized, Rejected, Revoked, Expired, Consumed, or Suspended — and a request carrying any other value is rejected with 400. Values are case-sensitive.

The change is scoped to this one operation. The three sibling list endpoints — GET /consents, GET /consent-groups/{consentGroupId}/consents, and GET /accounts/{accountId}/consents — share the v2.1 status parameter component and are unchanged in v2.2; they continue to accept a single untyped value.

The comma-separated form follows the convention already used for multi-valued query parameters elsewhere in the standards, such as accountIds and insurancePolicyIds on the Ozone Connect endpoints, so it needs no new parsing on the LFI side. In OpenAPI terms the parameter becomes an array with style: form and explode: false.

The Consent Manager OpenAPI document is published from the api-specs repository, which has no v2.2 release yet, so this change is shown as a draft specification: the endpoint page below renders the published v2.1 document with this parameter applied to it. Everything else in that document is unchanged from v2.1.

The payment log records what the API Hub knows about a payment, but not how it was settled. paymentResponse.paymentTransactionId already depends on the rail to be interpreted — its v2.1 description singles out AANI-generated identifiers in prose — while nothing in the record states which rail produced it.

v2.2 adds paymentResponse.paymentRail, a closed enum of AANI (the UAE instant payment platform), FTS (UAEFTS, the CBUAE funds transfer system), and LFI (settled internally, both accounts held at the same LFI, so the payment never reached an external rail). The LFI sets it on the existing PATCH /payment-log/{id} call, and it is returned on GET /payment-log.

The value records how the payment was executed rather than how it was requested: where an LFI's routing rules settle an instant payment on another rail, the field reports the rail actually used. A payment settles over exactly one rail — this holds for file payments as well as single payments, so one value describes the whole record.

The LFI MUST populate the field when patching the status to a terminal success — AcceptedWithoutPosting, AcceptedSettlementCompleted, or AcceptedCreditSettlementCompleted. It MAY be sent alongside Pending, and MAY be omitted on Rejected, where the payment may have been rejected before any rail was selected.

The three values are the namespaces already used by paymentResponse.rejectReasonCode, whose v2.1 pattern is ^(AANI|FTS|LFI)\.[A-Za-z0-9]+$. The two fields MUST therefore agree: an AANI.* reject code is accompanied by AANI, and an FTS.* code by FTS. An LFI.* reject code means the payment was rejected at the LFI before rail submission, and carries no such constraint.

Because the field is required on a terminal-success patch, an LFI built against v2.1 that patches a completed payment without it is rejected under v2.2. This is the one change in v2.2 that requires action from every LFI, and the API Hub enforcement date is set separately from the version cutover.

The Consent Manager OpenAPI document is published from the api-specs repository, which has no v2.2 release yet, so this change is shown as a draft specification: the endpoint pages below render the published v2.1 document with this field applied to it. Everything else in that document is unchanged from v2.1.

In v2.1 GET /payment-log returns every payment made under a consent in one response. The record it returns is not small — each one embeds the full payment request, its detached signature, the request headers, and the full payment response — so a long-lived consent that has executed hundreds of payments produces a response measured in megabytes, on an endpoint a Consent Management Interface calls to draw a customer-facing payment history.

v2.2 paginates the operation, using exactly the model already in place elsewhere in this API. It gains the shared page and pageSize query parameters — page is 1-indexed and defaults to 1, pageSize defaults to 25 — and the response meta object, which in v2.1 is empty and closed to additional properties, is replaced by the same paginationMetadata schema those endpoints return: pageNumber, pageSize, totalPages, and totalRecords.

Nothing here is bespoke. The four consent list operations on this API — GET /consents, GET /consent-groups/{consentGroupId}/consents, GET /psu/{userId}/consents, and GET /accounts/{accountId}/consents — are the only other paginated endpoints the API Hub provides to LFIs, and they take the same two parameter components and return the same metadata schema. /payment-log was the one list operation in the API that had been left unpaginated; it now behaves like the endpoints beside it, so an LFI already calling those has nothing new to learn.

totalRecords counts every payment under the consent and totalPages is ceil(totalRecords / pageSize), so a caller reads totalPages to know when to stop rather than treating a short page as the last one.

This is a behaviour change that requires action. An LFI built against v2.1 that calls this endpoint and renders what it receives will, from v2.2, silently show only the first page of payments on any consent that has more — with no error to signal the truncation. Any caller that needs the full set MUST iterate page until pageNumber reaches totalPages. This is the reason to check the endpoint even where the rest of v2.2 needs no work.

The Consent Manager OpenAPI document is published from the api-specs repository, which has no v2.2 release yet, so this change is shown as a draft specification: the endpoint page below renders the published v2.1 document with pagination applied to it. Everything else in that document is unchanged from v2.1.

A transaction the customer cannot recognise is of limited use to them. In v2.1 the narrative that identifies an entry — TransactionInformation on the TPP-facing schema, transactionInformation on Ozone Connect — is an optional field on both, so a conformant LFI may return a transaction carrying nothing but an amount, a date, and a type. TPPs then either display an entry the customer cannot place, or build their own guesswork from the fields that are present.

In v2.2 the field is technically required: it is added to the required list of AETransaction in the Account Information specification and of CbuaeTransaction in the Ozone Connect Bank Data Sharing specification. A transaction record that omits it no longer validates on either surface.

The requirement applies to both surfaces because the API Hub can only return a narrative the LFI supplied. Requiring it TPP-side alone would leave the Hub with nothing to serialise on a record the LFI is still permitted to send without one.

Being present is not on its own sufficient. The value MUST be a human-readable description by which the customer can recognise the entry. Where the LFI's core banking system holds no stored narrative for a transaction, the LFI MUST derive one from the data it does hold — the merchant name, the counterparty, or the transaction type. Whitespace-only values and non-informative placeholders such as N/A, -, or Unknown do not satisfy the requirement, and an empty string is rejected by the schema in any case.

The Ozone Connect field is also bounded to match: it gains minLength: 1 and maxLength: 500, the constraints the TPP-facing schema has carried since v2.1. Without them an LFI could return a 600-character narrative that passes its own contract and then fails the Hub's — a failure invisible in the document the LFI builds against.

This is a change every LFI must act on. An LFI built against v2.1 that returns transactions without a narrative — or without one for a subset of transaction types, which is the more common case — will have those responses rejected under v2.2. TPPs need take no action, but may stop handling the field as absent once their LFIs are on v2.2.

Neither specification has a v2.2 release in the api-specs repository yet, so this change is shown as a draft specification: the endpoint pages below render the published v2.1 documents with the requirement applied to them. Everything else in those documents is unchanged from v2.1.

Confirmation of Payee asks one question: does this name belong to this IBAN? In v2.1 the LFI answers it through a four-level structure borrowed from OpenID Connect for Identity Assurance — data[] → verifiedClaims[] → verification{…} → claims{…} — of which only the innermost name is used.

In v2.2 the two middle levels are removed. Each entry in data carries name directly, which is either a CbuaeCopPersonName (fullName required) or a CbuaeCopBusinessName (businessName required). The person and business branches are retained, mirroring the PersonName / BusinessName split the request already uses.

The verification subtree goes with it. Trust framework, assurance level, assurance process, evidence references and evidence metadata are no longer part of this operation — every LFI builds that structure today and the API Hub does not read it.

So does the wider customer data. The v2.1 ConfirmationOfPayeePersonClaims schema carries 23 fields, among them salary, employerName, maritalStatus, residentialAddress, emiratesId, birthDate and nationality. None of it is needed to compare two names, and Confirmation of Payee runs **without a consent** — so the response is reduced to the name data the question requires. The optional number field is dropped for the same reason. id is retained: it is pseudonymous by definition and is the only handle for investigating a disputed result.

Structured name fields are retained as **optional** members, so that the Hub's matching algorithm can be improved without a second breaking change to this contract. A person name may carry firstName, middleName, lastName, fullNameAr (the name in Arabic script) and alsoKnownAs; a business name may carry businessNameAr and alsoKnownAs. Only fullName and businessName are matched today, and a response carrying nothing but fullName is fully conformant.

The response also settles a naming inconsistency. The same three values carried three different names across v2.1: the Ozone Connect request used fullName/firstName/lastName, the Ozone Connect response used fullName/givenName/familyName, and the TPP-facing surface uses FullName/GivenName/LastName. v2.2 settles the Ozone Connect contract on the request vocabulary, so the same value carries the same name in both directions of one operation. givenName and familyName were in any case already documented as withdrawn — the v2.1 schema records that implementing them was "removed as of v1.2.1".

Three semantics that were previously implicit are now stated in the specification rather than only in the guide. The LFI performs no matching: it MUST NOT compare the submitted name to its own records, and MUST NOT filter, rank or omit holders by how well they match — the API Hub owns the rules. A joint account MUST return one entry per holder, and the API Hub evaluates every entry in data rather than stopping at the first. Not found is 200 with an empty data array, never 204, 404, 201 or 202; account-not-found, account-barred and customer-opted-out are deliberately indistinguishable so a CoP query cannot be used to probe for the existence of an account.

This is a breaking change to the response and requires action from every LFI. It is confined to the response body of this one operation — the request, headers, query parameters, status codes and error codes are unchanged, so the work is a rewrite of the response builder rather than a new integration. The TPP-facing /confirmation and /discovery endpoints do not move: the API Hub already normalises between the two surfaces.

One known limitation is unchanged. Claim-block selection still follows the TPP's request type rather than the data the LFI holds, so submitting a business name against an account held as a personal name is answered as a protocol error rather than as a no-match. Flattening the envelope does not address this, and it is left for a separate change.

The Ozone Connect Bank Data Sharing specification has no v2.2 release in the api-specs repository yet, so this change is shown as a draft specification: the endpoint page below renders the published v2.1 document with the reshaped CoP schemas applied to it. Everything else in that document is unchanged from v2.1.