Getting started

Audience: 🔌 Integration Client, 🧑‍💼 Company Admin

This page takes you from nothing to an executed payment in a sandbox: provision, send, read. No signup needed.

The interactive playground provisions a sandbox in one click and animates the round-trip. This guide is the same flow in curl.

What you'll have after Step 1

POST /api/sandbox/provision creates an isolated sandbox for you: a company, an admin login, an API key, and an already-active demo bank connection. From there, two credentials matter (see Authentication for the full model):

• API key (X-API-Key: key_…), the machine credential for the data plane: submitting payments, reading results, webhooks. It is bound to your sandbox company: you pass that companyId.
• Admin session (open the dashboardLogin.setPasswordUrl link to choose a password, then log in with email and that password; the admin of your sandbox company). This is the control plane, for inviting users, issuing API keys and setting up bank connections. You don't need it for the payment loop below; see Managing companies & users.

Sandbox tenants are deleted after 30 days of inactivity. Provisioning a new one is a single unauthenticated call.

The setPasswordUrl link is single-use and expires after 7 days; the account has no other way to set a password (no reset email is sent). If you miss the window, provision a new sandbox.

Environments at a glance

Every host runs in one of two postures:

The public sandbox.bankconnector.com turns every bank into a simulated Demo Bank (default danske-dk), and real-payment sends are off engine-wide. Separately, each bank connection carries its own environment: test | production flag. A production posture refuses a production connection pointed at a bank's test host.

⚠️ On sandbox.bankconnector.com, real payments can never move. See Going live.

Step 1: Provision a sandbox

No auth, no body required:

curl -X POST https://sandbox.bankconnector.com/api/sandbox/provision

You get back a 201 with everything you need:

{
  "apiKey":     "key_…",               // data-plane credential (X-API-Key)
  "companyId":  "comp_…",              // the company to act as
  "baseUrl":    "https://sandbox.bankconnector.com",
  "bank":       { "key": "danske-dk", "name": "Danske Bank", "country": "DK" },
  "dashboardLogin": { "url": "…", "email": "…", "setPasswordUrl": "…" },
  "firstPayment":   { /* a copy-paste-ready first request */ }
}

Export the key so the snippets below can use it:

export BC_KEY="key_…"
export BC_COMPANY="comp_…"

The response's firstPayment object is a ready-to-send request for this bank. Want a different bank? Pass {"bankKey":"nordea-dk"} in the provision body (list them with GET /api/profiles).

Step 2: (Optional) Preview a conversion

Validate and convert a canonical payment to XML with no state change and no delivery:

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

A 200 means the payment is structurally valid and converts cleanly; a 422 returns the exact issues in error.details.issues. Use it to iterate on your payload.

Step 3: Submit a payment

In sandbox this runs the full pipeline (validation, conversion, approval planning, asynchronous delivery to the demo bank) without sending a real payment:

curl -X POST https://sandbox.bankconnector.com/api/journal/payments \
  -H "X-API-Key: $BC_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2f9a1c7e-order-10432" \
  -d '{
    "companyId":   "'"$BC_COMPANY"'",
    "bankKey":     "danske-dk",
    "environment": "test",
    "payment":     { ... }
  }'
# 201 { "id": "...", "journalNo": "...", "status": "...", "xml": "...", "deliveryMode": "..." }

A 201 means accepted and converted, not yet sent to the bank. The status field tells you what happened next: queued-for-delivery when the payment was released straight to delivery (the sandbox's auto-release default), or pending-approval when an approval policy holds it for a User approver. The journal-document fields (id, journalNo, status, …) come back at the top level alongside xml and deliveryMode.

Step 4: Read the result

The demo bank replies within a few seconds with a real-format pain.002 and camt.053. Read the reconciled state:

curl -H "X-API-Key: $BC_KEY" \
  "https://sandbox.bankconnector.com/api/journal/reconciliation?companyId=$BC_COMPANY"
# status "executed", state "cleared"

GET /api/journal/list?companyId=$BC_COMPANY gives the same as a paged list. See Receiving results for webhooks + polling in depth.

Where to go next

• The shape of that payment object → Core concepts
• Get idempotency right before any retry logic → Idempotency
• React to results → Receiving results
• Managing many companies or users: Managing companies & users