API documentation

You need nothing to begin: no existing account, no email to support, no sales meeting. Eight steps separate a blank page from an authenticated sandbox call.

1. Sign up. POST /api/public/sandbox-signup is public. You declare your work email; we send you an activation link.

2. Activate your account. The link carries an activation token, which you pass to POST /api/public/sandbox-signup/set-password along with the password you choose. That token is never returned by an API response: it exists only in the email.

3. Log in to the portal. POST /api/v1/auth/login checks your credentials. Depending on your account's permissions, the portal may first have you enrol a TOTP app (QR code, then a six-digit code at every login) — keep your recovery codes safe.

4. Select your company. POST /api/v1/auth/select-company confirms which company you are working on: it is this response — not the login — that carries your session token (JWT).

5. Clear the step-up. Creating an API key is a sensitive action: POST /api/v1/auth/step-up issues a short-lived confirmation token, required at step 7.

6. Look at the available permissions. GET /api/v1/api-keys/available-permissions lists the scopes your account may grant a key. Grant only what your integration actually calls.

7. Create your key. POST /api/v1/api-keys mints it with the scopes you chose. The full key is shown exactly once, at that moment — put it straight into a vault or an environment variable.

8. Check that everything holds. GET /v1/wallet with your new key: if the balance comes back, your integration is authenticated and you can start.

Note that steps 1 to 3 are unauthenticated, steps 4 to 7 belong to the portal session, and step 8 is the first to use the API key. It is the only place in the API where those three regimes meet.

One detail that saves an hour of confusion: the sign-up and portal endpoints (steps 1 to 7) have their own error format, with ERR-XXXX codes. The envelope described in the Errors guide applies to the merchant API — the one your key calls.

Every request carries your API key in a header. There is no token to refresh and no OAuth dance: the key is enough, and it is what determines the environment.

A sandbox key starts with chari_sk_test_, a production key with chari_sk_live_. So you do not choose the environment in the URL or in a header: you choose it by choosing the key. That is deliberate — it makes it impossible to send a test request to production by mistake.

A key is a secret. It lives on your server, in an environment variable or a vault. It must never appear in code shipped to a browser, in a mobile app, in a git repository, or in a screenshot.

The /checkout/* endpoints are the exception: they are carried by the payment session itself, protected by a single-use verification key. Never send your API key there — those are the only calls the buyer's browser executes.

A network that drops between your server and ours leaves you in doubt: did the create go through? In payments, blind retries are the best way to charge the same customer twice.

Two independent mechanisms answer two different failures. They stack, and the right instinct is to know which one protects you from what.

The Idempotency-Key header protects against network retries. You send it on your creates; replaying a call with the same value returns the first result instead of creating a duplicate. That is the protection against a timeout, a dropped connection, an HTTP client retrying on its own.

The externalId field protects against business re-issue. It is unique per account and per environment: creating a resource with an externalId that already exists returns the existing resource with 200 OK, where a genuine create answers 201 Created. That is the protection against your own system re-issuing the same intent — a job re-run, a queue replayed, a double click in a back office.

So test the status, not just the body: 201 means “I just created it”, 200 means “it already existed”. Both are successes.

Refunds use refundReference for the same reason. Derive it from the order identifier — never from randomness: a deterministic reference makes replay safe, a random one refunds twice. And mind the statuses: a fresh refund answers 202 Accepted — it executes asynchronously — and a replay 200. Never 201.

The same externalId may exist once in sandbox and once in production without conflict: its deduplication is scoped to the environment. The Idempotency-Key barrier on creation, however, is scoped to the account — so keep distinct idempotency keys between your tests and your production.

Every error of the merchant API (/v1) shares the same envelope: a stable code your software can test, a readable message, and a correlationId to hand to support.

Test the code, never the message. The message may be rephrased, translated or clarified; the code is part of the contract.

The correlationId is returned on every response, including successful ones. Log it systematically: it is what lets us find one precise request in our logs.

The codes you will meet most: VALIDATION_ERROR (400, a field fails validation), UNAUTHORIZED (401, key missing or invalid), FORBIDDEN (403, the key lacks a scope), PRODUCTION_ACCESS_NOT_ENABLED (403, a production key on an account not yet enabled), WALLET_NOT_ACTIVE (422, the request is valid but a business rule blocks it) and RATE_LIMITED (429, slow down and read Retry-After).

5xx responses are on us: replay with your idempotency key rather than creating a new resource.

Three conventions hold across the API: send your own X-Request-Id — it is echoed on the response and becomes the correlationId; on the publicly exposed endpoints, read X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset to pace your traffic; and any URL you declare (return, notification) must be https://, on pain of a 400. Finally, tolerate new enum values and absent optional fields — never null: that is how the API evolves without breaking you.

List endpoints are paginated and always return the same envelope: the page contents, the page number, its size, the total number of elements and the total number of pages.

Numbering starts at zero. Never assume a list fits on one page — page through to totalPages.

On transactions, prefer cursor pagination for long traversals: ask for limit, then pass cursor = nextCursor while hasMore is true. It neither skips nor repeats a row when new transactions arrive mid-traversal.

For a large export, the dedicated transactions endpoint streams a CSV rather than a series of pages (up to 10,000 rows — beyond that, slice by period with from/to): it is faster and safer for accounting reconciliation.

A payment does not complete when you call it: the buyer goes through their bank, clears 3-D Secure, comes back. The result therefore reaches you by webhook, and the webhook is what to trust — not the browser redirect, which a buyer can interrupt by closing the tab. Polling is a fallback, not the source of truth.

You declare your receiving URLs from the API, with an explicit list of events. Only subscribe to what you handle: every needless event is a chance for a bug and a load on your server.

The URL must be public HTTPS, on port 443. localhost and private addresses are rejected at registration — in development, use a tunnel.

The signature. Every delivery carries X-CHARI-SIGNATURE: a lowercase hex HMAC-SHA256, computed over the string timestamp + "." + rawBody. The timestamp is in X-CHARI-TIMESTAMP, in epoch milliseconds.

Verification security comes down to four rules: compute the HMAC over the raw bytes before any parsing — a re-serialised JSON no longer produces the same signature; reject a timestamp skewed by more than ±5 minutes, as we do; compare in constant time (timingSafeEqual), never with ===; and during a secret rotation, accept either of the two signatures.

During a rotation, while the old secret is still in its grace window, we send the same body signed twice: X-CHARI-SIGNATURE with the old secret and X-CHARI-SIGNATURE-NEXT with the new one. Verify with the secret you hold, then cut over.

Deduplicate on Chari-Event-Id, not on Chari-Webhook-Id. This is the distinction that costs the most when you get it wrong: one logical event may be delivered several times, each attempt gets its own Chari-Webhook-Id — which therefore changes on every try — but they all carry the same Chari-Event-Id. Deduplicating on the wrong one means processing the same payment twice.

Delivery is at least once, and may arrive out of order: you will see repeats, by design. Only answer 2xx once both the business update and the dedup record have committed — any non-2xx is retried. Do the heavy work in the background: a handler that takes ten seconds eventually triggers redeliveries and, in time, the suspension of your endpoint. The first attempt fires immediately, then 1 min → 5 min → 30 min → 1 h → every 6 h, up to 16 attempts over roughly 72 hours; past that, the delivery is marked failed. After a longer outage, reconcile with GET /v1/transactions rather than waiting for a webhook that will not come back.

Your metadata and externalId come back on the events for the resource that carried them: that is how you reconcile without storing our references.

The sandbox opens immediately; production is enabled on your account after your company is verified. Until then, a production key gets an explicit 403.

Before switching, a few checks are worth the time they take: your webhook handler is idempotent and verifies the signature; your creates send an idempotency key; you log the correlationId of every call; your keys live in a vault, not in your repository; and you have tested at least one refund and one failed payment, not only the happy path.

On switch-over day you change exactly one thing: the key. URLs, payloads and error codes are identical.