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