Core concepts

Audience: 🔌 Integration Client, 🧑‍💼 Company Admin

Five ideas cover integrating with BankConnector.

1. The tenancy model

Company → (bank connections, accounts, payments, webhooks, users, API keys)

A company is the tenant: the organisation that holds the bank agreement and pays and gets paid. Every payment, account, connection and webhook belongs to a company, and companies are isolated from each other.
Your API key is bound to one company. You pass that companyId (in the body for POSTs, as a query param for GETs); missing it → 400 scope_required, and any other company's id → 403 forbidden.

A company comes into being when its own people sign up; see Managing companies.

2. You send canonical JSON, not XML

You never write ISO 20022 XML. You send a canonical payment instruction (a bank-agnostic JSON object) and BankConnector:

validates it (structure, then generic rules, then bank rules, then payment-type rules),
applies your saved bank settings (charge bearer, execution-date offset, etc.),
converts it to the correct pain.001 flavour for the target bank,
queues it for asynchronous delivery.

3. The canonical payment instruction

One instruction contains one or more payments (each becomes a PmtInf), and each payment contains one or more transactions (each becomes a CdtTrfTxInf). The tree below is the shape; the Payment field reference is the full required-vs-optional table for every field.

PaymentInstruction
├── messageId                 (required, ≤35 chars, your dedup handle)
├── initiatingParty { name, organisationId? }
└── payments[]  (1..1000)
    ├── paymentId              (required, ≤35)
    ├── paymentType            ("sepa", "domestic", "international", ...)
    ├── executionDate          (required, "YYYY-MM-DD", a real calendar date)
    ├── debtor  { name, country?, account, agent? }
    └── transactions[]  (1..10000)
        ├── endToEndId         (required, ≤35)
        ├── amount             (required, STRING, see below)
        ├── currency           (required, ISO 4217)
        ├── creditor { name, account, agent? }
        └── remittance?        (structured or unstructured)

A complete, valid example

{
  "messageId": "ORDER-2026-10432",
  "initiatingParty": {
    "name": "Acme Holding",
    "organisationId": { "id": "NL-1", "scheme": "CUST" }
  },
  "payments": [
    {
      "paymentId": "p1",
      "paymentType": "sepa",
      "executionDate": "2026-07-15",
      "debtor": {
        "name": "Acme Holding",
        "country": "NL",
        "account": { "iban": "NL91ABNA0417164300", "currency": "EUR" },
        "agent": { "bic": "ABNANL2A" }
      },
      "transactions": [
        {
          "endToEndId": "e1",
          "amount": "1250.00",
          "currency": "EUR",
          "creditor": {
            "name": "Supplier BV",
            "account": { "iban": "FR1420041010050500013M02606" },
            "agent": { "bic": "BNPAFRPP" }
          },
          "remittance": {
            "creditorReference": { "type": "scor", "value": "RF18539007547034" }
          }
        }
      ]
    }
  ]
}

Field rules that trip people up

The full catalog is in Validation reference.

amount is a string, not a number: "1250.00". Format ^\d{1,15}\.\d{2}$ (exactly two decimal places). You do not tailor decimals per currency: send the ordinary two-decimal form for everything and the engine emits each currency's correct ISO 20022 precision (JPY "1000.00" → 1000). Trailing zeros are always fine. The one thing we reject is an amount the currency cannot represent: a non-zero sub-unit, e.g. "1000.50" JPY (there is no half-yen). We refuse rather than silently truncate it, because truncating would change the amount you're paying. "0.00" parses but fails the positive-amount rule.
creationDateTime, if you send it, must be UTC with a Z. Offsets like +02:00 are rejected. Omit it and the server stamps "now."
executionDate is warn-only for the past, weekends, and holidays: it is never silently shifted, but those don't block. Two exceptions are refused, because the bank rejects the file outright: a non-banking day at a BEC bank, and a Finnish salary on a weekend or Finnish bank holiday. Both errors name the banking day to use. An impossible date (2026-02-30) is a hard schema error.
account is exactly one of iban XOR other. Providing both, or neither, is a validation error. IBANs are checked three ways: format, mod-97 checksum, and exact per-country length.
messageId is required and is your payment's identity: the bank de-duplicates on it within roughly a 90-day window, and on host-to-host BankConnector treats one messageId as one payment, whatever Idempotency-Key you send. Make it stable and unique per logical payment, and reuse it only to retry that same payment. See Idempotency.
name fields allow up to 140 characters, but SEPA banks process 70. Text is transliterated to the bank's character set for the rail then truncated, and transliteration can lengthen text (ß→ss). A German SEPA file keeps umlauts, ß and & as you wrote them. A name in a script with no Latin mapping is a hard error, not a silent blank.

4. Payments are accepted synchronously, delivered asynchronously

POST /api/journal/payments validates, converts and plans approval synchronously and returns 201 with the converted document and its XML. The send to the bank is always asynchronous. The bank's acknowledgement (pain.002) arrives later still.

A 201 tells you the payment is well-formed and accepted, not that the bank received or executed it. Follow the payment lifecycle through webhooks or polling.

The payment lifecycle

POST /api/journal/payments
   │  (validated → converted to pain.001 → recorded)
   ▼
pending-approval ──▶ queued-for-delivery ──▶ sending ──▶ sent ──▶ validated / executed
   │  no approval needed: released straight through        │       partially-accepted
   │  approval needed: held here until fully approved      │       rejected
   │                                                       ▼       cancelled
   ├───────────────────────────────────────────▶ (any stage) ──▶ delivery-failed
   │
   └──▶ rejected-by-approver   (an approver vetoed it; final, never sent)

A payment the bank holds for your own signers after checking the payee takes one more step between sending it and the bank's verdict:

sending / sent ──▶ awaiting-signer-release ──▶ validated / executed / rejected / cancelled …

A payment is recorded at pending-approval. Every payment is governed by an approval policy, and that policy decides whether this payment needs approving. If it does not, the payment moves straight to queued-for-delivery; if it does, it waits at pending-approval until approved. The built-in default policy requires approval on every payment; on the sandbox approvals are skipped. See Submitting payments. (payment.converted is a webhook event, not a status.)
Terminal statuses are executed, rejected, cancelled and rejected-by-approver, and sticky. A late or replayed bank message cannot flip them back.
rejected and rejected-by-approver are different outcomes. rejected is the bank's verdict on a file it received. rejected-by-approver means one of your own approvers vetoed the payment before it was sent: it never reached the bank and never will. To pay it anyway, submit a new payment with a new messageId.
awaiting-signer-release means the bank has the file and is waiting on your own signers. Under EU payee verification a German or Austrian bank can check the payee's name, discard the signatures that came with the file, and hold it in its EBICS distributed-signature folder until your signers release or cancel it there. It is not final, and it is never re-sent: the bank's own status report moves it on, as it does for sent. The payment.awaiting-signer-release event fires when a payment enters it.
If a send is ambiguous (the connection dropped and we can't be sure the bank received the file), the payment stays in sending and is not auto-retried, because a blind retry risks paying the beneficiary twice. A user confirms with the bank and resolves it.

5. You learn results by webhooks or polling

Two supported patterns, covered in Receiving results:

Webhooks: BankConnector POSTs signed events to your endpoint as things happen. Best for timeliness.
Polling: GET /api/journal/list is the designated "ERP poll," with an uncollectedOnly flag so you can drain only what you haven't seen. Best for simplicity and for batch/back-office systems.

Most production integrations use webhooks for latency and a periodic poll as a safety net.

Pagination

Every list endpoint returns the same envelope:

{ "items": [ ... ], "nextCursor": "…", "total": 123 }

Pass ?limit= to page; nextCursor (non-null ⇒ more rows) is echoed back, and you pass it as ?cursor= on the next request to walk the rest. When nextCursor is null, you've reached the end.
A malformed cursor returns 400 invalid_cursor.
Defaults & caps vary by endpoint: /journal/list default 500, cap 1000; /journal/documents default 50, cap 200; /journal/events cap 5000; /journal/reconciliation default 500, cap 1000.

An ERP draining a backlog larger than the default must follow nextCursor rather than assume one response holds everything; total tells you if there's more.

Bank keys

A bankKey is <bank>-<country-code>: the country code is part of the key so the same bank in different countries resolves to its own profile (e.g. jpmorgan-us, and other JPMorgan country flavours), each with its own BIC, pain version, payment types, and rules.

GET /api/profiles lists every supported bank.

Backward-compatible aliases. A few keys were historically bare (no country suffix); they still resolve to their canonical form, so existing integrations keep working:

Legacy key	Canonical key
`jpmorgan`	`jpmorgan-us`
`danske-bank`	`danske-dk`
`deutsche-bank`	`deutsche-bank-de`