Host-to-Host overview
Server-to-server integration: your backend calls ours directly. No hosted page, no redirect, no JS on your checkout.
In a host-to-host integration your server talks to ours. You authenticate with a secret key, you create the charge, and we hand you back the data your buyer needs to pay — a CLABE, a barcode, a QR string, or a redirect URL for rails that require one. You render it in your own UI. We never inject a script into your checkout and your buyer never leaves your domain unless the rail itself demands it.
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
https://sandbox.key2pay.ai/api/v1Bearer sk_live_… / sk_test_… (or a token from /auth/token)Always USD — we convert to the buyer's local currencyIdempotency-Key on every money call. Scoped per merchant.The key decides. A sk_test_ can never touch production data.HMAC-SHA256, signed over <timestamp>.<body>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 charge |
| 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 |