Canonical payment field reference

The JSON shape you send to POST /api/journal/payments (and POST /api/journal/payments/preview). BankConnector converts it to the bank's ISO 20022 dialect, so one shape serves every bank.

Unknown fields are dropped, not rejected. A field the schema does not list, at any depth, is removed before the payment is built and reported in unknownFieldsDropped with an UNKNOWN_FIELD_DROPPED warning. A misspelt optional field therefore does nothing: check that array after every submit.

Required means structurally required: the structural gate rejects the request with 422 if it's missing (400 on API version 2026-06-01, and with no version header). Some fields are optional in the schema but required by a specific bank's rules (a 422 at the bank level); those are marked "bank-conditional". All text fields are ISO 20022 Max*Text; exceeding the ceiling is a 422 under the same rule.

Fields marked "advanced" are rare: leave them out unless your bank told you to send them.

Amounts are decimal strings ("1500.00"), never numbers. This preserves exact minor units. See Core concepts for the amount rules.

The (PmtInf) / (CdtTrfTxInf) labels on the headings below are the ISO 20022 element names, for cross-referencing a bank's own specification. You send only the JSON fields.

Top level

Field	Required	Type / constraint
`schemaVersion`	optional	`"1.0"` \	`"1.1"` (defaults to `1.1`; unknown value rejected)
`messageId`	required	≤ 35 chars, your unique id for this instruction
`creationDateTime`	optional	ISO-8601 UTC (`...Z`); offsets are rejected
`initiatingParty`	required	object, `{ name, organisationId?, secondOrganisationId? }`
`initiatingParty.name`	required	≤ 140 chars
`initiatingParty.organisationId`	optional	OrganisationId; usually filled from your saved bank settings
`initiatingParty.secondOrganisationId`	optional	OrganisationId; a second identifier for the same customer, written after `organisationId` (some banks expect two)
`payments`	required	array, 1–1000 items

`payments[]`: a payment block (`PmtInf`)

Field	Required	Type / constraint
`paymentId`	required	≤ 35 chars; unique across the whole instruction
`paymentType`	optional	e.g. `"sepa"`, `"international"`, `"faster-payment"`; omit (or `"auto"`) to let the engine infer it (returned as `autoSelected`)
`priority`	optional	`"normal"` \	`"urgent"`; in Finland an urgent euro payment is sent as SEPA Instant, and a bank that cannot send one refuses it (the issue names the bank's rule)
`chargeBearer`	optional	who pays the bank fees; usually leave unset (the scheme default applies). Advanced: `DEBT`/`CRED`/`SHAR`/`SLEV` (`OUR`/`BEN`/`SHA` aliased)
`localInstrument`	optional	advanced: normally engine-derived; only set to override. ≤ 35 chars
`localInstrumentProprietary`	optional	advanced: the proprietary form of `localInstrument` (ISO `LclInstrm/Prtry` instead of `Cd`). ≤ 35 chars. Set at most one of the two
`categoryPurpose`	optional	advanced: normally omit. ISO category-purpose code, ≤ 4 chars
`executionDate`	required	real `YYYY-MM-DD` calendar date
`debtor`	required	Party (who pays)
`serviceUserNumber`	optional	advanced, UK Bacs only: your 6-digit Service User Number. Sent only where the bank's guide names a place for it; elsewhere the payment goes without it and the response says so
`ultimateDebtor`	optional	advanced: UltimateParty the payment is really made for, when it is not the account holder. Applies to every transaction unless one sets its own; leave it out when it is the debtor
`transactions`	required	array, 1–10000 items

`transactions[]`: one credit transfer (`CdtTrfTxInf`)

Field	Required	Type / constraint
`endToEndId`	required	≤ 35 chars, unique across the whole instruction
`instructionId`	optional	≤ 35 chars; unique across the whole instruction when set
`amount`	required	decimal string, exactly 2 decimals, more than zero, at most 15 integer digits, e.g. `"1500.00"`, for every currency. A third decimal is refused, never rounded (`"1234.567"` KWD). A zero-decimal currency such as JPY must end `.00`
`currency`	required	ISO-4217, 3 letters
`creditor`	required	Party (who is paid)
`remittance`	optional	Remittance
`purposeCode`	optional	≤ 10 chars; the purpose of payment (see below)
`regulatoryReporting`	optional	RegulatoryReporting
`splitPayment`	conditional	Polish split payment / MPP; mandatory on the `split` payment type (see below)
`ultimateDebtor`	optional	advanced: UltimateParty; overrides the payment-level `ultimateDebtor` for this transaction
`ultimateCreditor`	optional	advanced: UltimateParty the payment is ultimately for, when it is not the account credited
`instructionForDebtorAgent`	optional	advanced: free-text instruction to your own bank, ≤ 140 chars. Set only on an explicit bank instruction; the engine already derives it where a rail needs it
`instructionForCreditorAgent`	optional	advanced: free-text instruction to the creditor's bank, ≤ 140 chars, sent as written
`hmrcRtiReference`	optional	advanced, UK payroll only: the 3-character HMRC RTI code from your payroll software. Sent only where the bank's guide names a place for it; elsewhere the payment goes without it and the response says so
`resendOf`	optional	advanced: the refused payment this one re-issues. Not sent to the bank; once this payment is confirmed executed, the original refusal reads as resolved
`resendOf.messageId`	required if `resendOf`	the original submission's `messageId`, ≤ 35 chars
`resendOf.endToEndId`	required if `resendOf`	that line's `endToEndId`, ≤ 35 chars

`purposeCode`: one fact, many dialects

Supply the business purpose once; the engine emits it in the bank's language: ISO Purp/Cd for codes ≤ 4 chars, or a corridor-specific regulatory wrapper where the corridor demands one (e.g. PH accepts 10-digit codes; cross-border CNY is translated into its /BUSINESS/… form).

`splitPayment`: Polish MPP (mandatory on the `split` type)

A bank rejects a Polish split payment without its VAT amount (HSBC Poland also charges EUR 50 per occurrence), so all three sub-fields are required when the object is present:

Field	Required	Type / constraint
`vatAmount`	required	decimal string; must be ≤ the transaction `amount`
`taxId`	required	creditor tax id, Polish NIP; ≤ 14 chars (longer ids are rejected)
`invoiceRef`	required	invoice reference, ≤ 35 chars (`PRZEKAZANIE WLASNE` for own-VAT moves)

`remittance`: what the payment is for

For almost every payment, use remittance.unstructured: up to a few free-text lines (e.g. ["Invoice 2026-0042"]). That's the friendly default.

Field	Required	Type / constraint
`unstructured`	optional	array of strings, ≤ 140 chars per line; empty lines are dropped
`documents`	optional	array of invoices and credit notes, each emitted as a structured block (see below)
`creditorReference`	optional	`{ type?, value }` (see below)
`additionalInfo`	optional	array of strings, each ≤ 140 chars

Each documents item:

Field	Required	Type / constraint
`type`	required	`"invoice"` \	`"credit-note"`
`number`	optional	≤ 35 chars
`date`	optional	real `YYYY-MM-DD` calendar date
`amount`	optional	decimal string, same rules as the transaction `amount`

Only reach for remittance.creditorReference when the creditor requires a specific structured reference:

Field	Required	Type / constraint
`value`	required	the reference, ≤ 35 chars
`type`	optional	one of the values below

`type`	Use it for
`scor`	ISO 11649 "RF" structured creditor reference (generic)
`kid`	Norway
`ocr`	Sweden
`fik`	Denmark
`qrr`	Swiss QR-bill reference (required by a QR-IBAN)
`ogm`	Belgium, structured communication (OGM/VCS)
`viite`	Finland, creditor reference (viitenumero)
`kenmerk`	Netherlands, payment reference (betalingskenmerk)

If you don't have one of these, you don't need this field; unstructured is fine.

`regulatoryReporting`

Reporting to a central bank or tax authority on a cross-border payment. A payment out of Norway above NOK 100 000 owes details[0].code (a Valutaregister code), and one out of Sweden above SEK 150 000 owes a Skatteverket payment code. The payment is refused without it when it is in that currency, and warned about when it is in another. GET /api/banks/{bankKey}/payment-types publishes each rule with its code list. Some corridors need it too (cross-border CNY, the Philippines, Polish central-bank codes).

Field	Required	Type / constraint
`debitCreditReportingIndicator`	optional	`"CRED"` \	`"DEBT"` \	`"BOTH"`
`authority`	optional	`{ name?, country? }`
`authority.name`	optional	≤ 140 chars
`authority.country`	optional	ISO 3166-1 alpha-2
`details`	optional	array, up to 10 items
`details[].type`	optional	≤ 35 chars
`details[].country`	optional	ISO 3166-1 alpha-2
`details[].code`	optional	≤ 10 chars
`details[].amount`	optional	decimal string, same rules as the transaction `amount`
`details[].info`	optional	array of strings, each ≤ 35 chars

Party

Used for both debtor and each creditor.

Field	Required	Type / constraint
`name`	required	≤ 140 chars
`country`	optional	ISO 3166-1 alpha-2 (`UK` is accepted and sent as `GB`); bank-conditional (some banks require it on the debtor: `BANK_DEBTOR_COUNTRY_REQUIRED`)
`postalAddress`	optional	PostalAddress (all sub-fields optional)
`account`	required	Account
`agent`	optional	Agent
`organisationId`	optional	OrganisationId

UltimateParty

The party a payment is really made for or from, when that is not the account holder (for ultimateDebtor and ultimateCreditor). It has an identity only: no account or agent.

Field	Required	Type / constraint
`name`	required	≤ 140 chars
`country`	optional	ISO 3166-1 alpha-2
`postalAddress`	optional	PostalAddress
`organisationId`	optional	OrganisationId

PostalAddress

Field	Required	Type / constraint
`streetName`	optional	≤ 70 chars
`buildingNumber`	optional	≤ 16 chars
`postCode`	optional	≤ 16 chars
`townName`	optional	≤ 35 chars
`countrySubDivision`	optional	≤ 35 chars
`addressLines`	optional	array, up to 7 lines of ≤ 70 chars

Account

Exactly one of iban or other must be present, not both, not neither.

Field	Required	Type / constraint
`iban`	one-of	valid IBAN (format + mod-97 + length-registry checked)
`other`	one-of	`{ id, scheme }`, a national/BBAN account
`other.id`	required if `other`	≤ 34 chars
`other.scheme`	required if `other`	≤ 35 chars
`currency`	optional	ISO-4217; bank-conditional (some banks, e.g. Nordea, require it: `BANK_DEBTOR_ACCOUNT_CURRENCY_REQUIRED`)
`rollNumber`	optional	advanced, UK building-society payee only: ≤ 18 chars, needs `other`. Honoured only by a bank that declares the mapping (HSBC UK, Bacs); any other bank refuses the payment with `BANK_ROLL_NUMBER_NOT_SUPPORTED`

Agent

Optional on a party, but if you include a sub-object its ids are required.

Field	Required	Type / constraint
`bic`	optional	valid BIC (8 or 11); bank-conditional (some banks require the creditor BIC)
`clearing`	optional	`{ system, memberId }`
`clearing.system`	required if `clearing`	≤ 35 chars
`clearing.memberId`	required if `clearing`	≤ 35 chars
`name`	optional	≤ 140 chars
`country`	optional	ISO 3166-1 alpha-2, the agent's country. Bank-conditional: several rails require it. Only this single address element is supported

OrganisationId

Field	Required	Type
`id`	required	≤ 35 chars
`scheme`	optional	≤ 35 chars
`issuer`	optional	≤ 35 chars

Filled from your bank settings

When the company has saved bank settings and the payment leaves a field out, BankConnector fills executionDate (today plus the configured offset), chargeBearer, initiatingParty.organisationId, initiatingParty.secondOrganisationId and debtor.organisationId. Each one it filled is listed in the response's autoFilled. A value you send is never replaced.

See Validation for the full rule catalog and error codes, and Submitting payments for the request/response envelope.