No. 20AthenaReference2026-06-01
The payments API,documented in pairs.
A complete reference for charging cards, issuing refunds, and replaying events. As you read, the panel on the right stays locked to the call you are looking at — request and response, side by side, so the explanation and the code never drift apart.
/v1/chargesCreate a charge
Authorize and capture a payment in a single call.
amountintegerrequired- Smallest currency unit. 4200 is $42.00.
currencystringrequired- Three-letter ISO code, lowercase — usd, eur, gbp.
sourcestringrequired- A single-use token (tok_…) minted client-side.
descriptionstringoptional- Arbitrary note shown on the customer's statement.
- returns
charge
A charge moves money from a customer to your account. Pass an amount in the smallest currency unit — 4200 is $42.00 — together with a currency and a payment source token minted client-side.
Charges are idempotent: send an Idempotency-Key header and the gateway returns the original result for any retry inside 24 hours, so a dropped connection never double-bills a customer.
/v1/charges/:idRetrieve a charge
Read the full state of any charge by its id.
idstringrequired- The charge identifier, e.g. ch_3Nq8X2.
expand[]arrayoptional- Inline related objects — balance_txn, customer.
- returns
charge
Retrieving a charge returns the live object, including capture state, dispute flags, and the balance transaction that settles the funds. Use it to reconcile against your own ledger.
Reads are free of rate-limit weight beyond the standard envelope, so polling a charge while a webhook is in flight is safe — though webhooks remain the recommended source of truth.
/v1/refundsRefund a charge
Return funds in full or in part to the customer.
chargestringrequired- The charge to credit, e.g. ch_3Nq8X2.
amountintegeroptional- Omit to refund in full; pass less for a partial.
reasonstringoptional- duplicate, fraudulent, or requested_by_customer.
- returns
refund
A refund credits a previous charge. Omit the amount to refund in full, or pass a smaller value for a partial refund — the gateway tracks the remaining refundable balance for you.
Refunds settle on the customer's original payment method. The returned object carries the expected arrival window so your support team can set accurate expectations.
/v1/eventsList events
Page through the immutable webhook event log.
limitintegeroptional- Page size, 1–100. Defaults to 10.
typestringoptional- Filter — charge.succeeded, charge.refunded.
starting_afterstringoptional- Cursor: the last event id from the prior page.
- returns
list<event>
Every state change publishes an event. List them to backfill a missed webhook or to build an audit trail; events are retained for 30 days and paginate with a cursor in the starting_after parameter.
Filter by type to narrow the stream — charge.succeeded, charge.refunded, charge.dispute.created — and verify each delivery with the signing secret before you trust its payload.
Authentication & errors
Two keys, four failures.
Authenticate every request with your secret key over HTTP Basic auth — the key as the username, the password left empty. The mode lives in the prefix: sk_live_ bills real cards, sk_test_ never moves a cent. There is no third state, so a request can never be ambiguous about which ledger it touches.
Never ship a secret key to the browser. Mint a short-lived, single-use token client-side and exchange it server-side — a leaked sk_live_ key is a leaked bank account.
- Live
sk_live_••••••••••••••••3xQ7Bills real cards. Server-side only — never in client code or a repo. - Test
sk_test_51M2cR8eZ•••sandboxSafe sandbox key. Use tok_visa, 4242…, and free retries.
Error codes
invalid_request400A required parameter is missing or malformed.Fix the bodyauthentication401The API key is absent, revoked, or for the wrong mode.Check the keycard_declined402The issuer declined the charge; inspect decline_code.Read decline_coderate_limit429Too many requests; the call was throttled.Retry-After: 2sEvery error returns a stable type, a human message, and a request id (req_…) — log the id, it is the fastest path through support.
Limits reliability
The numbers a finance team underwrites before it routes live volume. Measured against the production cluster, refreshed every minute, and audited under SOC 2 Type II.
- Live rate limit
- 1,000/minBurstable to 1,500/min per key
- p50 latency
- 38msAuthorize → response, edge-measured
- Settled uptime
- 99.99%Trailing 90 days, status-page verified
- Event retention
- 30dReplayable webhooks, cursor-paged
First-party SDKs
Install in one line.
Panel speakscURL
First-party libraries wrap auth, retries, and idempotency keys so your first charge is a single call. Pick a runtime — the code panel on the right switches to match, so what you install is exactly what you read.