Split the payment schema into Domestic and International definitions
PAR and POST /payments carry both domestic and international payments through one shared schema, where international is only signalled implicitly. Split them at the top into a Domestic definition (today’s shape, minus the FX object) and an International definition that can be modelled to cross-border reality.
Cast your vote
Sign in with the Trust Framework to vote — For, Against, or Abstain — recorded in the open with your reasoning. Your organisation and name come from your directory profile, and each person may vote once.
One schema asked to be two
PAR (POST /par) and POST /payments were designed to carry both domestic and international payments through a single payment schema. Nothing at the top of the request says which one is being made. The distinction is signalled only indirectly: by whether the optional CurrencyRequest (FX) object is present, and by which shape — domestic or international — happens to sit inside the encrypted PersonalIdentifiableInformation blob, expressed as an anyOf rather than an explicit choice.
In practice the two have diverged sharply. Domestic payments have made real headway; international payments have not been delivered. Multiple LFIs have raised issues and asked for clarifications because the international fields have not mapped naturally to how a cross-border payment actually works — the international creditor shape is thin (a creditor account plus a single creditor agent), with none of the structure a SWIFT / ISO 20022 payment needs.
Because the international schema was not what it needed to be, LFIs have moved the fields they actually require out of the standard and into their own Open Finance international consent and authorization journeys. If the API is adopted as it stands, that leads to a varying customer experience across the ecosystem — the opposite of what a shared standard is meant to deliver.
The split is cheap to make now and expensive to defer. With little to no live international integration to migrate, separating the two definitions keeps the domestic schema free of international-only complexity and gives international its own home to be modelled properly.
Make the split explicit at the top
Replace the single shared payment schema with an explicit choice between a Domestic definition and an International definition, made at the top of both the PAR consent and POST /payments — in place of today’s implicit signalling through an anyOf PII and an optional CurrencyRequest.
The Domestic definition is today’s schema, unchanged, with one removal: the CurrencyRequest object goes. A domestic payment is always a same-currency (AED → AED) transfer, so FX never applies; the domestic creditor (IBAN-only, with Confirmation of Payee) stays exactly as it is.
The International definition gets its own schema. As a first step it carries today’s international PII plus the CurrencyRequest object — moved across and made a required, first-class part of the definition rather than an optional add-on. From there we realign its fields, field by field and with the LFIs, to cross-border SWIFT / ISO 20022 (pacs.008) practice. International is limited to two payment types: Single Instant Payment and Fixed Periodic Schedule.
What changes in the spec
One structural change — an explicit top-level split — and what each definition then looks like.
POST /payments)Introduce an explicit Domestic / International choice at the top of the consent and the payment-creation request, replacing the anyOf over the two PersonalIdentifiableInformation shapes and the “is CurrencyRequest present?” heuristic. The payment context is stated, not inferred.
Remove the CurrencyRequest object — FX never applies to a same-currency domestic transfer. Everything else (the IBAN-only domestic creditor, Confirmation of Payee, the full payment-type taxonomy, references, billing) is unchanged.
The old CurrencyRequest object is unpacked onto the request. Amount becomes an explicit choice: InstructedAmount (the external / target amount the creditor receives, in the currency of transfer) or EquivalentAmount (the internal / source amount debited in the debtor’s currency, plus the currency it converts into) — both reusing the domestic { Amount, Currency } shape. Purpose splits into an external PaymentPurposeCode (ISO 20022 ExternalPurpose1Code; the domestic Aani 3-letter list no longer applies) and a simple internal ProprietaryPurposeCode, alongside the free-text ExtendedPurpose. ExchangeRateInformation, ChargeBearer, InstructionPriority and DestinationCountryCode stay; EndToEndIdentification is added; and the exchange-house FxQuoteId is removed (FX quoting is the separate FX Service Initiation spec). Payment types are restricted to SingleInstantPayment and FixedPeriodicSchedule.
The encrypted creditor block is unchanged in this draft. The cross-border additions LFIs need — intermediary agents, ultimate creditor / debtor, regulatory reporting, and structured remittance information, on top of the structured creditor address the schema already carries — are recommended as the next step and called out in the asks below, rather than modelled here yet.
# ONE shared schema for domestic AND international.
# Which one it is gets signalled only IMPLICITLY:
POST /payments
{
"Data": {
"ConsentId": "pcon_8821",
"Instruction": { "Amount": { "Amount": "5000.00", "Currency": "AED" } },
"CurrencyRequest": { # optional — its PRESENCE means "international"
"ExtendedPurpose": "Family support",
"CurrencyOfTransfer": "GBP",
"DestinationCountryCode": "GB"
},
"PersonalIdentifiableInformation": "<JWE>", # anyOf[ Domestic | International ]
"PaymentPurposeCode": "GDDS",
"OpenFinanceBilling": { ... }
}
}
# Domestic vs international is decided by (a) whether CurrencyRequest is present and
# (b) which PII shape happens to sit inside the encrypted blob — never stated outright.# TWO definitions, chosen at the TOP of the request.
# == DOMESTIC == today's shape, CurrencyRequest removed
POST /payments # Domestic
{
"Data": {
"ConsentId": "pcon_8821",
"Instruction": { "Amount": { "Amount": "5000.00", "Currency": "AED" } },
"PersonalIdentifiableInformation": "<JWE: domestic creditor (IBAN) + CoP>",
"PaymentPurposeCode": "GDDS",
"OpenFinanceBilling": { ... }
}
}
# == INTERNATIONAL == banking cross-border (FX quoting is a separate spec)
POST /payments # International
{
"Data": {
"ConsentId": "pcon_9034",
"Instruction": { # external (instructed) XOR internal (equivalent)
"EquivalentAmount": { # debtor pays 5,000 AED, converted to GBP
"Amount": { "Amount": "5000.00", "Currency": "AED" },
"CurrencyOfTransfer": "GBP"
}
},
"ExchangeRateInformation": { "UnitCurrency": "AED", "RateType": "Indicative" },
"ChargeBearer": "Shared",
"DestinationCountryCode": "GB",
"PaymentPurposeCode": "GDDS", # external — ISO ExternalPurpose1Code, not Aani
"ProprietaryPurposeCode": "FAMILY-SUPPORT", # internal — bank/corridor code
"ExtendedPurpose": "Family support",
"EndToEndIdentification": "e2e-9034-jun26",
"PersonalIdentifiableInformation": "<JWE: international creditor + agent — unchanged>",
"OpenFinanceBilling": { ... }
}
}
# International payment types: SingleInstantPayment and FixedPeriodicSchedule only.The split, written out
Working drafts attached to this proposal — open each to read it in the same rendered view as the published API specs. Schemas the proposal changes are defined in full; schemas unchanged from the published spec are shown as stubs marked “unchanged”. The International draft restructures the cleartext request body (the instructed / equivalent amount choice, split purpose codes, EndToEndIdentification) while leaving today’s encrypted creditor block unchanged — the cross-border creditor fields are the next step.
What the split buys
- ✓Domestic vs international is read from the top of the request — not inferred from whether an optional object is present or from which shape happens to be inside the encrypted PII blob.
- ✓The common case gets simpler: domestic no longer carries the international-only CurrencyRequest (FX) object at all.
- ✓International gets its own schema that can be modelled to cross-border reality, so the fields LFIs need live in the standard instead of in bespoke per-LFI consent and authorization journeys.
- ✓One standard international schema means one consistent customer experience across the ecosystem, rather than each LFI diverging.
- ✓Validation becomes context-specific: the API Hub can require FX / currency-of-transfer only for international, and Confirmation of Payee only for domestic.
- ✓Restricting international to Single Instant Payment and Fixed Periodic Schedule matches what is realistically supported cross-border and shrinks what each LFI must build.
What the split costs
- ×It is a breaking change to the consent (PAR) and payment-creation request that every implementer must adopt.
- ×The detailed international field set still has to be designed — this proposal makes the split and moves CurrencyRequest across; the field-by-field cross-border modelling is a follow-up worked through with LFIs.