● Public API · /v1 · 50 endpoints Integration modes
Pick a path first, then read the integration guide. All three share the same /v1 endpoints and the same webhooks; the only difference is whether card data passes through your servers — and that single question decides your PCI scope and your timeline.
Which one to pick
Hosted checkout (HPP)
SAQ-A You have no frontend team, want to launch fastest, and do not mind redirecting to a page we host
Take a client token when creating the payment and redirect the buyer to our hosted checkout. Payment methods, 3DS and localisation are all rendered by us; you only handle the webhook.
- Effort
- 1–2 days
- Flow
- Create client session → redirect buyer → receive webhook → verify by querying
Web / App SDK
SAQ-A You want checkout embedded in your own page, keeping your branding and your checkout flow
Card fields run inside an iframe served from our origin, so your page never sees card data and your PCI scope stays SAQ-A. Styling is configurable.
- Effort
- 3–5 days
- Flow
- Create client session → mount SDK → get payment_method token → create payment server-side → receive webhook
Server-to-server (H2H)
SAQ-D You already hold a PCI DSS attestation and want to own the checkout UI completely
Card data passes through your servers, so you carry the PCI DSS Level 1 compliance cost yourself. Do not choose this path without an existing attestation.
- Effort
- 2–4 weeks plus a PCI audit
- Flow
- Build your own checkout → envelope-encrypt card fields → create payment server-side (L2 signing) → handle the 3DS redirect → receive webhook
Do not pick H2H without a PCI DSS attestation. Once a card number touches your servers, your entire infrastructure falls into audit scope, at a cost measured in six figures a year. On the other two paths card data stays inside an iframe or hosted page on our origin, and your scope is SAQ-A.
Environments
The key prefix *is* the environment, and prefix and host must match. An sk_test_ key against the live host returns 401 outright — it will never accidentally charge real money.
| Environment | Host | Key prefix |
live | https://api.baton.example | sk_live_ / pk_live_ |
test | https://api.sandbox.baton.example | sk_test_ / pk_test_ |
Secret keys are server-side only. The moment a request carries a browser Origin or Referer header we reject it and alert you — this is by far the most common way keys leak.
API reference
14 groups, 50 endpoints. These pages are generated from the OpenAPI spec, which is the single source of truth. OpenAPI spec
3 Client sessions
Exchange the context of one pending payment for a short-lived client token, which your frontend SDK or our hosted checkout renders against. Card numbers never reach your servers.
7 Payments
One endpoint for every provider. Once created, routing decides which provider to use and cascades to a backup automatically on a soft decline.
4 Payment attempts
A payment is made of N attempts, one per provider. Attempts are modelled explicitly, so the cascade is inspectable and can be intervened in.
5 Payment methods and vault
Card data lives only in the vault; your systems hold nothing but a token. Reuse, set as default, delete.
3 Customers
Map your own users onto Baton customers for stored-card reuse, risk profiling and dispute evidence.
4 Payouts
Send money to a beneficiary. Signing requirements are one level stricter than for payments (L2 asymmetric signing), and account details must be encrypted in transit.
2 Disputes
Pull chargebacks and disputes, upload evidence. The evidence window is set by the card networks and cannot be extended once it closes.
1 FX rates
Reference rates for multi-currency pricing. Settlement always uses the rate on the provider's own advice.
3 Refund
A refund is its own resource, with its own reference and status. A provider may reject a refund days later, so a failed refund has to be findable on its own.
2 Files
Upload dispute evidence. Files are bound to one purpose — this is not general-purpose storage.
5 Balances and reconciliation
Balances, settlement batches and bulk exports, so your ERP and finance systems can pull the data themselves instead of someone exporting it from the console.
6 Webhook management
Register endpoints, rotate secrets, inspect deliveries and replay them. After an outage on your side, this is how you catch up without contacting us.
3 Routing
Routing rules as configuration-as-code: published from your repository, versioned, and simulated before release. We do not lock orchestration inside the console.
2 Provider proxy
Forward your raw request to a named provider, substituting vaulted card data on the way through. For provider-specific features Baton has not abstracted yet.