Getting Started

Audience: 🔌 Integration Client · 🏗️ Platform Operator

This page takes you from nothing to a converted payment in a sandbox.

Prerequisites

• A base URL for your BankConnector environment. For most customers this is your branded subdomain (https://<company>.bankconnector.com); for the shared sandbox it's https://sandbox.bankconnector.com.
• An API key for your platform (key_…). See Authentication for how one is issued.
• Your platformId and companyId.
• A bank key to target — e.g. abn-amro-nl, danske-dk, nordea-dk. Bank keys follow the pattern <bank-slug>-<country>. List what's available with GET /profiles.

Environments at a glance

BankConnector is multi-tenant SaaS: most customers connect to the vendor-run platform at bankconnector.com — your company gets a branded subdomain (https://<company>.bankconnector.com), and there's no infrastructure to run yourself. (The same software can also be deployed on-premises for enterprise customers who require it — ask your operator if that's your situation; everything in this guide applies the same way either way, just against a different host.)

Whichever host you're on, it runs in one of three postures:

Separately, each bank connection carries its own environment: test | production flag. Posture and connection-environment are independent — a production posture refuses to activate a production connection that points at a bank's test host, and vice-versa.

⚠️ A sandbox posture alone does not guarantee no real money can move. The hard boundary is your company's sandboxOnly flag — a sandboxOnly company can never deliver a production-environment payment, on any posture. A company that isn't sandboxOnly could, in principle, create a real production connection even on a sandbox-posture server. Confirm your company's sandboxOnly status with your operator; don't rely on the posture label alone. See Going Live for the full picture.

Do all your integration work against https://sandbox.bankconnector.com first.

Step 1 — Confirm you can reach the API

curl https://sandbox.bankconnector.com/health
# 200 {"status":"ok"}   (or {"status":"degraded","warnings":[...]} — still live)

/health is always 200 if the process is up. /ready returns 503 until the database is migrated and reachable — that one is for orchestration, not for you.

Step 2 — Discover what a bank supports

These endpoints are stateless and need no tenant scope — the public read-only sandbox key (prefilled in the API Reference "Try it" panel) can call them:

# All bank profiles
curl -H "X-API-Key: $BC_KEY" https://sandbox.bankconnector.com/profiles

# Payment types a specific bank offers
curl -H "X-API-Key: $BC_KEY" https://sandbox.bankconnector.com/banks/danske-dk/payment-types

Step 3 — Preview a conversion (no side effects)

Before you submit anything to the journal, you can validate + convert a canonical payment to XML with no state change and no delivery:

curl -X POST https://sandbox.bankconnector.com/journal/payments/preview \
  -H "X-API-Key: $BC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platformId": "<platformId>",
    "companyId":  "<companyId>",
    "bankKey":    "abn-amro-nl",
    "payment":    { ... see Core Concepts for the full object ... }
  }'
# 200 { ..., "xml": "<Document>...</Document>" }

A 200 here means the payment is structurally valid and converts cleanly. A 422 returns the exact validation issues in error.details.issues. This is the cheapest way to iterate on your payload.

There is also a stateless POST /convert/:bank that returns raw pain.001 XML directly, and POST /validate/:bank that returns just a validation outcome. Use preview when you want the journal's view (settings applied, delivery mode resolved); use convert/validate for pure engine checks.

Step 4 — Submit a payment

Once preview looks right, submit it for real. In sandbox this exercises the full pipeline — validation → conversion → approval planning → async delivery to the demo bank — without moving money:

curl -X POST https://sandbox.bankconnector.com/journal/payments \
  -H "X-API-Key: $BC_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2f9a1c7e-order-10432" \
  -d '{
    "platformId": "<platformId>",
    "companyId":  "<companyId>",
    "bankKey":    "abn-amro-nl",
    "payment":    { ... }
  }'
# 201 { "id": "...", "journalNo": "...", "status": "...", "xml": "...", "deliveryMode": "...", "approval": {...}, "delivery": {...} }

A 201 means accepted and converted — not sent. The bank send happens asynchronously, and the journal-document fields (id, journalNo, status, …) come back at the top level of the response alongside xml and deliveryMode — there's no "document" wrapper. Continue to Receiving Results to learn how to observe delivery.

In the sandbox, the demo bank responds after ~4 seconds, so you can watch a payment move through its lifecycle end to end.

Where to go next

• You'll need the shape of that payment object → Core Concepts
• You'll want to get idempotency right before you write any retry logic → Idempotency
• You'll need to react to results → Receiving Results