Canonical payment field reference
Audience: 🔌 Integration Client
The one JSON shape you send to POST /journal/payments (and POST /journal/payments/preview). BankConnector converts it to the bank's ISO 20022 dialect, so you build this once and target any bank.
Required below means structurally required: the structural gate rejects the request with 400 if it's missing. Some fields are optional in the schema but required by a specific bank's rules (a 422 at the bank level); those are called out as "bank-conditional." All text fields are ISO 20022 Max*Text; exceeding the ceiling is a 400.
Amounts are decimal strings (
"1500.00"), never numbers. This preserves exact minor units. See Core Concepts for the amount rules.
You never write ISO 20022 tags yourself. The
(PmtInf)/(CdtTrfTxInf)labels on the section headings below are there only if you want to cross-reference a bank's own MIG. You can ignore them entirely and just send 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? } | |
initiatingParty.name | required | ≤ 140 chars | |
initiatingParty.organisationId | optional | OrganisationId | |
payments | required | array, 1–1000 items |
payments[]: a payment block (PmtInf)
| Field | Required | Type / constraint | |
|---|---|---|---|
paymentId | required | ≤ 35 chars | |
paymentType | optional | e.g. "sepa", "international", "faster-payment"; omit (or "auto") to let the engine infer it (returned as autoSelected) | |
priority | optional | "normal" \ | "urgent" |
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 | |
categoryPurpose | optional | advanced: normally omit. ISO category-purpose code, ≤ 4 chars | |
executionDate | required | real YYYY-MM-DD calendar date | |
debtor | required | Party (who pays) | |
transactions | required | array, 1–10000 items |
transactions[]: one credit transfer (CdtTrfTxInf)
| Field | Required | Type / constraint |
|---|---|---|
endToEndId | required | ≤ 35 chars, unique within the block |
instructionId | optional | ≤ 35 chars |
amount | required | decimal string, always exactly 2 decimals, e.g. "1500.00" — for every currency |
currency | required | ISO-4217, 3 letters |
creditor | required | Party (who is paid) |
remittance | optional | { unstructured?, documents?, creditorReference?, additionalInfo? } |
purposeCode | optional | ≤ 10 chars; the purpose of payment (see below) |
regulatoryReporting | optional | RegulatoryReporting object |
splitPayment | conditional | Polish split payment / MPP; mandatory on the split payment type (see below) |
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). This is why the ceiling is 10, not 4.
splitPayment: Polish MPP (mandatory on the split type)
A Polish split payment without its VAT amount is rejected and fined by the bank, so all three sub-fields are required when the object is present:
| Field | Required | Type / constraint |
|---|---|---|
splitPayment.vatAmount | required | decimal string; must be ≤ the transaction amount |
splitPayment.taxId | required | creditor tax id, Polish NIP; ≤ 14 chars (longer ids are rejected) |
splitPayment.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.
Only reach for remittance.creditorReference when the creditor requires a specific structured reference: a Norwegian KID, a Swedish OCR, a Danish FIK, a Swiss QR reference, or the ISO 11649 cross-border reference (SCOR). It's { type, value }:
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) |
If you don't have one of these, you don't need this field; unstructured is fine.
Party
Used for both debtor and each creditor.
| Field | Required | Type / constraint |
|---|---|---|
name | required | ≤ 140 chars |
country | optional | ISO 3166-1 alpha-2; bank-conditional (e.g. CGI 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 |
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 CGI banks, e.g. Nordea, require it: BANK_DEBTOR_ACCOUNT_CURRENCY_REQUIRED) |
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 (HSBC IT/IE priority, AE, FR non-SEPA). Only this single element is supported; FR SEPA rejects a full agent address |
OrganisationId
| Field | Required | Type |
|---|---|---|
id | required | ≤ 35 chars |
scheme | optional | ≤ 35 chars |
issuer | optional | ≤ 35 chars |
See Validation for the full rule catalog and error codes, and Submitting Payments for the request/response envelope.