Getting Started

API Access

Please get in touch with our representative for getting your API key for accessing the APIs. Create sandbox keys in the merchant portal after registration; live keys activate once KYB is approved.

All merchant APIs require the X-API-Key header. Share your server IP addresses with our team if IP allowlisting is enabled on your programme.

Rate Limiting

All the APIs have reasonable rate limitations. The same can be modified if the business need arises.

Collection Limits

Collections are settled in EUR or GBP via open banking (account-to-account pay-in).

Standard bank and scheme limits apply on a per-transaction basis. Minimum collection amounts and per-market caps depend on your programme — share your requirements with our representative.

How a Collection Works

1. 1 Supply payer details on create (customer_email, name fields) or reuse your own customer reference in reference.
2. 2 Call POST /api/v1/payments/merchant/requests with amount, currency, market, and your unique reference. You get back a payment_request_id plus checkout_url.
3. 3 Redirect the payer to checkout_url — hosted checkout with bank selection and SCA. There is no separate QR / UPI intent surface; always use the hosted link.
4. 4 Once the payer authorises the debit, we receive callbacks from the upstream rail. We emit a single open_banking.collection.updated webhook when funds are collected (not one POST per provider event). Use data.source: open_banking for account-to-account, APM for Bancontact / iDEAL / other Stripe methods (data.payment_method). If webhooks are not set up, poll GET /api/v1/payments/merchant/status with your order_id (same value as reference).
5. 5 Settled amounts are credited on platform settlement schedules (typically T+5). View balances and request payouts from the merchant portal.

Status Lifecycle

• +pending — collection created; payer has not completed checkout yet.
• +sent — payer authorised; bank settlement is in flight.
• +settled — funds received; wallet credited and webhook fired with final status.
• +failed — payment was attempted but did not succeed.
• +cancelled / expired — payer did not complete within the allowed window; treated as terminal.

Flow Diagram

Collection Flow

Webhooks

Register your webhook URL in Merchant → Webhooks.

The primary event for pay-ins is open_banking.collection.updated. Provider events (Stripe charge.updated, payment_intent.created, redirects, …) stay on StixBNK and are not forwarded. You receive one outbound webhook when funds are collected, and one on failure / cancellation / expiry. The same event covers open banking and APM: read data.source (open_banking vs APM). APM payloads also include data.payment_method (e.g. bancontact, ideal).

Verify X-Webhook-Signature: hex HMAC-SHA256 of the raw request body using your signing secret. Match the signature received with the generated signature to ensure the webhook came from StixBNK.

Respond with HTTP status code 200. If we do not receive a 200, we retry with exponential backoff (e.g. 1 min, 2 min, 4 min, 8 min, 16 min) up to 10 attempts.

Settlement & Balance

Every successful collection is credited on your merchant balance after provider settlement and platform hold rules.

View balances and settlement history in the merchant portal. Payouts to your bank account are initiated from the portal according to your programme schedule.