BAAS IBAN API Reference

Quickstart — Sandbox onboarding

Self-serve sandbox access in two steps. You'll get a whitelabel id and a sandbox API key (bk_sbx_…) instantly — on screen and by email. Sandbox is fully isolated — your test calls never touch live money.

1 · Sign up — get your sandbox API key

Open apikey-baas-sandbox.codegotech.com and submit your name, company and email. You instantly receive:

• Your whitelabel id
• Your API key in the form bk_sbx_… — shown only once, store it safely
• The base URL https://baas-sandbox.codegotech.com/api/v1 and a ready-to-paste curl snippet

2 · Create your first account holder, wallet & IBAN

Create an account holder, open a currency wallet for them, then issue an IBAN. (A USER_OWNED IBAN in the holder's name requires identity verification — use COLLECTION to receive without it, or run KYC first; see Start identity verification.)

That's a full account: holder → wallet → IBAN. Inspect everything you create from your whitelabel console at baas-whitelabel.codegotech.com (where you also set your customer prices, branding and webhook URL).

Integration flow

A complete integration follows these sequential steps. The endpoints in the left navigation are grouped accordingly. Identity verification is hosted by design: your end-user captures their ID and selfie on a Codego-hosted page — you never receive, store or forward identity documents, which keeps you out of the regulated data-processor scope. You receive only the final structured result via webhook.

Authentication

Every request is authenticated with your whitelabel API key in the X-Api-Key header. Keys look like bk_sbx_… (sandbox) or bk_live_… (production) and are issued at signup. Keep the key server-side — never expose it in client code.

Each key is scoped to one whitelabel tenant; all resources you create or read are isolated to it. Sandbox and live are fully separated. To rotate a key, use your whitelabel console or contact [email protected].

Environments — sandbox & live

Both environments share the same endpoint paths, request and response shapes — the same code works in both. Switch hosts, switch keys, and you're done. Webhooks are configured separately per environment.

Identity verification & webhooks

Hosted KYC/KYB. Start a verification session for an account holder with POST /users/{id}/kyc/sessions; you get back a one-time url. Redirect (or pop up) the holder to it — they capture their ID and a selfie on a Codego-hosted page; for a business the same flow collects company documents and beneficial owners. Documents never touch your servers. The outcome syncs back via the user.updated webhook, after which GET /users/{id} shows kycLevel: "verified" and you can issue a USER_OWNED IBAN and send payouts.

Webhooks — configuration & verification

Set your receiving URL in your whitelabel console at baas-whitelabel.codegotech.com → API & Webhooks. Every delivery is a POST with header Signature: sha256=HMAC_SHA256(rawBody, secret) and an Idempotency-Key header. Verify the signature against the raw body before trusting the event, and de-duplicate on the idempotency key.

// Verify a delivery (Node)
const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', WEBHOOK_SECRET)
  .update(rawBody)            // the raw request body, not re-serialised JSON
  .digest('hex');
if (req.headers['signature'] !== expected) return res.status(401).end();

Example user.updated payload (delivered to your configured webhook URL):

Map body.id → your record keyed by body.externalId, then continue: open a wallet, issue the IBAN, and start receiving and sending money. See Webhook events below for the full event list.

Errors

The API uses standard HTTP status codes. 2xx = success; 4xx = client error with a JSON { error, message } body; 5xx = transient — retry with backoff.