Build on StixBNK ⚡

StixBNK is a programmable platform for open banking routing and electronic invoicing. Route account-to-account pay-ins across providers, issue EN 16931 / Factur-X aligned invoices with hosted pay-by-bank links, and reconcile everything through one webhook schema — sandbox first, live after KYB.

What you can build

• + Open banking collections with a hosted checkout_url for every pay-in
• + Electronic invoices (EN 16931 / Factur-X) with PDF + payment link in one issue
• + Multi-provider routing by payer market — one API, normalised events
• + Invoice settlement on the same open banking rails as API checkout
• + Webhook-driven reconciliation for collections and invoice payments
• + Sandbox simulators before KYB — same contract for test and production

Start here

How integration usually goes

1. 1 Register, open the merchant portal, and create sandbox API keys.
2. 2 Read authentication and webhook guides — one schema for checkout and invoices.
3. 3 Create a test collection or invoice in sandbox; open the hosted checkout link.
4. 4 Register your webhook URL in Merchant → Webhooks and verify signatures.
5. 5 Complete KYB; switch to live keys when approved — same API contract.

Authentication

Merchant REST endpoints require an API key in the header:

X-API-Key: YOUR_API_KEY

Create keys in the merchant portal after registration. Use sandbox keys while KYB is in review; live keys activate routing on production open banking providers.

Webhooks

Configure outbound webhooks in Merchant → Webhooks. The primary event for pay-ins is:

open_banking.collection.updated

The same event is used for open banking (account-to-account) and APM (Bancontact, iDEAL, Przelewy24, …). Distinguish them with data.source.

Provider webhooks (Stripe payment_intent.*, charge.*, bank redirects, …) are ingested by StixBNK only. They are not forwarded to you. You receive one outbound POST when funds are collected (collection_status sent or settled), and one on failure / cancellation / expiry.

Verify X-Webhook-Signature — hex HMAC-SHA256 of the raw request body using your signing secret.

The payload includes your business reference, amount, currency, collection_status, and sandbox flag. Invoice settlements include invoice identifiers when linked.

Envelope ↓ · Open banking example ↓ · APM example ↓

{
  "id": "evt_6aa218f45f6e3",
  "type": "open_banking.collection.updated",
  "created": 1789008116,
  "livemode": false,
  "data": {
    "source": "open_banking",
    "actor_type": "merchant",
    "payment_request_id": "pay_abc123",
    "reference": "SANDBOX_1789006303316",
    "amount": 45,
    "currency": "EUR",
    "market": "FR",
    "collection_status": "sent",
    "transfer_status": "succeeded",
    "transaction_id": 138,
    "linked_merchant_id": null,
    "callback_error": null,
    "callback_error_reason": null,
    "transaction_status": "completed",
    "sandbox": true,
    "livemode": false,
    "purpose": "merchant_collection"
  }
}

{
  "id": "evt_6aa218f45f6e3",
  "type": "open_banking.collection.updated",
  "created": 1789008116,
  "livemode": false,
  "data": {
    "source": "APM",
    "payment_method": "bancontact",
    "actor_type": "merchant",
    "payment_request_id": "pi_3UDxvpGuok3qQCPy0wgxskzD",
    "reference": "SANDBOX_1789006303316",
    "amount": 45,
    "currency": "EUR",
    "market": "BE",
    "collection_status": "sent",
    "transfer_status": "succeeded",
    "transaction_id": 138,
    "linked_merchant_id": null,
    "callback_error": null,
    "callback_error_reason": null,
    "transaction_status": "completed",
    "sandbox": true,
    "livemode": false,
    "purpose": "merchant_collection"
  }
}

Sandbox & go-live

Use dedicated sandbox API paths for integration testing — no sandbox: true flag on live URLs.

• POST /api/v1/payments/merchant/sandbox/requests — create test collection
• GET /api/v1/payments/merchant/sandbox/status — poll test collection
• GET/POST /api/v1/invoices/sandbox — sandbox invoices
• GET/POST /api/v1/invoices/sandbox/item.php — single sandbox invoice

Live production providers use /api/v1/payments/merchant/requests (no sandbox flag) after KYB approval.

Hosted checkout is always returned as checkout_url. Redirect payers there; poll GET /api/v1/payments/merchant/status or rely on webhooks for final status.

Settlement and merchant payout run on platform T+5 schedules in fiat or USDC depending on your programme.

Electronic invoicing

The merchant portal and /api/v1/invoices support structured billing aligned with EN 16931 and Factur-X field sets — buyer identity, VAT category, line items, and document profile.

When you issue an invoice, StixBNK generates the human-readable document (HTML/PDF), optional Factur-X XML artefact, and a hosted pay-by-bank checkout_url on the same open banking routing layer as API collections.

• + Draft in the portal or POST /api/v1/invoices with issue: true
• + Email PDF + payment link; payer completes bank SCA on hosted checkout
• + Webhook marks invoice paid when the bank confirms — same event schema as checkout

Invoice API endpoints ↓