Take a payment — as a sale, or as a pre-authorisation captured later — then refund, void, and read transactions. ## Getting set up ### Authentication A bearer token, created in the merchant portal under **Developer → API keys**. The token carries the merchant; there is no merchant parameter anywhere in this API. Tick **Test key** while you build — a test key can never charge a real card. ### Amounts Integer minor units: `4995` is $49.95. Sending `49.95` is a validation error rather than a 49-cent charge. ### Currencies and countries A charge is in its MID's main currency unless you send `currency`, which must be one that MID bills in — anything else is refused with `currency_not_accepted`. With no `mid_id`, we pick one of your MIDs that bills in the currency you asked for. A MID can also be limited to buyers in certain countries, checked against the billing address (`country_not_accepted`). `GET /mids` lists each MID's `currencies` and `countries`. Every transaction records the currency it was billed in. ## Taking a payment Every example goes to `POST /transactions` with your bearer token and an `Idempotency-Key`. Amounts are in minor units, so `4995` is $49.95. ### A sale — charge the card now ```http POST /api/v1/transactions Authorization: Bearer YOUR_API_KEY Idempotency-Key: order-1001 { "amount": 4995, "card_number": "4111111111111111", "exp_month": 12, "exp_year": 2030, "cvv": "123", "email": "ada@example.com", "first_name": "Ada", "last_name": "Lovelace", "address_line_1": "1 Market Street", "city": "San Francisco", "state": "CA", "postcode": "94105", "country": "US", "customer_ip": "203.0.113.7", "external_ref": "ORDER-1001" } ``` The response is the transaction: `"type": "sale"`, `"status": "approved"`. The money is taken. Keep `data.id` to refund it later and `data.card.token` to bill this card again. **Send `customer_ip`** — your customer's IP address, as your checkout saw it — on every charge your customer makes online. The processor's fraud checks use it. Without it no address is sent: the request comes from your server, and your server's address would make every customer look like the same person. ### A pre-authorisation — hold the money, take it later The same request with `"capture": false`. The issuer holds the amount on the card but nothing is taken yet — use it when you charge on dispatch, or when the final amount is not known. ```http POST /api/v1/transactions Authorization: Bearer YOUR_API_KEY Idempotency-Key: order-1002-auth { "amount": 12000, "capture": false, "card_token": "card_8fK2…", "external_ref": "ORDER-1002" } ``` The response has `"type": "authorize"` and `"status": "approved"`. Keep `data.id` — that is what you capture. **Capture within 7 days**: after that the hold is voided automatically, releasing the customer's money, you get a `transaction.voided` webhook, and a capture is refused with `authorization_expired`. ### A capture — take what the pre-authorisation is holding ```http POST /api/v1/transactions/{id}/capture Authorization: Bearer YOUR_API_KEY Idempotency-Key: order-1002-capture { "amount": 11500 } ``` Omit `amount` to take everything that was authorised, or send less and the rest is released. An authorisation is captured once. The response is a new transaction with `"type": "capture"` and `parent_transaction_id` pointing at the authorisation, which moves to `"status": "captured"`. From here the **capture** is the transaction that holds the money: refund it with `POST /transactions/{capture id}/refund`. ### Changed your mind? - **Before capture** — `POST /transactions/{id}/void` on the authorisation releases the hold. Nothing was taken, nothing is charged. - **Before settlement** — void the sale or capture. - **After settlement** — refund all or part of it. Authorisations expire at the card issuer, typically after about seven days, so capture promptly. ## Test cards With a **test key**, these numbers produce the outcome in their row on **every test MID** — our simulated gateway and NMI's sandbox alike, so the same tests run whichever processor a MID is on. Use any future expiry and any security code. On a live MID they are just invalid cards. | Outcome | Visa | Mastercard | American Express | Discover | |---|---|---|---|---| | Approved | `4242424242424242` | `5555555555554444` | `378282246310005` | `6011111111111117` | | Declined by the issuer | `4000000000000002` | `5100000000000008` | `370000000000002` | `6011000000000004` | | Declined — insufficient funds | `4000000000009995` | `5100000000009991` | `370000000009995` | `6011000000009997` | | Declined — expired card | `4000000000000069` | `5100000000000065` | `370000000000069` | `6011000000000061` | | Declined — wrong security code | `4000000000000127` | `5100000000000123` | `370000000000127` | `6011000000000129` | | Error — rejected by the gateway | `4000000000000119` | `5100000000000115` | `370000000000119` | `6011000000000111` | On a simulated test MID, any other valid number is approved — and on any card, the cents of the amount still choose a failure: ending `.05` declines, `.10` is insufficient funds, `.30` times out and `.51` is rejected by the gateway. On NMI's sandbox, any other number gets NMI's own answer. ## Billing a saved card Every sale returns a token at `data.card.token`. Send it as `card_token` with an amount and nothing else — the number, its expiry and the billing address are already ours. It works on any of your MIDs. `GET /customers/{id}` lists a customer's cards and their tokens. The card behind a token is held by us, encrypted under our own key, and never leaves. You are not storing card data by keeping a token, and we never hand back more of the number than the first six and last four digits. ## Billing a new card A new card needs a billing address. When you send `card_number`, also send `email`, `first_name`, `last_name`, `address_line_1`, `city`, `postcode` and `country` — plus `state` for US, CA and AU addresses. AVS is checked against it. Billing with `customer_id` or `payment_method_id` reuses the address already on file. ## Declines and errors A decline is a `201`, not an error. The transaction was created; read `status` and `approved` to see what the processor said, and `response_message` for why. An HTTP `4xx` means the request itself was wrong, and nothing was charged. **`status: pending` means we did not hear back from the processor** — a timeout or a dropped connection. The card may have been charged. **Do not retry it with a new key.** We ask the processor within minutes and record what it did; `GET` the transaction to see the outcome. A refund, capture or void with no answer returns `422` with code `outcome_unknown`, and nothing more can be done to that transaction until it is resolved. ## Retries and idempotency Every write requires an `Idempotency-Key` header (up to 64 characters; a UUID is ideal). Keys belong to your account and are honoured for 24 hours: - **Same key, same request** — the original response comes back, same status and body, with `Idempotency-Replayed: true`. Nothing is charged twice. A request that timed out can be retried this way safely. - **Same key, different request** — `422` `idempotency_key_reused`. Use a new key for a new request. - **While the first is still running** — `409` `idempotency_key_in_use`. Wait a moment and retry. - **After a 5xx** — the key is released; the retry runs again. A refund, capture or void is a new request and needs a new key. ## Errors Every error has the same shape, with a real HTTP status: ```json { "error": { "code": "no_rate", "message": "…", "details": {} }, "correlation_id": "…" } ``` `details` appears on validation errors, listing each field. Quote `correlation_id` to support. | Status | Code | Meaning | |---|---|---| | 400 | `idempotency_key_required`, `idempotency_key_too_long` | The header is missing or too long | | 401 | `unauthenticated` | No valid key | | 403 | `forbidden` | The key lacks the ability for this endpoint | | 404 | `not_found` | No such record for this key's account and mode | | 409 | `idempotency_key_in_use` | The same request is still running | | 422 | `validation_failed` | Fields are missing or wrong — see `details` | | 422 | `idempotency_key_reused` | The key was used for a different request | | 422 | `card_data_in_url` | Card details were in the URL — nothing was charged; treat the card as exposed | | 422 | `mid_mode_mismatch` | A test key on a live MID, or a live key on a test MID | | 422 | `no_mid`, `mid_not_granted` | No MID to bill, or that MID is not yours | | 422 | `currency_not_accepted`, `country_not_accepted` | The MID does not take that currency or that buyer's country | | 422 | `no_rate` | Live payments are not set up yet on this account | | 422 | `merchant_inactive` | The account is suspended | | 422 | `authorization_expired` | The authorisation was not captured in time and has been, or is about to be, voided | | 422 | `card_removed` | The card was removed and cannot be billed; take the number again | | 422 | `payment_intent_unavailable` | The payment was already made, cancelled, closed after five declines, or expired | | 422 | `billing_details_required` | A new card needs a billing address; send it when setting up the payment or with the card | | 403 | `merchant_unavailable` | The key's merchant account is suspended or closed | | 422 | `invalid_card`, `card_not_found`, `card_not_chargeable`, `customer_not_found`, `no_payment_method` | The card or customer could not be used | | 422 | `not_refundable`, `already_refunded`, `already_captured`, `not_voidable`, `not_chargebackable`, `already_charged_back` | That action does not apply to this transaction now | | 422 | `gateway_refused` | The processor declined a refund, capture or void | | 422 | `outcome_unknown` | No answer from the processor about an earlier action — do not retry | | 422 | `transaction_busy` | Another action on this transaction is in progress — retry shortly | | 429 | `rate_limited` | Over 600 sales, captures, refunds and voids a minute on one key — wait for `Retry-After` seconds | | 503 | `card_service_unavailable` | Card details cannot be read right now; nothing was charged | | 500 | `server_error` | Ours — quote the `correlation_id` | A **declined sale or authorisation is a `201`**, not an error: the transaction exists with `status: declined`. A declined refund, capture or void is a `422` `gateway_refused`. ## Taking payments on your website Our card form sits in your checkout page, but it is served by ChargeNation: the card number and security code go from your customer's browser straight to us and never touch your servers — the lightest PCI scope there is (SAQ A). **1. A publishable key.** In the portal, **Developer → API → Publishable keys**: give it the web addresses your checkout runs on (`https://shop.example.com`). It can show the card form on those sites and complete payments your server set up — nothing else, so it is safe in page source. Test keys complete test payments only. **2. Your server sets up the payment** with your API key, and hands the `client_secret` to the page: ```http POST /api/v1/payment-intents Authorization: Bearer YOUR_API_KEY Idempotency-Key: order-1001 { "amount": 4995, "external_ref": "ORDER-1001", "email": "ada@example.com", "first_name": "Ada", "last_name": "Lovelace", "address_line_1": "1 Market Street", "city": "San Francisco", "state": "CA", "postcode": "94105", "country": "US" } ``` The billing details are optional here: anything you leave out, send from the page with the card instead. **3. The page shows the card form and pays:** ```html

``` **4. Fulfil the order from your server**, not from the page: on the `payment_intent.succeeded` webhook, or by checking `GET /payment-intents/{id}` shows `status: succeeded`. A payment can be retried with another card after a decline, up to five times, and lasts 24 hours. With `"capture": false` the card is only held; capture its transaction as usual. The same test cards work in test mode. Style options: `color`, `placeholderColor`, `invalidColor`, `backgroundColor`, `borderColor`, `fontSize`, `fontFamily`, `borderRadius`, `padding`. The form also emits `change` (with `complete` and `error`), `focus`, `blur` and `ready`. ## The payment page No checkout of your own? Send the shopper to ours. Every payment intent comes back with a `checkout_url` — open it, put it behind a Pay button, or send it in an email or a text. The shopper sees your name (or logo), the amount and your `description`, enters their billing address if you did not send it and their card, and pays. Give `success_url` and they come back to it with `?payment_intent=pi_…` added; give `cancel_url` for a Back link. Without `success_url` the page shows its own receipt. ```http POST /api/v1/payment-intents Authorization: Bearer YOUR_API_KEY Idempotency-Key: invoice-2041 { "amount": 4995, "description": "Invoice 2041", "external_ref": "INV-2041", "success_url": "https://shop.example.com/thanks", "cancel_url": "https://shop.example.com/cart" } ``` The `checkout_url` carries the client secret after a `#`, which browsers never send to a server, so it is shown once, like the secret. Set your logo and button colour in the portal under **Developer → Payment page**; until then the page uses ChargeNation's. As with the card form, fulfil the order on the webhook or `GET /payment-intents/{id}`, not on the redirect alone. ## Webhooks We POST an event to your endpoint when something happens to your money: a payment approved, declined or failed; captured, refunded, voided or charged back; a payout sent. Add endpoints in the merchant portal under **Developer → Webhooks → Endpoints**. A test endpoint receives test events only, a live one live events only. Every event has the same envelope. `data.object` is what the event is about — a transaction in exactly the shape the API returns it, or a payout. For a capture, refund, void or chargeback, `data.related` is the transaction it acted on; otherwise it is `null`. This is a partial refund: ```json { "id": "evt_01jcz7k2v4q8m3x9t6r5w1n0ab", "type": "transaction.refunded", "created_at": "2026-11-09T18:42:07+00:00", "livemode": true, "data": { "object": { "id": 48377, "type": "refund", "status": "approved", "amount": 1500, "currency": "USD", "refunded_amount": 0, "refundable_amount": 1500, "approved": true, "response_code": "100", "response_message": "Approved", "auth_code": null, "avs_response_code": null, "cvv_response_code": null, "processor_transaction_id": "10423100007", "mid_id": 3, "customer_id": 1207, "payment_method_id": 2210, "parent_transaction_id": 48213, "external_ref": null, "payment_intent": null, "source": null, "test": false, "processed_at": "2026-11-09T18:42:06+00:00", "created_at": "2026-11-09T18:42:05+00:00", "card": { "token": "card_Xq7rT2mVb9LkP4sNw8YcJd3FhZa6GuEe", "brand": "visa", "masked": "411111••••1111", "bin": "411111", "last_four": "1111", "exp_month": 12, "exp_year": 2029 } }, "related": { "id": 48213, "type": "sale", "status": "partially_refunded", "amount": 4995, "currency": "USD", "refunded_amount": 1500, "refundable_amount": 3495, "approved": true, "response_code": "100", "response_message": "Approved", "auth_code": "831207", "avs_response_code": "Y", "cvv_response_code": "M", "processor_transaction_id": "10422981543", "mid_id": 3, "customer_id": 1207, "payment_method_id": 2210, "parent_transaction_id": null, "external_ref": "order-1001", "payment_intent": null, "source": null, "test": false, "processed_at": "2026-11-07T15:20:44+00:00", "created_at": "2026-11-07T15:20:43+00:00", "card": { "token": "card_Xq7rT2mVb9LkP4sNw8YcJd3FhZa6GuEe", "brand": "visa", "masked": "411111••••1111", "bin": "411111", "last_four": "1111", "exp_month": 12, "exp_year": 2029 } } } } ``` **Answer with any 2xx within ten seconds**, before doing any slow work of your own. Anything else — another status, a redirect, a timeout — is retried after 1 and 5 minutes, then 30 minutes, 2, 6 and 12 hours, then daily: about three days in all. After that the endpoint is switched off and your account's Owners are emailed; switch it back on under **Endpoints**. **Expect repeats and any order.** The same event can arrive more than once, and a refund can arrive before the sale it refunds. Use the event `id` to skip one you have handled, and the object's `status` rather than the order of arrival. **Missed some?** `GET /events` lists every event, newest first, and `GET /events/{id}` fetches one — the same bodies your endpoint received. Every delivery — the body we sent, your response code and any error — is under **Developer → Webhooks → Deliveries** in the portal, with **Resend**. ## Webhook events | Event | When | `data.object` | `data.related` | |---|---|---|---| | `transaction.approved` | A sale or authorisation was approved — including one that was pending and has now been settled with the processor | The sale or authorisation | — | | `transaction.declined` | A sale or authorisation was declined | The sale or authorisation | — | | `transaction.failed` | A sale or authorisation failed, or never reached the processor | The sale or authorisation | — | | `transaction.captured` | An authorisation was captured | The capture | The authorisation | | `transaction.refunded` | A refund went through, in full or in part | The refund | The sale or capture | | `transaction.voided` | A payment or authorisation was voided | The void | What was voided | | `transaction.charged_back` | A customer disputed a payment | The chargeback | The sale or capture | | `payment_intent.succeeded` | A customer paid through the card form, the payment page or a payment link — sent once, alongside the transaction's own `transaction.approved` | The payment intent | Its transaction | | `payout.sent` | We sent you a payout | The payout | — | | `ping` | **Send a test event** in the portal | — | — | ChargeNation can switch an event type off for your account. One that is off is not recorded or sent, and is not offered when you add an endpoint. An endpoint set to receive every event gets every type your account has, including ones added later. A payout: ```json { "id": "evt_01jcw3f8r2m6k9t4x7q1z5n8cd", "type": "payout.sent", "created_at": "2026-11-05T16:00:02+00:00", "livemode": true, "data": { "object": { "id": 9120, "amount": 1284650, "currency": "USD", "method": "ach", "reference": "ACH-20261105-0042", "statement_period": "2026-10", "sent_at": "2026-11-05T16:00:00+00:00" }, "related": null } } ``` ## Verifying webhook signatures Every request carries a `ChargeNation-Signature` header: ``` ChargeNation-Signature: t=1762713727,v1=1ae0b6757aa86f9cdb868614b92cfe432f3109dae760151b5c773294b6b2b968 ``` `t` is when we signed it, in Unix seconds. `v1` is the hex HMAC-SHA256 of `t`, a full stop, and the **raw request body**, keyed with the endpoint's signing secret (`whsec_…`, shown once when you add the endpoint or make a new one). 1. Read the raw body before any JSON parsing — re-encoding it changes the bytes and the signature will not match. 2. Compute the HMAC of `t + "." + body` with your secret. 3. Compare it with `v1` in constant time. 4. Reject a `t` more than five minutes from now, so a captured request cannot be replayed later. **Check your code** with secret `whsec_test`, `t` = `1762713727` and body `{"id":"evt_test","type":"ping"}`: the signature is `1ae0b6757aa86f9cdb868614b92cfe432f3109dae760151b5c773294b6b2b968`. ```php $header = $_SERVER['HTTP_CHARGENATION_SIGNATURE'] ?? ''; parse_str(str_replace(',', '&', $header), $parts); $body = file_get_contents('php://input'); $expected = hash_hmac('sha256', $parts['t'].'.'.$body, $secret); $ok = isset($parts['t'], $parts['v1']) && hash_equals($expected, $parts['v1']) && abs(time() - (int) $parts['t']) <= 300; ``` ```js // Node: express.raw({ type: 'application/json' }) keeps req.body as the raw bytes const crypto = require('crypto'); const parts = Object.fromEntries(req.get('ChargeNation-Signature').split(',').map(p => p.split('='))); const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.`).update(req.body).digest('hex'); const ok = expected.length === (parts.v1 || '').length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1)) && Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300; ``` ```python # raw_body is the request body, as bytes import hashlib, hmac, time parts = dict(p.split('=', 1) for p in header.split(',')) expected = hmac.new(secret.encode(), parts['t'].encode() + b'.' + raw_body, hashlib.sha256).hexdigest() ok = hmac.compare_digest(expected, parts.get('v1', '')) and abs(time.time() - int(parts['t'])) <= 300 ``` Making a new signing secret in the portal replaces the old one at once: update your code at the same time. ## Tracing a request Every response carries `X-Correlation-Id`. Send your own and we will use it, which is what ties your logs to ours when something needs explaining.