KvarnPay — Merchant integration guide ​

Everything you need to put the KvarnPay widget in your product: one endpoint on your backend, one iframe on your page.

What KvarnPay is ​

KvarnPay is an embeddable crypto on-ramp built by Kvarn Capital Ltd. You drop our widget into your app; your customer picks an amount, verifies their identity, and pays by card — all inside the frame, without leaving your product. We then credit the equivalent crypto to your account in Kvarn's ledger, attributed to the customer who paid it in.

The paying customer is Kvarn's customer: we run the identity check (KYC), we hold the customer record, and we own the payment relationship. You receive the crypto. No crypto moves on-chain per payment — balances accumulate in the ledger and are paid out to you separately.

How the integration works ​

Four moving parts, and only two of them are yours. You never call our API directly: your backend signs a token, your page hands that token to our widget, and the widget does the rest.

  1. Your backend signs a short-lived token asserting who your customer is — your own reference for them, and optionally your own fee on this payment (when Kvarn has enabled that for your account). It is signed with the secret Kvarn gave you.
  2. Your page embeds our widget in an iframe, with that token in the URL fragment — the part of a URL after #, which browsers keep local and never send to any server.
  3. The widget exchanges the token with our API for a KvarnPay session. Your servers never talk to ours; the only thing you produce is the token.
  4. The customer completes the flow inside the widget — amount, identity check, card payment — and we credit the crypto to your ledger account.
How the token travels Your backend signs a ten-minute token and hands it to your page. Your page loads the KvarnPay widget in an iframe with the token in the URL fragment. The widget exchanges the token with the KvarnPay API for a session token. The customer then completes the amount, identity check and card payment inside the widget. Your backend your server — the only place the secret lives 1. a signed token, good for10 minutes, naming your customer Your page where your customer already is 2. iframe src — the token ridesin the URL fragment KvarnPay widget an iframe on your page 3. exchanges the token fora KvarnPay session KvarnPay API verifies the token, opens the session 4. Amount, identity check and card paymentthen all happen inside the widget.
The token is the whole contract between us. Everything below it is ours to run.

Before you start ​

Two values identify you to us. The first Kvarn hands you when your account is created; the second you take from your KvarnPay portal:

  • Your merchant id — a UUID. It identifies you to us and is not secret.
  • Your JWT secret — the shared key your tokens are signed with. It is secret, and it is the only credential in this integration. Kvarn issues the first one; an owner in your portal can rotate it at any time (see Your portal).

Throughout this guide they appear as YOUR_MERCHANT_ID and YOUR_JWT_SECRET.

One more thing stands between your integration and the first payment: your business verification, completed by an owner in your portal. Until it is verified, a session for your customers is refused with 403 and the code merchant_kyb_required — the integration itself can be built and tested meanwhile.

Careful

The signing algorithm is HS256, which is symmetric — the same secret both signs and verifies, so anyone who can check a token can also mint one. The secret must live only on your server: never in browser code, never in a mobile app bundle, never committed to a repository. Anyone holding it can open a KvarnPay session as any of your customers.

Powered by Kvarn X

© 2026 Kvarn Capital Ltd