Core Concepts

Audience: 🔌 Integration Client · 🏗️ Platform Operator

Five ideas explain almost everything about integrating with BankConnector.

1. The tenancy model

Platform → Company → (bank connections, accounts, payments, webhooks)

• A platform is the operating tenant (BankConnector the vendor, for most customers — see below). 🏗️
• A company is who actually pays and gets paid. Every payment, account, connection, and webhook belongs to a company.
• Scope = platform + companyId. Your API key implies the platform, so you never pass platformId on a data-plane call — you pass only companyId (in the body for POSTs, as a query param for GETs). Missing it → 400 scope_required.

As an integration client you operate as one company at a time. Your API key fixes the platform; you name the company in each call. (The platformId still exists — you'll see it on control-plane routes like creating companies — but data-plane payment calls don't take it.)

2. You send canonical JSON, not XML

You never author ISO 20022 XML. You send a canonical payment instruction — a clean, bank-agnostic JSON object — and BankConnector's engine:

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

The same canonical object works across banks; the engine handles the per-bank dialect.

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).

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

These are the ones worth reading twice. The full catalog is in Validation Reference.

• amount is a STRING, not a number: "1250.00". Format ^\d{1,15}\.\d{2,3}$ (2–3 decimal places). Precision must match the currency's ISO 4217 minor unit — JPY and ISK take 0 decimals ("1000.50" is rejected), most currencies 2, KWD/BHD 3. "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. 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 deduplication handle — the bank de-duplicates on it within roughly a 90-day window, and BankConnector uses it as a fallback idempotency key. Make it stable and unique per logical payment. See Idempotency.
• name fields allow up to 140 characters, but SEPA banks process 70. Text is transliterated to the SEPA character set then truncated — and transliteration can lengthen text (ß→ss). 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 /journal/payments does validation, conversion, and approval-planning synchronously and returns 201 with the converted document and its XML. But the send to the bank is always asynchronous, via a transactional outbox and a delivery worker. The bank's acknowledgement (pain.002) arrives later still.

So a 201 tells you the payment is well-formed and accepted. It does not tell you the bank received or executed it. You observe that through the payment lifecycle, via webhooks or polling.

The payment lifecycle

converted ─┬─▶ pending-approval ─▶ queued-for-delivery ─▶ sending ─▶ sent
           │                                                          │
           └──────────────────────────▶ queued-for-delivery          ▼
                                                              validated / executed
    (any stage) ─▶ sanctions-hold                             partially-accepted
                ─▶ delivery-failed                            rejected
                                                              cancelled

• Terminal statuses are executed, rejected, cancelled — sticky. A late or replayed bank message cannot flip them back.
• sanctions-hold means screening paused the payment for review — this is visible via polling and the audit log, but is not one of the fanned-out webhook events (see Receiving Results).
• An ambiguous send stays in sending and is not auto-retried (it's the money path); it surfaces as an SLA breach for a human to resolve.

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 /journal/list is the designated "ERP poll," with an unretrievedOnly flag so you can drain only what you haven't seen. Best for simplicity and for batch/back-office systems.

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

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. This convention is enforced at startup.

BankConnector's bank registry covers hundreds of banks across dozens of countries and grows continuously — the authoritative, current list is always GET /profiles, not a number written down here.

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