Host-to-Host overview
Server-to-server integration: your backend calls ours directly. The buyer completes the required consent step on Key2Pay before payment creation.
Context and key considerations
In a host-to-host integration your server talks to ours. You authenticate with a secret key. The default version 2026-05-01 preserves HTTP 200 with a real transactionId and provider instructions. The examples below explicitly opt in with Key2Pay-Version: 2026-10-12 and receive HTTP 201 with status: awaiting_consent,transactionId: null and a checkoutUrl. Redirect the buyer to that Key2Pay URL to review the payment and explicitly accept. Only then is the provider payment created. QR codes, bank instructions and provider URLs stay protected until acceptance. Read the consent integration contractbefore using the payment examples below; completed transactions are retrieved separately.
What host-to-host means here
Concretely: every call in this section is made from your backend, with a secret key that never reaches a browser. That single constraint is what makes the model work — it is why the API can trust the caller with money movement, buyer data and payouts.
sk_live_ / sk_test_ key (or a bearer token minted from one). Publishable keys (pk_*) are safe to expose in a browser or mobile app precisely because they cannot create charges, issue refunds, read customer data or send payouts. A publishable key on any of these calls returns 403 key_kind_not_allowed.Host-to-host vs hosted checkout
Both models are supported and both settle identically. The difference is who renders the payment step and who holds the buyer's attention.
| Host-to-host | Hosted checkout | |
|---|---|---|
| Who renders the payment step | You | We do |
| Buyer leaves your domain | Only if the rail requires it | Yes |
| Credential used | sk_* (server-side) | Created server-side, buyer gets a URL |
| You handle missing buyer data | Yes — see the 422 contract | We prompt the buyer |
| Control over UX | Total | Our template + your branding |
| Integration effort | Higher | Lower |
The contract at a glance
The endpoints you'll use
The whole host-to-host surface is nine calls. Everything else in this documentation is either an alternative model (hosted checkout) or an operational convenience.
| Call | What it's for |
|---|---|
| POST /auth/token | Exchange your keys for a 1h bearer token (optional) |
| GET /payment-methods | What you can charge, for this shop, right now |
| POST /payments | Create the buyer consent session |
| GET /payments/{id} | Poll the charge — the reconciliation backstop |
| GET /payments | List + paginate |
| POST /payments/{id}/refund | Open a refund |
| POST /webhooks | Register your endpoint |
| GET /me/balance | What you're owed |
| POST /me/payout/send | Pay someone out |