● 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.

EnvironmentHostKey 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.