Canonical payment field reference

Audience: 🔌 Integration Client

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.

Required below 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 (400 on 2026-06-01 or with no version header).

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 for cross-referencing a bank's own MIG. You send only the JSON fields.

Top level

payments[]: a payment block (PmtInf)

Finland: urgent euro payments

At a Finnish bank, a euro payment marked priority: "urgent" is sent as SEPA Instant (paymentType becomes "sepa-instant"): it reaches the payee's bank within seconds, any day, and cannot be recalled once it is sent. It is never sent as a POPS express payment.

BankConnector sends SEPA Instant only through a Finnish bank whose own guide shows how it marks one: Danske Bank, OP, SEB, POP Pankki and Ålandsbanken. At any other Finnish bank a sepa-instant payment is refused with PAYMENT_TYPE_NOT_OFFERED, and an urgent euro payment with BANK_FI_URGENT_SEPA_INSTANT_UNAVAILABLE. Remove "urgent" to send it as a normal SEPA payment, or pay it from an account at a bank that offers SEPA Instant. At SEB, SEPA Instant payments go in an instruction of their own: one mixed with other payments is refused with BANK_SEPA_INSTANT_MIXED. An urgent salary is refused with BANK_FI_URGENT_SALARY_NOT_INSTANT: a salary is paid on its payment date and never goes instant. At Danske Bank, an urgent or sepa-instant payment whose categoryPurpose is SALA, INTC, SDVA or URGP is refused with BANK_DANSKE_SEPA_INSTANT_NOT_HONOURED: Danske sends those as ordinary SEPA payments, never as SEPA Instant.

OP rejects a SEPA Instant payment that carries invoice details, so at OP a SEPA Instant payment (an explicit "sepa-instant" or an urgent euro payment) with remittance.documents is refused with BANK_OP_SEPA_INSTANT_INVOICE_DOCUMENTS. Send it as a normal SEPA payment, or keep it instant and give the invoice's reference number (remittance.creditorReference) or a short message (remittance.unstructured) instead.

transactions[]: one credit transfer (CdtTrfTxInf)

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:

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 }:

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.

Account

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

Agent

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

OrganisationId

---

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