Documentation · API v1
Build payments
into anything.
One REST API for online checkout, hosted payment links, recurring billing and countertop card machines. Integer amounts, mandatory idempotency on anything that moves money, and signed webhooks you can verify in ten lines.
Overview#
Wicker is a single REST API for taking money. The same credential, the same envelope and the same event stream cover four situations that are usually four separate integrations: a card entered on your own checkout, a hosted payment link you send to a buyer, a recurring charge against a card you already hold, and a card presented on a countertop machine.
The API is deliberately small and deliberately strict. Amounts are integers. Writes that can move money require an Idempotency-Key. The environment is decided by the key you present rather than by anything you send. Almost every mistake you can make surfaces as a 400 at the edge rather than as a half-completed payment three seconds later.
Base URL
https://api.wickerpay.com
Integration prefix
/api/v1
Auth
API key
Currencies
USD, CAD
What a typical integration looks like#
- Submit the onboarding application and wait for it to be approved. Until then the dashboard shows only Onboarding and Settings — there is no key to create yet, and sandbox is no exception.
- Once the account is approved, create a sandbox key under Developers → API keys and put the secret straight into your secret manager.
- Tokenize the card in your own page with the hosted card fields. Your server never sees the number; the browser gets back a single-use
tokenand a maskedcardsummary. POST /api/v1/paymentswith that token, an amount in minor units and anIdempotency-Key.- Set your sandbox webhook endpoint under Developers → Webhook endpoint and treat the webhook — not the HTTP response — as the moment of truth for anything asynchronous.
- Once your production processor account is active, switch the dashboard to Live, create live keys, and configure the production webhook endpoint. It is a second, separate endpoint, not the sandbox one repointed.
Two doors, one of which is not yours
The merchant integration surface documented here is versioned under /api/v1/... and authenticates with an API key. The dashboard also talks to its own unversioned endpoints using a short-lived session JWT. Those exist, but they are internal to the dashboard, are not versioned, and are not part of the public integration surface — do not build against them.
Quickstart#
Take a $10.50 payment. The amount travels as 1050, the funding source is a single-use token from the hosted card fields — posted together with the masked card summary the tokenizer handed back — and the Idempotency-Key is a fresh UUIDv4 that identifies this one logical operation — reuse it for retries of this payment and never for another.
curl -X POST https://api.wickerpay.com/api/v1/payments \
-H "Authorization: Bearer $WICKER_API_KEY" \
-H "Idempotency-Key: 8f0d5a2c-1e4b-4a7f-9c31-2b6d0e5a71f4" \
-H "Content-Type: application/json" \
-d '{
"amountMinor": 1050,
"currency": "USD",
"intent": "sale",
"token": "tok_5f3a9c21b7e04d18",
"card": { "last4": "1111", "bin": "411111", "exp": "1030", "type": "visa", "category": "credit" },
"statementDescriptor": "ACME COFFEE",
"description": "Order 1042"
}'// Node 18+ — global fetch, global crypto.
const res = await fetch('https://api.wickerpay.com/api/v1/payments', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.WICKER_API_KEY}`,
'Idempotency-Key': crypto.randomUUID(),
'Content-Type': 'application/json'
},
body: JSON.stringify({
amountMinor: 1050,
currency: 'USD',
intent: 'sale',
token: 'tok_5f3a9c21b7e04d18',
card: { last4: '1111', bin: '411111', exp: '1030', type: 'visa', category: 'credit' },
statementDescriptor: 'ACME COFFEE',
description: 'Order 1042'
})
});
const body = await res.json();
if (!res.ok) throw new Error(body.message);
console.log(res.status, body.data._id, body.data.status);import os, uuid, requests
res = requests.post(
"https://api.wickerpay.com/api/v1/payments",
headers={
"Authorization": f"Bearer {os.environ['WICKER_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"amountMinor": 1050,
"currency": "USD",
"intent": "sale",
"token": "tok_5f3a9c21b7e04d18",
"card": { "last4": "1111", "bin": "411111", "exp": "1030", "type": "visa", "category": "credit" },
"statementDescriptor": "ACME COFFEE",
},
timeout=30,
)
payment = res.json()
print(res.status_code, payment["data"]["_id"])The response#
An online card payment that clears returns 201 Created with the payment already in a terminal state.
{
"status": true,
"message": "Payment created.",
"data": {
"_id": "66f1c0f4a2b7e10c9d4a3f21",
"reference": "PAY-000042",
"status": "succeeded",
"intent": "sale",
"method": "card",
"amountMinor": 1050,
"capturedAmountMinor": 1050,
"refundedAmountMinor": 0,
"tipAmountMinor": 0,
"currency": "USD",
"statementDescriptor": "ACME COFFEE",
"description": "Order 1042",
"instrument": { "brand": "VISA", "last4": "1111", "cardType": "CREDIT" },
"paymentInstrumentId": null,
"authorizationCode": "084213",
"failureCode": "",
"succeededAt": "2026-08-28T09:14:23.011Z",
"createdAt": "2026-08-28T09:14:22.180Z"
}
}If you paid on a card machine, read this
The same call against a deviceId does not answer until the customer has acted. It returns 201 when they paid, 402 when the sale did not happen, and 504 when nobody presented a card within two minutes. See card-machine payments wait for the customer.
Conventions#
Base URL and versioning#
Everything you integrate against lives under https://api.wickerpay.com/api/v1/. The v1 segment is a contract: fields are added, never removed or repurposed, within a version. Treat unknown fields in a response as forward compatibility rather than as an error, and never assume the object you receive contains only the keys documented here.
The dashboard's own endpoints are unversioned and authenticate with a session JWT rather than an API key. They are mentioned only so you recognize them if you see them in a browser network panel. They are not a supported integration surface and they change without notice.
Response envelope#
Every response, at every status code, is a JSON object carrying a boolean status. On success it is true, the payload sits under data, and a short human-readable message comes with it. On failure it is false and message is the explanation.
{
"status": true,
"message": "ok",
"data": { /* the resource, or a list plus its pagination block */ }
}{
"status": false,
"message": "amountMinor must be an integer of at least 1"
}Do not branch on message text
message is written for a human being reading a log or a support ticket. It is safe to show to your staff, it is not stable, and it is not an error code. Branch on the HTTP status. If you need finer behavior than the status gives you, branch on the resource's own status field instead.
Identifiers#
Every object you address in a path is addressed by its _id — a 24-character hexadecimal string — and that is the field you store. Payments and refunds additionally carry a human-readable reference such as PAY-000042 or RFD-000018; it is unique within your account, it is what support will ask you for, and it is not interchangeable with _id in a URL. Identifiers issued by the payment processor are never accepted from you, and only the ones a processing statement already shows are returned: a payment's nmiTransactionId and nmiBatchId, and a settlement's batchReference (the same batch id). Nothing else of the processor's — vault ids, order ids, decline text — is ever on an object you receive, and none of them is accepted in a request.
Money is always an integer#
Every monetary field ends in Minor and carries an integer number of minor units. 1050 is $10.50. 1 is one cent. Sending 10.50, "10.50" or 1050.0 is a 400 — floats are rejected at the edge rather than rounded, because silently rounding somebody's money is worse than refusing it.
Both supported currencies — USD and CAD — have two decimal places, so today a minor unit is always a cent. Read the currency alongside the amount rather than hard-coding a divisor: if a currency with a different exponent is ever added, code that divides by 100 unconditionally will be wrong on every figure it prints.
Currencies#
- USD
- CAD
Where a request omits currency, USD is assumed. A refund is always issued in the currency of the original payment; there is no cross-currency refund.
Environments#
There are two environments, sandbox and production. The dashboard's switch, at the top right of every screen, labels them Sandbox and Live; moving to Live asks you to confirm, moving back does not. In the API, which environment you are in is resolved entirely from the API key you present — never from a request body, a query parameter, a path segment or a header you control. A sandbox key cannot read or write live data, and a live key cannot see anything you created in sandbox.
That has a practical consequence worth internalizing early: objects do not migrate. A customer, a stored instrument, a payment link or a registered device created in sandbox does not exist in production. Going live means creating them again with live credentials.
Authentication#
You authenticate against Wicker with an Wicker API key and nothing else. You never hold, present or configure a credential belonging to the payment processor; the relationship between Wicker and our processing partner is not part of your integration.
Key format#
A key is two parts joined by a dot: <keyId>.<secret>. The key id looks like gw_test_ or gw_live_ followed by 24 hexadecimal characters. The secret is base64url.
gw_test_9c1f4a02b7de5183aa60c4e2.Zm9vLWJhci5iYXo_cXV4LTAx
└────────── keyId ─────────┘ └─────── secret ────────┘
# Split on the FIRST dot only.
# The secret is base64url and may itself contain dots.
# Splitting on every dot can silently corrupt the secret.Split on the first dot
If you parse a key yourself, take everything before the first . as the key id and everything after it — dots included — as the secret. A naive split('.') that keeps only the second element will silently truncate some secrets and you will spend an afternoon debugging an intermittent 401.
Presenting the key#
Two headers are accepted and they are equivalent. Use whichever your HTTP client makes cleaner. Send one, not both.
Authorization: Bearer gw_live_3b8e1d47f02ac5916de4b7c0.SGVsbG8td29ybGQtc2VjcmV0
# …or…
X-API-Key: gw_live_3b8e1d47f02ac5916de4b7c0.SGVsbG8td29ybGQtc2VjcmV0Storage and rotation#
Keys are created under Developers → API keys in the dashboard, with Create key. You name the key, pick its environment, and the dialog then shows you the key id, the secret, and the exact <keyId>.<secret> string to send — so nobody has to work out the concatenation. The secret is shown once, at that moment, and is not recoverable afterwards — not by you, not by support. Put it straight into a secret manager. Do not commit it, do not put it in a front-end bundle, and do not send it to a browser: an API key is a server credential.
The key list shows both environments at once, because the environment is baked into the key and a list filtered by whatever the dashboard is currently set to would hide half of them. Each row carries a Last used time, which is the only reliable way to tell whether something is still calling with a key before you take it away.
Rotation happens on the same screen, with Rotate. It issues a new secret and puts the old one on a clock whose length you choose: stop immediately, 1 hour, 24 hours (the default), 3 days, or 7 days, which is the maximum. Until that expires both secrets work, so a rolling deploy can have old and new instances running at the same time without a window of 401s, and the old key is listed as rotating with the moment it stops. Deploy the new secret everywhere, confirm traffic has moved, then let the clock run out.
Revoke is the other lever and it is not the same thing. It has no grace period: the key stops working at once and anything still using it starts failing immediately. That is exactly what you want after a leak, and exactly what you do not want during a planned change — use rotation for that.
What a key is scoped to#
A key is bound to one merchant and one environment, both fixed when the key is minted and neither influenced by anything you send. Every key can reach the whole /api/v1 surface for that merchant and environment; there are no per-operation permissions today, so treat every key as able to move money and issue one per deployment rather than one per team. A key asking for an object that belongs to another merchant gets a 404, never a 403.
Because there is no read-only key, the controls that matter are the ones you already have: separate keys per service so one can be revoked without an outage, rotation rehearsed before you need it, and secrets kept in a secret manager rather than in a repository.
The dashboard's own roles do not carry over. A colleague invited under Settings → Team is either an Admin or a Member; a Member can see the key list and its last-used times but cannot create, rotate or revoke a key, and the same split applies to the webhook endpoint. That is a control over who touches credentials in the dashboard, not over what a credential can do — every key, whoever minted it, reaches the whole /api/v1 surface.
Optional request signing#
A key can be marked signature-required. That is a checkbox — Require a request signature — on the Create key dialog, and it is fixed for the life of the key: there is no way to switch signing on or off afterwards, so a key that needs it is minted with it. Every request made with such a key must carry an additional header:
X-Gateway-Signature: t=1774689262,v1=6b1f0e3c9a47d5820ecb1f47a3d90c5e7182ba63c04f9d1e8a72b5c6d3e0f419
# t = unix seconds at the moment you sign
# v1 = hex HMAC-SHA256 over these four parts, each joined by one newline (\n):
# <t>
# <METHOD>
# <path and query>
# <raw request body>
# keyed with your API key secret (the part after the first dot)- The signed payload is
<t>\n<METHOD>\n<path and query>\n<raw request body>— the four parts joined by a single newline, one byte, with no other separator. <METHOD>is upper case.<path and query>is the request target exactly as sent, not decoded and with no host, such as/api/v1/payments/PAY-1?expand=refunds. A signature made for one call does not verify on another.- Sign the raw bytes you actually transmit. Serialize once into a string, sign that string, send that string. Re-running
JSON.stringifyon a parsed object reorders keys and changes whitespace, and the signature will never match. A binary body, such as a dispute evidence upload, goes into the HMAC as the bytes you send: decoding it to a string first is lossy. - For a request with no body, such as a
GETor aDELETE, the body part is empty, so the string ends in the third newline:<t>\n<METHOD>\n<path and query>\n. - A request is accepted within ±5 minutes of
t. The window is symmetric on purpose: your clock may be behind ours or ahead of it, and either way we should not reject a legitimate call. - A signature is accepted once. Inside that window, a repeat of the same call — the same
t, method, path and query, and body — is refused with401, whatever happened to the first copy. Two different calls in the same second have different signatures and both pass. A client that must resend an identical call, a retry or a repeated poll alike, signs it again with a latert. A retry of a money-moving write keeps the sameIdempotency-Key.
const crypto = require('node:crypto');
const keyId = process.env.WICKER_KEY_ID; // gw_live_3b8e1d47f02ac5916de4b7c0
const secret = process.env.WICKER_SECRET; // everything after the first dot
// Serialise ONCE. This exact string is what gets signed and what gets sent.
const body = JSON.stringify({
amountMinor: 1050,
currency: 'USD',
token: 'tok_5f3a9c21b7e04d18'
});
const t = Math.floor(Date.now() / 1000);
const method = 'POST';
const target = '/api/v1/payments'; // path and query exactly as sent, no host
const v1 = crypto
.createHmac('sha256', secret)
.update(`${t}\n${method}\n${target}\n`)
.update(body) // a string or a Buffer: the bytes you send
.digest('hex');
const res = await fetch(`https://api.wickerpay.com${target}`, {
method,
headers: {
'Authorization': `Bearer ${keyId}.${secret}`,
'X-Gateway-Signature': `t=${t},v1=${v1}`,
'Idempotency-Key': crypto.randomUUID(),
'Content-Type': 'application/json'
},
body // the very same string that was signed
});Authentication failures#
A missing key, a malformed key, an unknown key id, a wrong secret, a revoked key, a missing signature, a bad signature, a stale timestamp and a repeated signature all produce 401. An unknown key id and a wrong secret get the same message, Invalid API key., so we do not tell an unauthenticated caller whether a key id exists, because that would turn the endpoint into an oracle for enumerating credentials. The other cases say which they are: a revoked key, a key past its rotation window, a missing, malformed, stale or repeated signature, a suspended or rejected merchant account, and an account whose onboarding application has not been submitted each have their own 401 message. When you get a 401, check, in order: the header name, the split on the first dot, the environment of the key, and your server's clock. Request signature does not match. means the string you signed is not the one we rebuilt, so check the upper-case method, the path and query as sent, and the raw body. Request signature has already been used. means the same call arrived twice, so sign the resend with a later t.
Idempotency#
Networks fail after the request arrives and before the response gets home. Idempotency is how you retry that request without charging somebody twice.
Where it is required#
An Idempotency-Key header is mandatory on every write that can move money. Omit it and the request is rejected with a 400 before anything happens.
| Operation | Idempotency-Key | Why |
|---|---|---|
POST /payments | Required | A repeat would create a second charge. |
POST /payments/{id}/capture | Required | A repeat would capture twice against one authorization. |
POST /payments/{id}/void | Required | A repeat races with a capture. |
POST /payments/{id}/refunds | Required | A repeat would return the money twice. |
Everything else — reads, PATCH, and creating customers, links, subscriptions and devices | Not required | None of these move money, so a repeat costs you a duplicate row at worst. Requiring a key would be ceremony with no safety behind it; one sent anyway is simply ignored. |
The rules#
- Maximum length is 255 characters. Use a UUIDv4 generated once per logical operation and reused for every retry of that operation.
- A replayed key returns the original response byte for byte — same status code, same body — with the extra header
Idempotent-Replay: true. It does not re-run anything. - The identity of a key includes the request path. The same key value on
/api/v1/paymentsand on/api/v1/payments/{id}/refundsis two different operations, and neither will replay the other. - If the first request bearing a key is still in flight, a second request with that key gets
409. The in-flight lease lasts 5 minutes; back off briefly and retry. - Reusing a key with a different body, or on a different operation, is
422. That is not a retry, it is a bug in the caller — usually a key generated per HTTP attempt, or once per process, instead of once per operation. - A key whose first attempt died mid-flight is resolved to a
504once its lease runs out, and every retry replays that answer. It is deliberately not re-executed: nobody saw the outcome of the first attempt, so re-running it could charge the cardholder twice. Check the named record before you send anything else. - A write that failed — a validation
400, a state-conflict409— releases its key. That is deliberate: the failure did not move money, so once you have fixed the request you may retry it under the same key. Only a completed request, or one whose outcome is unknown, pins its key to a stored answer. - Keys are retained for 24 hours. After that the key is forgotten and the same value would execute again as a fresh request.
Generate the key where the intent lives
Create the UUID at the point your system decides “this order should be charged” and persist it with the order. Do not create it inside your HTTP retry loop — a key that changes on every attempt provides exactly no protection, which is the failure mode idempotency exists to prevent.
# Stored against order 1042 when the order was placed.
KEY="8f0d5a2c-1e4b-4a7f-9c31-2b6d0e5a71f4"
curl -X POST https://api.wickerpay.com/api/v1/payments \
-H "Authorization: Bearer $WICKER_API_KEY" \
-H "Idempotency-Key: $KEY" \
-H "Content-Type: application/json" \
-d '{"amountMinor":1050,"token":"tok_5f3a9c21b7e04d18"}'
# Timed out? Send the identical request again with the identical key.
# You get the original response back, plus: Idempotent-Replay: trueErrors#
The HTTP status is the contract. Every failure body is { "status": false, "message": "…" }; the message explains, the status decides.
Status codes#
- 400
- Validation or malformed request. A missing required field, a float where an integer belongs, an unparseable body, a missing
Idempotency-Keyon an operation that requires one, two funding sources where exactly one was expected, a capture larger than the authorization, or a refund larger than the remaining headroom. Fix the request; retrying it unchanged will fail identically. - 401
- Bad or missing credential. Also covers a missing or invalid
X-Gateway-Signatureon a signature-required key, a timestamp outside the ±5 minute window, a signature that has already been used, a merchant account that is suspended or rejected, and an account whose onboarding application has not been submitted. An unknown key id and a wrong secret share one message; the other cases each name themselves. - 402
- A card-machine sale that did not happen: the issuer declined at the terminal, the customer cancelled, the card would not read, or the terminal was busy or offline. The body carries
status: falseand the payment record underdata—data.failureCodesays which — so you have the evidence of the attempt. Nothing was collected. - 403
- Authenticated, but the merchant account itself cannot transact — suspended, or in a status that is not active. Not a retryable condition, and not something a different key fixes; contact support.
- 404
- Not found within your scope. See the note below: this is the same answer you get for an object that exists but is not yours.
- 409
- The request is well-formed and the state of the world says no. A capture or void against a payment whose status does not allow it, a refund on a disputed payment, a sale the processor refused as a duplicate of a recent payment on the same card for the same amount (the record exists as
failedwithfailureCode: "DUPLICATE"),allowDuplicateson an account whose processor does not permit it, an onboarding application that has not been submitted, a duplicate record, or anIdempotency-Keywhose first request is still in flight. Safe to retry only in the in-flight case, after a short backoff. - 422
- Idempotency-key misuse, and nothing else. The same key was already spent on a different operation, or replayed with a different request body. Both are caller bugs: mint a new key for a new operation.
- 429
- Rate limited. Every
429carries aRetry-Afterheader in seconds; honor it, then back off exponentially with jitter. - 500
- Something unexpected on our side. Retry with the same
Idempotency-Key; if the original did take effect, you get the original response back rather than a second charge. - 502
- Our processing partner returned something we could not act on. The payment's true state may still be settling — retry with the same idempotency key, and reconcile with
POST /payments/{id}/syncif the ambiguity persists. - 504
- Outcome unknown, not failure. We stopped waiting for the processor, so the money may or may not have moved. The body names the record to poll. Do not retry with a new key — that is how a cardholder gets charged twice. Retrying with the same key replays this same answer until the record resolves, which it normally does within minutes. On a terminal sale it also means nobody presented a card within two minutes: the request was cancelled at the terminal and the record is
unknown— a tap that landed in that same moment is recovered within minutes, so poll it rather than re-ringing the sale.
404 is deliberately ambiguous
“This object does not exist” and “this object exists and belongs to another merchant” return exactly the same 404. Distinguishing them would let anyone with a valid key probe for other merchants' identifiers. Treat a 404 as “not yours” and do not read anything more into it.
Rate limits#
Rate limits are keyed on the credential, not on the source IP address. A merchant behind a corporate NAT, a fleet of workers sharing one egress address, or a container platform that recycles addresses every deploy all get the budget that belongs to their key — not a budget shared with whoever else happens to be on the same address.
The budget is 600 requests per minute per key on /api/v1. Every response — not only a rejection — carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, so a bulk client can slow down before it is refused rather than after.
The practical corollaries: giving each worker its own key gives each worker its own budget, and a runaway job in one service cannot starve another service that uses a different key.
Handling a 429#
- Honor the
Retry-Afterheader. It is the shortest wait we know will help. - Otherwise back off exponentially — roughly 1s, 2s, 4s, 8s — with jitter, so a fleet that all got limited at the same instant does not all retry at the same instant.
- Cap the number of attempts and surface the failure. A queue that retries forever hides an integration that has outgrown its limits.
- Retries of a money-moving write must carry the same
Idempotency-Keyas the attempt that was limited.
Pagination#
Filtered reads are POST requests to a /list sub-path with the filters in a JSON body. It looks unusual for a read, and it is deliberate: filters are structured, sometimes long, and sometimes contain values that have no business sitting in a query string or in an access log. Posting them lets them travel in a body.
| Field | Type | Required | Description |
|---|---|---|---|
page | integer | Optional | 1-based page number. Defaults to 1. |
limit | integer | Optional | Rows per page. Defaults to 25 and is clamped to a maximum of 100. |
| resource filters | object | Optional | Whatever the resource supports — status, date range, customer, device, and so on. Filters combine with AND. |
curl -X POST https://api.wickerpay.com/api/v1/payments/list \
-H "Authorization: Bearer $WICKER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"page": 1,
"limit": 25,
"status": "succeeded"
}'{
"status": true,
"message": "ok",
"data": {
"payments": [ /* … */ ],
"pagination": {
"page": 1,
"limit": 25,
"total": 318,
"pages": 13
}
}
}
// The array is named after the resource: "payments", "buyers",
// "devices", "subscriptions", and so on. "pagination" is always "pagination".Walk pages by incrementing page until it exceeds data.pagination.pages. Because new objects arrive while you paginate, a deep page walk over a busy account can see an item twice or miss one; if you are exporting rather than browsing, pin a date range in the filter so the result set stops moving underneath you.
Tokenizing a card#
A card number never reaches your servers, and there is no endpoint here that accepts one. The card is turned into a single-use token inside the buyer's browser by our hosted card fields, and that token is what you post to POST /api/v1/payments. The dashboard's own New payment screen and every payment link page work exactly this way; this section is for a checkout you build yourself.
The tokenization config#
Two values differ per environment and, on some accounts, per merchant: the public tokenization key and the script URL that serves the hosted fields. Neither is a secret — the key authorizes tokenization and nothing else — but do not hard-code them. Read them from the API with the same key you use for everything else; the environment of that key decides which tokenization key comes back, so a sandbox key can never hand your page the production one.
/api/v1/tokenization-config
curl https://api.wickerpay.com/api/v1/tokenization-config \
-H "Authorization: Bearer $WICKER_API_KEY"{
"status": true,
"message": "ok",
"data": {
"environment": "sandbox",
"driver": "live", // "mock" in a sandbox that runs on the built-in simulator — see Testing
"tokenizationKey": "7hQ2xk-9mVd4P-Ab3Nz8-Kw5Ty1",
"scriptUrl": "https://…/token/Collect.js",
"keySource": "platform",
"wallets": { "googlePay": true, "applePay": false, "domain": "", "displayName": "Acme Coffee" }
}
}Read it once per environment at deploy time — it is a read, so it is not idempotency-guarded and it counts against your rate budget like any other call — and put tokenizationKey and scriptUrl into your page's configuration. wallets.googlePay and wallets.applePay say which wallet buttons would actually work; domain is the domain registered for Apple Pay and displayName the merchant name a wallet sheet shows. The dashboard reads the same object through its own session, which is why its New payment screen and yours tokenize identically.
Mounting the fields#
Load the script once, with the key on the tag, and mount one hosted field per selector. The host elements are plain <div>s you own and style around; the inputs inside them are served from the tokenizer's own origin, which is the PCI boundary. Style the inputs through the configuration object rather than your stylesheet, show the form only after the fields report themselves mounted, and treat a tokenization that never answers as "try again", never as paid.
<script src="{scriptUrl}" data-tokenization-key="{tokenizationKey}" data-variant="inline"></script>
<div id="card-number"></div>
<div id="card-expiry"></div>
<div id="card-cvv"></div>
<button id="pay">Pay $10.50</button>
<script>
CollectJS.configure({
variant: 'inline',
fields: {
ccnumber: { selector: '#card-number', placeholder: 'Card number' },
ccexp: { selector: '#card-expiry', placeholder: 'MM / YY' },
cvv: { selector: '#card-cvv', placeholder: 'CVC', display: 'show' }
},
fieldsAvailableCallback: () => showForm(),
timeoutDuration: 15000,
timeoutCallback: () => showRetry(),
callback: (r) => {
// r.token is single-use and expires in 24 hours.
// r.card is { number (masked), bin, exp "MMYY", type, category, hash }.
postToYourServer({ token: r.token, card: r.card });
}
});
document.getElementById('pay').onclick = () => CollectJS.startPaymentRequest();
</script>Your server then makes the POST /api/v1/payments call with the token and, verbatim, the card object the callback handed you. The token is the money; the card object is description — brand, last four, expiry, BIN and the category that decides whether a surcharge is lawful. Nothing in it is trusted for anything else: when it is absent the stored instrument is read back from the vault, and a missing category is looked up from the BIN.
Bank accounts and wallets#
- Bank accounts. Mount
checkname,checkabaandcheckaccountfields instead of the card ones. The callback then carriescheck: { name, account, aba, hash }; post that ascheckalongside the token, which is also how the API knows the token is a bank account. The resulting payment ispendinguntil the bank settles or returns it — days, not seconds. - Apple Pay and Google Pay. The tokenizer renders the wallet button itself (
fields.applePay,fields.googlePay, plusprice,currencyandcountryin the configuration) and the button produces the same kind of token a card does. Post it withwallet: "apple_pay"or"google_pay"so the payment is typed correctly for pricing and disputes. Apple Pay additionally needs your domain registered with us; render the button only when the config'swallets.applePayistrue. There is no session-validation endpoint to call — the tokenizer handles Apple's merchant validation on the registered domain. - Re-configure, do not re-inject. One script per page. If the amount changes after the wallet button is mounted, call
configureagain with the newprice; adding the script tag twice is the reliable way to break the page.
Why this keeps you in SAQ-A
The card number, expiry and security code are typed into fields served from the tokenizer's origin and go straight to the vault; your page receives an opaque token and a masked summary. Your servers never see, transmit or store cardholder data, which is what keeps a standard integration inside PCI DSS SAQ-A — the shortest of the self-assessment questionnaires. You lose that the moment you take card numbers into your own inputs and forward them. Do not build that.
Payments#
A payment is one attempt to move money from a buyer to you. The same object covers a card tokenized in your checkout, a bank account, a wallet, a card already on file, and a card tapped on a countertop machine — the difference is which funding source you supply.
POST
/api/v1/payments
Create a payment. An Idempotency-Key header is required.
Exactly one funding source
Supply one of token, paymentInstrumentId or deviceId. Supplying two of them, or none of them, is a 400. There is no precedence rule and no fallback — an ambiguous request is rejected rather than guessed at.
| Field | Type | Required | Description |
|---|---|---|---|
amountMinor | integer | Required | Minor units, at least 1. 1050 is $10.50. A decimal is a 400. There is also a ceiling — your account's approved per-transaction maximum, up to a platform limit of $10,000.00 — and exceeding it is a 400 that names the figure. |
currency | enum | Optional | USD or CAD. Defaults to USD. |
intent | enum | Optional | sale authorizes and captures in one step. authorization authorizes only, leaving you to capture later. Defaults to sale. |
token | string | One of three | A single-use token from the hosted card fields — a card, a bank account or a wallet all produce one. Spent by this request; it expires 24 hours after it was minted. |
paymentInstrumentId | string | One of three | A stored instrument — a card or bank account you already have permission to charge. |
deviceId | string | One of three | A card machine. This must be your device id from this API, never an identifier issued by the payment processor. The request then waits for the customer, up to two minutes — see below. |
card | object | Optional | The card object the tokenizer's callback handed you, passed through as received: { number | last4, bin, exp, type, category, hash, name }. Describes the stored instrument without a second round trip, and category — credit, debit or unknown — is what decides whether a surcharge is lawful. Fields below. |
check | object | Optional | The tokenizer's check object for a bank-account token: { name, account, aba, hash }. Sending it is also how the API knows the token is a bank account rather than a card. |
wallet | enum | Optional | apple_pay or google_pay when the token came from a wallet button. Types the payment for pricing and disputes; the token itself is the same kind a card produces. |
buyerId | string | Optional | The _id of an existing customer to attach the payment to. Supply this or buyer, not both. |
buyer | object | Optional | Inline buyer details when you do not already have a customer. Fields below. |
customerReference | string | Optional | Your own identifier for the buyer. Up to 120 characters. Stored and returned; never shown to the cardholder. |
statementDescriptor | string | Optional | Up to 22 characters. This is what the cardholder sees on their bank statement — a descriptor they do not recognize is the leading cause of avoidable disputes. It is sent to the card networks only where your account supports a dynamic descriptor; it is stored on the payment either way. |
description | string | Optional | Up to 255 characters. Internal; appears in the dashboard and in exports, and is searchable. |
tipAmountMinor | integer | Optional | Minor units, 0 or more. Use this when the tip was decided by your own interface. Sending it alongside a deviceId is a 400 — a tip on a terminal is entered by the cardholder on the terminal, so turn the tip prompt on for that device instead. |
supplementalFeeMinor | integer | Optional | Minor units, 0 or more. An additive per-transaction fee added on top of the amount. Check what your jurisdiction and card scheme rules permit before charging one. |
buyerCharge | object | Optional | A charge passed on to the buyer, itemized on the payment: { "type", "amountMinor" }, where type is surcharge, convenience or rent_surcharge and amountMinor is an integer of at least 1. At most one per payment. A surcharge is credit-cards-only — a card whose category is debit or unknown is refused — and capped by the schemes at 3% (2.5% in Canada). Not accepted alongside a deviceId; a terminal computes its own surcharge from the rate configured on it. |
storeInstrument | boolean | Optional | Keep the card or bank account on file instead of treating it as single-use. The resulting paymentInstrumentId comes back on the payment and can be charged again later. |
purchaseData | object | Optional | Level 2 / Level 3 purchase data for commercial cards, which lowers interchange on them: { sales_tax, tax_exempt, customer_reference_number, invoice_reference_number, destination_postal_code, ship_from_postal_code, summary_commodity_code, shipping_amount, discount_amount, duty_amount, item_data: [ … ] }. Each item_data entry is { item_description, quantity, amount_excluding_sales_tax, amount_including_sales_tax, sales_tax, merchant_product_code, commodity_code, unit_of_measure, item_discount_amount }, up to 99 of them. Accepted on card-machine sales too: the tax and order description land on the processor's transaction record, while what it keeps of the line items, and whether the terminal's printed slip lists them, depends on the device. The terminal shows the customer the amount. |
allowDuplicates | boolean | Optional | Switch the processor's duplicate check off for this one sale — two genuine coffees five minutes apart on the same card look like a duplicate to the processor and not to the café. Honoured only where your account permits it; elsewhere the request is refused with a 409 that says so, before anything is charged. |
buyerIpAddress | string | Optional | The cardholder's IPv4 address, not your server's. Anything that is not a dotted-quad IPv4 address is a 400. Sending your own egress address makes every payment look like it came from one place and actively degrades risk scoring — omit the field rather than guessing. |
tags | object | Optional | Up to 50 key/value pairs. Keys up to 40 characters and not blank, values up to 500. Your metadata; returned unchanged and never sent to the processor. |
The card and check objects
Both are the tokenizer's own callback objects, passed through as received. Nothing in them moves money — the token does that — and nothing in them is required. They are the difference between a payment that comes back describing the card and one whose description has to be read back from the vault.
| Field | Type | Limit | Description |
|---|---|---|---|
card.number | string | ≤ 32 | The masked number as the tokenizer returned it, e.g. 411111******1111. Send this or last4. |
card.last4 | string | 4 | The last four digits, if you would rather not forward the masked number. |
card.bin | string | ≤ 8 | The first six digits. |
card.exp | string | ≤ 6 | Expiry as MMYY. |
card.type | string | ≤ 40 | The brand as the tokenizer names it — visa, mastercard, amex, discover… Normalized to the instrument.brand enum on the way in. |
card.category | enum | — | credit, debit or unknown. Becomes instrument.cardType and gates buyerCharge.type: "surcharge". When omitted it is looked up from the BIN, which answers UNKNOWN on some cards — and UNKNOWN is refused for surcharging. |
card.hash | string | ≤ 64 | The tokenizer's card hash. Stored so the same physical card can be recognized across tokens. |
card.name | string | ≤ 100 | The name on the card, when your form collected one. |
check.name | string | ≤ 100 | The account holder. |
check.account | string | ≤ 32 | The masked account number as the tokenizer returned it. |
check.aba | string | ≤ 16 | The routing number. Its last four become bankRoutingLast4 on a stored instrument. |
check.hash | string | ≤ 64 | The tokenizer's account hash. |
The buyer object
| Field | Type | Limit | Description |
|---|---|---|---|
email | string | — | Buyer email address. |
firstName | string | ≤ 50 | Given name. |
lastName | string | ≤ 50 | Family name. |
businessName | string | ≤ 100 | Trading name, where the buyer is a business. |
phone | string | ≤ 20 | Contact number. |
address.line1 | string | ≤ 100 | Street address. Used for address verification — avsResult on the payment — and including it lowers interchange. |
address.line2 | string | ≤ 100 | Apartment, suite, unit. |
address.city | string | ≤ 50 | City or town. |
address.region | string | ≤ 50 | State or province. |
address.postalCode | string | ≤ 20 | Postal or ZIP code. |
address.country | string | 3 chars | Three-letter country code. Defaults to USA. |
The payment object
Every payment endpoint answers with the same object, and it is also the data of every payment.* webhook. Timestamps are ISO-8601 strings or null; identifiers issued by the processor are never on it.
| Field | Type | Description |
|---|---|---|
_id | string | The identifier you store and address the payment by. |
reference | string | Human-readable, unique within your account: PAY-000042. What support will ask you for. |
status | enum | One of the payment statuses. |
intent | enum | sale or authorization, as requested. |
method | enum | The rail: card, bank, apple_pay or google_pay. |
source | enum | Where the payment came from: api, portal, checkout (a payment link), terminal, pos or subscription. Derived from the credential and the funding source, never from anything you send — it selects the rate. |
amountMinor | integer | What was requested, plus any tip entered on a terminal. |
capturedAmountMinor | integer | What has actually been captured. Less than amountMinor after a partial capture. |
refundedAmountMinor | integer | The total of refunds that have not failed. Headroom is capturedAmountMinor − refundedAmountMinor. |
currency | enum | USD or CAD. |
description, statementDescriptor | string | As sent. |
buyerId | string | The customer, when one was attached or created inline. |
paymentInstrumentId | string | The stored instrument this charged, or that storeInstrument created. null on a single-use token and on every terminal sale. |
instrument | object | A display summary — { brand, last4, expirationMonth, expirationYear, cardType }. brand is VISA, MASTERCARD, AMERICAN_EXPRESS, DISCOVER, JCB, DINERS_CLUB, MAESTRO, CHINA_UNION_PAY, EBT or UNKNOWN; cardType is CREDIT, DEBIT, PREPAID, CHARGE, DEFERRED_DEBIT, UNKNOWN or blank. Never an id you could charge. |
buyerCharge | object | { type, amountMinor } when one was applied, otherwise null. |
tipAmountMinor | integer | The tip, whether you sent it or the cardholder entered it on the terminal. |
avsResult | enum | POSTAL_CODE_AND_STREET_MATCH, STREET_MATCH, POSTAL_CODE_MATCH, NO_ADDRESS, NO_MATCH, NOT_SUPPORTED, UNKNOWN or blank. |
cvvResult | enum | MATCHED, UNMATCHED, NOT_PROCESSED, NOT_PRESENT, NOT_SUPPORTED, UNKNOWN or blank. |
failureCode | string | Why a payment did not succeed. For an issuer decline it is the processor's response code as a string — 200 generic decline, 202 insufficient funds, 223 expired card, 225 CVV mismatch, 240 call issuer, 250–253 do not retry, 261/262 stop recurring, 264 retry later, and so on. Our own codes: DUPLICATE, UPSTREAM_ERROR, and on terminals TERMINAL_CANCELLED, TERMINAL_TIMEOUT, TERMINAL_DISCONNECTED, TERMINAL_BUSY, TERMINAL_BAD_CARD_READ, TERMINAL_FAILED. Blank on success. |
failureMessage | string | Our wording for the failure, written to be read aloud to the person holding the card. Never the processor's own text, which can name a fraud rule or say "stolen". |
bankReturn | object | Present only on a returned bank debit: the return reason code and description. Otherwise null. |
refunds | array | Every refund against this payment: { _id, reference, amountMinor, status, reason, failureCode, failureMessage, createdAt, succeededAt, failedAt }, where status is pending, succeeded or failed. |
disputed | boolean | A chargeback is open or was lost. See Disputes. |
authorizationCode | string | The issuer's approval code — the one value a cardholder's bank can look up. |
subscriptionId | string | Set on a recurring collection, so an order system can tell a purchase from a monthly charge. Otherwise null. |
deviceId | string | Which terminal took it. Otherwise null. |
cardPresent | object | On a terminal sale, what the card and the terminal said to each other: the entry mode and the EMV block your processing agreement obliges you to be able to print. Otherwise null. |
paymentLinkId | string | Which payment link collected it. Otherwise null. |
tags | object | Your metadata, unchanged. |
authorizedAt, capturedAt, succeededAt, failedAt, voidedAt | timestamp | When each transition happened. null until it does. |
settledAt | timestamp | When the payment landed in a closed settlement. |
expiresAt | timestamp | On an uncaptured authorization, when the hold will lapse — roughly seven days out. |
nmiTransactionId | string | The processor's transaction reference — the number a statement, a support ticket or the acquirer will quote. Blank until the processor has answered. |
nmiCondition | string | The processor's own lifecycle word for the transaction, as last read — for the support conversation, not for your state machine: branch on status. |
nmiBatchId | string | The settlement batch the payment landed in. The same value as batchReference on the settlement, so a payment can be tied to the line on your processing statement. Blank until the batch closes. |
createdAt, updatedAt | timestamp | Record timestamps. |
Card-machine payments wait for the customer#
The request is open while the customer pays
A payment created with a deviceId pushes the amount to the terminal and then waits — polling the terminal for up to two minutes — and answers only when the interaction is over. There is no interim "sent to the terminal" response and nothing to poll for while the customer is deciding: the HTTP answer is the outcome. Give your HTTP client a timeout comfortably above two minutes, and keep the Idempotency-Key so a dropped connection replays the same answer rather than ringing the sale twice.
| Status | When | What to do |
|---|---|---|
| 201 | An online payment — token or paymentInstrumentId — that the processor answered during the request, including a decline. Or a terminal sale the customer completed. | Read data.status. It is succeeded, captured, authorized, failed, or — for a bank debit — pending. On failed, failureCode and failureMessage say why. |
| 402 | A terminal sale that did not happen: declined at the terminal, cancelled by the customer or the till, a card that would not read, a terminal that was busy or offline. status is false and the payment record — failed or canceled — is still under data. | Treat it as a decline. Show message to your staff, branch on data.failureCode if you need to, and take the sale again; nothing was collected. |
| 409 | The processor refused the sale as a duplicate of a recent payment on the same card for the same amount. The record exists as failed with failureCode: "DUPLICATE". | Wait for the window to pass, change the amount, or resend with allowDuplicates: true if your account permits it. |
| 504 | Nobody presented a card in two minutes, or the processor did not answer in time. The request was cancelled at the terminal and the record is unknown (or pending, for an online payment). data carries { _id, reference, status }. | Do not retry with a new key. Poll GET /payments/{id}: a tap that landed in that same moment is recovered within minutes, and the outcome also arrives by webhook. |
{
"status": true,
"message": "Payment taken on the terminal.",
"data": {
"_id": "66f1c1b8a2b7e10c9d4a3f5c",
"reference": "PAY-000043",
"status": "succeeded",
"source": "terminal",
"amountMinor": 1260,
"tipAmountMinor": 210,
"currency": "USD",
"deviceId": "66f0a1c4e2b7d9a3f5c81b02",
"paymentInstrumentId": null,
"instrument": { "brand": "MASTERCARD", "last4": "0027", "cardType": "DEBIT" },
"cardPresent": { "entryMode": "CONTACTLESS", /* EMV block */ },
"succeededAt": "2026-08-28T09:31:19.404Z"
}
}
// Asked for 1050. Took 1260, because the cardholder tipped 210.{
"status": false,
"message": "The customer cancelled the sale on the terminal.",
"data": {
"_id": "66f1c1b8a2b7e10c9d4a3f5d",
"reference": "PAY-000044",
"status": "canceled",
"failureCode": "TERMINAL_CANCELLED",
"failureMessage": "The customer cancelled the sale on the terminal.",
"amountMinor": 1050,
"deviceId": "66f0a1c4e2b7d9a3f5c81b02"
}
}
// Nothing was collected. Ring the sale again when the customer is ready.{
"status": false,
"message": "The terminal waited for a card and nobody presented one. Do not retry it — poll PAY-000045…",
"data": { "_id": "66f1c1b8a2b7e10c9d4a3f5e", "reference": "PAY-000045", "status": "unknown" }
}
// Poll GET /api/v1/payments/{id}. A tap in that same moment resolves it within minutes;
// a payment still unknown after that needs a person — open a ticket with the reference.A terminal computes its own tip and surcharge from the prompts configured on it, so tipAmountMinor and buyerCharge are both a 400 alongside a deviceId. Read the final figures off the payment — amountMinor, capturedAmountMinor, tipAmountMinor — never off the number you sent. To abandon a sale the terminal is still prompting for, call POST /api/v1/devices/{id}/cancel; the open create request then answers 402 with TERMINAL_CANCELLED.
POST
/api/v1/payments/{id}/capture
Capture a payment that was created with intent: "authorization". Requires an Idempotency-Key. A hold lasts roughly seven days — expiresAt says when — and capturing one that has expired, or a payment in any status other than authorized, is a 409. A confirmed capture answers in the same call with status: "captured" and capturedAt set; there is nothing further to wait for.
| Field | Type | Required | Description |
|---|---|---|---|
amountMinor | integer | Optional | Capture less than was authorized — a partial capture, for a shipment that went out short. Omit to capture the full authorized amount. More than the authorization is a 400. |
POST
/api/v1/payments/{id}/void
Release an authorization you are not going to capture, so the hold on the cardholder's account falls away instead of aging out. Requires an Idempotency-Key. Only a payment in authorized can be voided: voiding something already captured is a 409 — captured money comes back as a refund, not as a void. A void is immediate: the answer is status: "voided" with voidedAt set. The hold itself can take the issuer a few days to drop from the cardholder's statement, but nothing about the payment is pending.
POST
/api/v1/payments/{id}/refunds
Refund a captured payment in full or in part. Requires an Idempotency-Key. A payment may be refunded many times until its headroom is gone. A payment in a status that cannot be refunded is a 409.
A disputed payment cannot be refunded
Once a chargeback opens, the amount has already been debited from you. Refunding on top would take the money from you a second time, so a refund against a disputed payment is refused with a 409. If you do not intend to contest the dispute, accept it — that concedes the money once.
| Field | Type | Required | Description |
|---|---|---|---|
amountMinor | integer | Optional | Minor units to return. Omit for a full refund of whatever headroom remains. |
reason | string | Optional | Why the money is going back. Stored on the refund and shown in the dashboard and exports. |
The answer is 201 with the payment, its refunds[] now carrying the new row. A card refund the processor accepts comes back with the refund already succeeded — and refund.succeeded fires at once — while a bank-account refund stays pending until the bank settles it, days later. A refund the processor refuses is failed, with failureCode and failureMessage on the refund row.
Refund headroom
The refundable balance of a payment is reserved the instant a refund is requested, not when it settles. Two refund requests that arrive at the same moment therefore cannot both succeed against the same money: the first reserves what it needs, and the second sees only what is left. If it asks for more than that, it gets a 400.
Reservations are not permanent. If the bank later refuses a refund, that refund releases its reservation and the payment's headroom goes back up — the money becomes refundable again, and a fresh refund request will be accepted. This is why the honest source of truth for “can I still refund this?” is the payment's current refundedAmountMinor, read at the moment you ask, rather than a figure you computed and cached earlier.
POST
/api/v1/payments/{id}/sync
Not a polling endpoint
sync re-reads a payment from the payment processor and updates our record. It exists for reconciliation — an end-of-day sweep, or a payment that looks stuck after a 502 — and it is the recovery path for a create that timed out: a payment with no processor reference is looked up by the order we sent, so a charge that landed after we stopped waiting is adopted rather than repeated. It is not a substitute for webhooks. Polling it in a loop will get you rate limited long before it gets you an answer, and the webhook would have arrived first anyway. When the processor holds an older version than we do the message says so and nothing changes.
POST
/api/v1/payments/list
Filtered, paginated list of payments, newest first. See Pagination for the body shape. No Idempotency-Key.
| Field | Type | Required | Description |
|---|---|---|---|
status | string | array | Optional | One status, or an array of them. Unknown values narrow to nothing rather than erroring. |
method | enum | Optional | card, bank, apple_pay or google_pay. |
buyerId | string | Optional | Payments attached to one customer. A malformed id is a 400. |
disputed | boolean | Optional | Only disputed, or only undisputed, payments. |
createdFrom, createdTo | timestamp | Optional | Bound createdAt. Pin these when exporting so the result set stops moving under you. |
amountMin, amountMax | integer | Optional | Bound amountMinor, inclusive. |
search | string | Optional | Matches the reference and description (case-insensitive substring), and the exact authorizationCode or card last4. |
GET
/api/v1/payments/{id}
Retrieve one payment — the object above, including its captured amount, tip, refunds and refunded total. A payment belonging to another merchant is a 404.
Payment statuses#
A payment's status field is the one value your system should key off. It is stable, enumerated and safe to branch on — unlike the human-readable message of an error. It is deliberately smaller than the processor's own vocabulary: you asked for a charge and you want to know whether it worked. The processor's word is on the payment as nmiCondition for the support conversation, and nothing else.
| Status | What causes it |
|---|---|
pending | Created but not resolved. Either the processor has not answered yet, or the rail is slow: a bank debit stays pending until the bank settles it (then succeeded) or returns it (then returned), which takes days. Not a failure, and never to be rendered as one. |
authorized | An authorization intent succeeded, online or on a terminal. Funds are held on the cardholder's account but nothing has been taken. Capture or void it before expiresAt. |
captured | An authorization has been captured. The money is committed and on its way into a settlement. |
succeeded | A sale completed end to end — authorized and captured in one step, or a bank debit the bank has settled. Final, until a refund or dispute changes it. |
failed | The issuer declined, the processor refused the request, or a terminal could not take the sale. failureCode and failureMessage say why. Final: create a new payment to try again — do not retry the failed one. |
canceled | A terminal sale that never completed: the customer cancelled on the machine, the till cancelled it, or it was cancelled through POST /devices/{id}/cancel before a card was presented. No money moved. Final. |
voided | An uncaptured authorization was deliberately released by a void call. No money moved. Final. |
expired | An uncaptured hold that aged out on its own — roughly seven days. Distinct from voided, which somebody chose, and from canceled, which never got as far as a hold. It arrives as payment.expired because nothing upstream announces it. |
returned | A bank debit that the bank paid and then took back — days later, after you had shipped. The money moved and then came back, which is not the same as a decline; bankReturn carries the reason. |
refunded | The full captured amount has been returned. No headroom remains. |
partially_refunded | Some of the captured amount has been returned and some headroom remains. Further refunds are possible up to that headroom. |
disputed | The cardholder has raised a chargeback. The amount is withdrawn and a respondBy deadline is running. A dispute that is won puts the payment back. See Disputes. |
unknown | Nobody can yet say what happened: the processor answered that it cannot tell, or a terminal sale was cancelled at our two-minute timeout in the same moment a card may have been tapped. Different from pending, which is "ask again shortly". A poller keeps looking the payment up and resolves it when the processor can; one still unknown after that needs a person — open a support ticket with the payment's reference. |
Statuses move forwards, not backwards
Events can arrive out of order under retry. Guard your state machine: if you have already recorded refunded, a late-arriving payment.captured for the same payment should be ignored, not replayed. Compare against the payment's current status rather than assuming the event you are holding is the newest thing that happened. The one deliberate exception is expired: it is inferred by us rather than reported by the processor, so a capture that lands minutes before the deadline can still overwrite it.
Customers & stored instruments#
A customer — a buyer, in the language of the API — is a person or business you can attach payments, stored cards and subscriptions to. Creating one is optional for a single sale and effectively mandatory for anything recurring.
/api/v1/customers
/api/v1/customers/list
/api/v1/customers/{id}
/api/v1/customers/{id}
/api/v1/customers/{id}/payment-methods/{instrumentId}/remove
The customer body takes the same shape as the inline buyer object documented under Payments: email, names, business name, phone, and a nested address and shippingAddress with the same length limits. customerReference carries your own identifier so you can find a buyer by the id your system already uses. Creating a customer is a purely local record — nothing is sent to the processor until a payment stores a card against it — so none of the customer endpoints require an Idempotency-Key; creating the same customer twice costs you a duplicate row, not money. The exception is customerReference: it is unique within your account, so repeating one is refused with a 409 rather than quietly creating a second record under the same identifier. A create must carry at least one identifying field — a completely empty customer is a 400.
The customer object is { _id, customerReference, email, phone, firstName, lastName, businessName, address, shippingAddress, stats, enabled, tags, createdAt, updatedAt }. stats is maintained for you — payment counts and totals — and is not writable.
Stored instruments#
A payment instrument is a card or bank account held in the vault on the customer's behalf that you can charge again by id. There is exactly one way one comes into existence: a payment made with storeInstrument: true. Tokenize the card in the hosted fields, charge it once with that flag — a $0 or small first charge is the usual pattern — and the paymentInstrumentId that comes back on the payment is reusable from then on.
The instruments themselves are read back from the customer: GET /api/v1/customers/{id} returns data.paymentMethods, an array whose _id is the value you pass as paymentInstrumentId on a later payment or subscription. The payment object carries only a display summary of the instrument — brand, last four, expiry, card type — never a vault identifier you could take elsewhere.
| Field | Type | Description |
|---|---|---|
_id | string | What you pass as paymentInstrumentId. |
type | enum | PAYMENT_CARD, BANK_ACCOUNT, APPLE_PAY or GOOGLE_PAY. |
brand | enum | The card brand, in the same enum as instrument.brand on a payment. Blank on a bank account. |
cardType | enum | CREDIT, DEBIT, PREPAID, CHARGE, DEFERRED_DEBIT or UNKNOWN. What a surcharge is checked against. |
last4 | string | Last four of the card or account number. |
expirationMonth, expirationYear | integer | Card expiry. Kept current by the account updater where the issuer supports it — see instrument.updated. |
name | string | The name on the instrument, when one was collected. |
bankAccountType, bankRoutingLast4 | string | Bank accounts only: checking or savings, and the last four of the routing number. Blank on a card. |
enabled | boolean | false once the instrument can no longer be charged — removed by you, or disabled after the issuer said the account is closed or the card must not be retried. |
disabledMessage | string | Our wording for why it was disabled, safe to show to staff. Never the issuer's own text. |
storedForFutureUse | boolean | Whether the cardholder agreed to the card being kept — the stored-credential flag the networks require on later charges. |
createdAt | timestamp | When it was stored. |
POST /api/v1/customers/{id}/payment-methods/{instrumentId}/remove deletes the entry from the processor's vault and disables our row rather than deleting it — a two-year-old receipt still has to be able to say which card was used. A disabled instrument is refused by POST /payments and by the subscription biller with a message that names the reason.
There is no endpoint that accepts a card number, because there is no code path in which raw card data reaches your servers. Charging a stored instrument is the same POST /api/v1/payments call you already know, with paymentInstrumentId in place of token. It still needs an Idempotency-Key, and it still returns 201.
Payment links#
A payment link is a hosted checkout page you can send by email, print as a QR code or paste into a message. It needs no front-end work from you at all: create the link, share the URL, and collect the resulting payment events. The page tokenizes with the same hosted fields your own checkout would, offers whichever of card, bank account, Apple Pay and Google Pay the link's methods allow, and its payments arrive with source: "checkout" and the link's _id in paymentLinkId.
POST
/api/v1/payment_links
| Field | Type | Required | Description |
|---|---|---|---|
title | string | Required | Up to 120 characters. The buyer sees this. It is the heading on the checkout page, so write it for a customer, not for your database. |
description | string | Optional | Up to 500 characters, shown to the buyer beneath the title. |
internalName | string | Optional | Up to 120 characters. Never shown to a buyer. Use it for the reference your team searches by. |
amountType | enum | Optional | FIXED — you set the price. VARIABLE — the buyer types an amount within bounds. Upper case, and it defaults to FIXED. |
amountMinor | integer | Fixed only | The price, in minor units. Required when amountType is FIXED; rejected otherwise. |
minAmountMinor | integer | Variable only | Floor for a buyer-entered amount. Rejected on a fixed link. |
maxAmountMinor | integer | Variable only | Ceiling for a buyer-entered amount. Rejected on a fixed link. |
currency | enum | Optional | USD or CAD. Defaults to USD. |
isMultipleUse | boolean | Optional | Defaults to false. A single-use link is spent by its first successful payment. |
intent | enum | Optional | sale or authorization, exactly as on a payment. |
methods | array | Optional | Payment methods offered on the page — card, bank, apple_pay, google_pay. At least one. Defaults to ["card"]. Apple Pay renders only where the domain is registered for it; a token of a kind the link does not allow is refused before anything is charged. |
termsUrl | string | Required | An https:// URL to your terms — plain http is a 400. Required on every link: a buyer paying a stranger's page is entitled to read what they are agreeing to before they pay. |
statementDescriptor | string | Optional | Up to 22 characters, as on a payment. |
expiresAt | timestamp | Optional | After this moment the page stops accepting payments and says so. |
tags | object | Optional | Up to 50 pairs; keys up to 40 characters, values up to 500. |
The rules, stated plainly#
- A
FIXEDlink must carryamountMinorand must not carryminAmountMinorormaxAmountMinor. - A
VARIABLElink is the exact reverse: bounds are allowed, a fixedamountMinoris not. With nomaxAmountMinorset, the buyer's amount is still capped by your account's per-transaction ceiling. - Breaking either rule is a
400at creation, not a surprise at checkout. - The price of a fixed link is read from our record of the link, never from anything the browser submits. A buyer who edits the page and posts a different amount pays the price you set.
- A single-use link is spent by its first successful payment. Anyone who opens it afterwards is told the link has already been used — they do not get a blank page, an error, or a second chance to pay.
termsUrlis required on every link, fixed or variable, single-use or multi-use.
Managing a link#
/api/v1/payment_links/{id}
/api/v1/payment_links/{id}/activate
/api/v1/payment_links/{id}/deactivate
/api/v1/payment_links/list
/api/v1/payment_links/{id}
A link's state is one of four upper-case values: ACTIVE — payable; COMPLETED — a single-use link spent by its first successful payment; EXPIRED — past its expiresAt; DEACTIVATED — taken out of service by you. Only an ACTIVE link accepts a payment, and expiry is computed at the moment the page is read rather than trusted from a stored flag. Reactivating a COMPLETED or EXPIRED link is a 409 — create a new link instead.
Deactivating takes a link out of service without deleting it; the URL keeps working as a page but stops accepting payments, and activating puts it back. PATCH is deliberately narrow — title, description, internalName, termsUrl, statementDescriptor, expiresAt and tags. The price and the amount type cannot be edited on a live link; a buyer who has been sent one must not have the number change underneath them. None of these require an Idempotency-Key.
{
"title": "Winter service — 12 month plan",
"internalName": "WSVC-2026-Q1",
"amountType": "FIXED",
"amountMinor": 18000,
"currency": "USD",
"isMultipleUse": false,
"termsUrl": "https://acme.example/terms",
"statementDescriptor": "ACME SERVICE"
}{
"title": "Pay your balance",
"amountType": "VARIABLE",
"minAmountMinor": 500,
"maxAmountMinor": 500000,
"currency": "CAD",
"isMultipleUse": true,
"termsUrl": "https://acme.example/terms"
}
// Adding "amountMinor" here would be a 400.Subscriptions#
A subscription is a standing instruction to charge a card we already hold, on a schedule, until somebody stops it. It is a mandate — a thing the cardholder agreed to — and the API is shaped to keep it honest.
POST
/api/v1/subscriptions
| Field | Type | Required | Description |
|---|---|---|---|
paymentInstrumentId | string | Required | The stored card the mandate will charge. A single-use token is not accepted here — see the note below. |
buyerId | string | One of two | The customer the mandate belongs to. Send this or customerReference; sending neither is a 400. Unlike a payment, a subscription cannot create a customer on the fly. |
customerReference | string | One of two | Your own identifier for the buyer, if you would rather not carry ours. Up to 120 characters. |
amountMinor | integer | Required | The amount to collect each period, in minor units. |
currency | enum | Optional | USD or CAD. Defaults to USD. |
interval | object | Required | A unit and a count, not a named enum: { "unit": "month", "count": 1 }. unit is day, week, month or year and is required; count is a positive integer that defaults to 1. That is how you express “every two months” or “every five weeks” without a lookup table. |
billingCycleDay | integer | Optional | 1–31. The day of the period on which to collect. Meaningful only when interval.unit is month or year — “bill on the 15th” is a statement about months. Months shorter than the chosen day collect on their last day. |
startsAt | timestamp | Optional | When the schedule begins. Defaults to now. |
trialEndsAt | timestamp | Optional | Nothing is collected before this moment. The first collection lands on the first scheduled date after it. |
totalBillingPeriods | integer | Optional | Stop after this many successful collections. Omit for open-ended. |
statementDescriptor | string | Optional | Up to 22 characters, on every collection. Recurring charges with an unrecognizable descriptor generate disputes for years. |
description | string | Optional | Up to 500 characters. Internal description of what is being billed. |
nickname | string | Optional | Up to 120 characters. A short label for your own dashboards. |
acceptedTerms | boolean | Optional | Records that the cardholder accepted the recurring terms. |
termsText | string | Optional | Up to 2000 characters. Store the exact wording that was shown — it is the evidence that the mandate was agreed to. |
tags | object | Optional | Up to 50 pairs; keys up to 40 characters, values up to 500. |
There is no card form here — and no charge at creation
A subscription is a standing instruction to charge a credential we already hold. A single-use token is, by definition, not one, so paymentInstrumentId is required and there is no card-collection step inside subscription creation. Store the card first — by charging with storeInstrument: true, or through the hosted card form — then create the mandate.
Creating a subscription charges nothing. It writes the mandate; the biller collects on schedule from that point on. If you need money on day one, take a payment and create the subscription alongside it.
The mandate's provenance comes from the request
The IP address and user-agent recorded against a mandate are taken from the HTTP request that created it. They are never read from the body, because a field you can set is not evidence of anything.
Subscription statuses#
| Status | What it means |
|---|---|
not_started | Created with a startsAt in the future. Nothing collects until that moment. |
trialing | Inside the trial window. The mandate exists; nothing is collected before trialEndsAt. |
active | Collecting on schedule. The normal state of a healthy subscription. |
past_due | The last collection failed and the dunning ladder is running. Still live — keep serving the customer. |
paused | Collection suspended — by a pause call, or by the issuer: when a collection is answered with "stop all recurring charges to this card" the subscription is paused rather than run through dunning, and the subscription.paused event carries pausedBy: "issuer" with the failureCode. Resumes by hand, or on its own at resumesAt. |
canceled | Ended — by you, by dunning running out, or by the platform. canceledVia says which. Terminal. |
completed | Reached its totalBillingPeriods and finished normally. Terminal. |
Each successful collection is an ordinary payment: it arrives as payment.succeeded carrying a subscriptionId, not as a subscription event. The subscription.* events describe the mandate; the payment.* events describe the money. Collections are flagged to the card networks as recurring, stored-credential charges automatically; there is nothing to set.
Updating a subscription#
/api/v1/subscriptions/{id}
The update surface is deliberately narrow. You may change:
amountMinor— applies from the next period; a period already in progress is never re-pricedbillingCycleDay— but only before the first collection; once a period has billed, changing it is a409paymentInstrumentId— point the mandate at a different stored card, which is what a customer whose card expired actually needsstatementDescriptor,description,nicknametags
You may not change interval, startsAt or trialEndsAt. Every one of those silently re-dates a mandate the cardholder has already agreed to: lengthening a trial, shifting a start, or turning a monthly agreement into a weekly one changes what was consented to without anybody being asked. To change a schedule, cancel the subscription and create a new one — which is also the only version of that change you can describe to the customer honestly.
Lifecycle#
/api/v1/subscriptions/{id}/pause
/api/v1/subscriptions/{id}/resume
/api/v1/subscriptions/{id}/cancel
/api/v1/subscriptions/list
/api/v1/subscriptions/{id}
Pausing stops collection without ending the mandate; pass resumesAt to have it wake on its own, or omit it and resume by hand. Canceling is final, and it defaults to atPeriodEnd: true — the customer has already paid through the end of the current period, so service runs to the end of it unless you explicitly send atPeriodEnd: false. None of these take an Idempotency-Key; pausing an already-paused subscription is not an event worth protecting against.
The dunning ladder#
When a scheduled collection fails — an expired card, insufficient funds, an issuer having a bad day — the subscription does not simply stop. It enters dunning (with one exception: an issuer that answers "stop recurring charges to this card" — failureCode 261 or 262 — pauses the subscription outright, because retrying would only produce the same answer, and disables the card on 261):
- The collection fails, the subscription moves to
past_due, andsubscription.payment_failedis emitted. The subscription is still live — keep serving the customer. - The charge is retried on days 1, 3, 8 and 15 after the first failure. Each failed attempt emits
subscription.payment_failedagain, so a single billing period can produce several of these events. - When the last attempt has been made,
subscription.dunning_exhaustedis emitted. Its payload carriescancelsAt— 19 days after the first failure — because a charge submitted on day 15 can still settle on day 17, so the mandate is not killed the instant the ladder runs out. - If nothing has collected by
cancelsAt, the subscription is canceled automatically andsubscription.canceledfollows. That is involuntary churn, and it is worth counting separately from a customer who chose to leave.
Treat subscription.payment_failed as “tell the customer to fix their card” and subscription.dunning_exhausted as “stop providing the service”. Because a failed period emits several of the former, deduplicate your customer emails on something other than the event count, or a customer with one bad card will receive four notices over two weeks. The window between the first failure and cancelsAt is the whole opportunity to save the mandate; after it, winning the customer back costs a fresh acquisition.
Devices#
A device is a card machine: a countertop PIN pad, a handheld smart terminal, an unattended kiosk module, or a phone running Tap to Pay. You register it once by typing the code the terminal shows on its screen, and from the moment it reports itself connected you send it amounts to collect with POST /api/v1/payments and a deviceId. There is no serial-number form, no model to pick, and no separate activation step: a registered terminal is a working terminal.
Phones running Tap to Pay are devices too, with kind: "phone". They are enrolled from the POS app on the handset itself, not registered here: the processor's software on the phone reads the card, so only the app on that phone can start the sale. A phone carries no nmiDeviceId or serial number, cannot be given a sale through this API, and cannot be cancelled from it. Every device carries kind (terminal or phone), and the list takes ?kind=terminal to hide phones.
GET
/api/v1/devices/models
The hardware catalogue. It is for labels and illustrations, not for registration — the processor tells us what a terminal is when its code is accepted, and the device's modelId then points at one of these entries (or is null for hardware we do not list, in which case make and model still describe it). Read it at build time rather than hard-coding a list you will forget to update. The response is { models: [ … ], connectionStatuses: ["connected", "disconnected", "unknown"] }, each model being { id, label, make, category, description, contactless, printer }.
| id | Label | Category | Contactless | Printer |
|---|---|---|---|---|
LANE_3000 | Ingenico Lane/3000 | Countertop | yes | no |
LANE_5000 | Ingenico Lane/5000 | Countertop | yes | no |
LANE_7000 | Ingenico Lane/7000 | Countertop | yes | no |
LANE_8000 | Ingenico Lane/8000 | Countertop | yes | no |
AXIUM_DX8000 | Ingenico Axium DX8000 | Smart terminal | yes | yes |
AXIUM_RX7000 | Ingenico Axium RX7000 | Smart terminal | yes | yes |
SELF_2000 | Ingenico Self/2000 | Unattended | yes | no |
SELF_5000 | Ingenico Self/5000 | Unattended | yes | no |
VP3350 | ID TECH VP3350 | Mobile | yes | no |
TAP_TO_PAY_IOS | Tap to Pay on iPhone | Tap to Pay | yes | no |
TAP_TO_PAY_ANDROID | Tap to Pay on Android | Tap to Pay | yes | no |
A terminal without a printer can still take the sale; the receipt is emailed or texted from our side, so the flag is informational.
POST
/api/v1/devices
Register a terminal. On the terminal, open its cloud or registration screen and type the code it shows into this call. The code is single-use at the processor — a second submit of the same code is refused — and a terminal that is removed needs a fresh code from its screen to come back. No Idempotency-Key: a retried registration lands on the row it already made.
| Field | Type | Required | Description |
|---|---|---|---|
registrationCode | string | Required | 4 to 12 letters and digits, exactly as the terminal shows it. Anything else is a 400 before the processor is asked. Never a serial number. |
nickname | string | Optional | Up to 60 characters. What staff will call it: “Front counter”, “Van 2”. Stored with us; the name on the processor's side stays whatever was given at registration. |
isDefault | boolean | Optional | Mark this as the account's default terminal. |
tags | object | Optional | Up to 50 pairs; keys up to 40 characters, values up to 500. |
The answer is 201 with the device. Its message says which of two things is true: “Terminal registered and connected. It can take payments now.” or “Terminal registered. It will take payments once it shows as connected.” — read connectionStatus rather than the prose.
The device object
{
"id": "66f0a1c4e2b7d9a3f5c81b02", // yours; use it in every /{id} route and as deviceId on a payment
"nickname": "Front counter",
"make": "Ingenico",
"model": "Lane/3000", // free text, as the processor reports it
"modelId": "LANE_3000", // catalogue id, or null
"modelLabel": "Ingenico Lane/3000",
"serialNumber": "SNLN12AB0042",
"connectionStatus": "connected", // connected | disconnected | unknown — as of syncedAt
"enabled": true, // your switch; false refuses sales, keeps history
"isDefault": false,
"registeredAt": "2026-09-17T10:00:00.000Z",
"lastSeenAt": "2026-09-17T10:00:00.000Z", // last reading that said connected
"syncedAt": "2026-09-17T10:00:00.000Z", // when connectionStatus was read — show its age
"removedAt": null,
"tags": {},
"createdAt": "2026-09-17T10:00:00.000Z",
"updatedAt": "2026-09-17T10:00:00.000Z"
}Render the connection with its age
connectionStatus is true as of syncedAt, not as of now. A green dot with no timestamp next to it is a lie an hour later. unknown means the state has never been read, not that the terminal is offline. Opening a single device re-reads the processor every time; the list does so only when you ask it to.
Managing a device#
/api/v1/devices
/api/v1/devices/{id}
/api/v1/devices/{id}
/api/v1/devices/{id}
/api/v1/devices/{id}/cancel
The fleet is a GET with query parameters — the one list on this API that is not a POST /list, because a till polls it and a cacheable read is the right shape for that. It answers from our mirror by default, so twenty terminals do not cost a processor round trip to render; refresh=true re-reads the processor's device list first, in one call, adopting terminals paired elsewhere and retiring ones removed there. If the processor cannot be reached on a refresh the rows are the stored ones and the response carries a warning saying so.
| Parameter | Type | Default | Description |
|---|---|---|---|
page, limit | integer | 1, 25 | Paging, as everywhere else. limit is clamped to 100. |
search | string | — | Matches nickname, serial number or model, case-insensitively. |
enabled | boolean | — | Filter on your switch. |
connectionStatus | enum | — | connected, disconnected or unknown — the last-known state. |
includeRemoved | boolean | false | Also list terminals removed here or in the processor's own portal (removedAt set). |
refresh | boolean | false | Re-read the processor before answering. |
The response is { devices: [ … ], offline, pagination }. offline is account-wide and ignores your filters on purpose: it counts terminals that are enabled, not removed and not connected — every one of which will refuse a sale while looking perfectly normal on the counter — so a search that narrows them off the page cannot silence the warning about them.
One device is re-read from the processor on every GET, because "can I take a payment on this right now" is the question the read exists to answer and only the processor knows. If the processor no longer has the terminal, the row is marked removed and returned with removedAt set.
PATCH takes any of nickname, enabled and tags — at least one, or it is a 400 — and touches nothing at the processor, so it works with the terminal unplugged and it works while your processing is paused. enabled: false is the off switch: the terminal refuses payments until it is switched on again, nothing is deleted, and history is kept. Patching a removed terminal is a 409.
DELETE removes the terminal at the processor and marks the row removed. Idempotent, 200 with the device. To use the hardware again, register it with a new code from its screen.
cancel aborts a sale, it does not retire a terminal
POST /api/v1/devices/{id}/cancel stops whatever the terminal is currently prompting for and returns it to its idle screen — the customer walked off, the cashier rang the wrong amount. The answer is 200 with { device, requestId, requestStatus: "cancelledByApi" }; when nothing was in progress requestId is empty and the message says the terminal had nothing to cancel. The POST /payments call that was waiting on that terminal answers 402 with failureCode: "TERMINAL_CANCELLED" and the payment is canceled. It is not a lifecycle action: to take a terminal out of service, PATCH it enabled: false. In the dashboard the same action is the Return to idle screen button on a terminal's page.
Taking a sale on a terminal#
A sale is POST /api/v1/payments with the device's id as deviceId, an amount, and an Idempotency-Key. The request pushes the amount to the machine and stays open — up to two minutes — until the customer has paid, cancelled, or walked away, and the HTTP answer is the outcome: 201, 402 or 504. intent: "authorization" works on a terminal too and answers authorized. The payment comes back with source: "terminal", deviceId, and a cardPresent block carrying the entry mode and the EMV data your processing agreement obliges you to be able to print.
| failureCode | Payment status | Meaning |
|---|---|---|
| — | succeeded / authorized | The customer paid, or a hold was placed. 201. |
issuer code (200, 202, …) | failed | The issuer declined at the terminal. Same codes as an online decline. 402. |
TERMINAL_CANCELLED | canceled | The customer cancelled on the machine, the till cancelled, or /cancel was called. 402. |
TERMINAL_BAD_CARD_READ | failed | The card would not read. Ask the customer to try again or use another card. 402. |
TERMINAL_BUSY | failed | The terminal was already in a sale. Cancel it, or wait. 402. |
TERMINAL_DISCONNECTED | failed | The terminal is not connected. Check power and network, then try again. 402. |
TERMINAL_TIMEOUT | failed / unknown | Nobody presented a card. When the terminal itself timed out the payment is failed (402); when we stopped waiting and cancelled the request it is unknown (504) — poll it, because a tap in that same moment is recovered. |
TERMINAL_FAILED | failed | The terminal reported a failure it could not classify. 402. |
Tips, surcharges, signatures and receipts live on the terminal
How a terminal behaves — whether it prompts for a tip and with which presets, whether it surcharges and at what rate, when it asks for a signature, whether it offers a receipt, what its idle screen shows — is configured on the device itself or in its own management portal, not through this API. That is why tipAmountMinor and buyerCharge are refused alongside a deviceId: the machine computes both. Read the final figures off the payment — amountMinor, capturedAmountMinor, tipAmountMinor — never off the number you sent. Reconciliation built on the requested amount will drift by exactly the tips your staff earn, which is the most awkward possible way to discover this.
Check the connection before you blame the decline
A terminal takes a sale only when it is powered on, online and registered. Anything less and the request comes back 402 with TERMINAL_DISCONNECTED — that is a certainty, not a risk. The dashboard's Terminals screen shows each machine's connection alongside how old that reading is, and opening a terminal refreshes it. When a card machine starts refusing everything, the order to check is enabled first, connection second, and the card third.
Disputes#
A dispute is a cardholder telling their bank they should not have been charged. The amount and a dispute fee are taken back from you at once, the payment moves to disputed, and you get a window in which to answer. The case itself is argued at the acquirer, by a person, with the evidence you assemble here: you upload files and write an account of the sale, we forward them, and the verdict is recorded against the dispute when it comes. There is nothing to "submit" — everything you attach while the dispute is open is the response.
/api/v1/disputes/list
/api/v1/disputes/{id}
/api/v1/disputes/{id}/evidence
/api/v1/disputes/{id}/evidence/{evidenceId}
/api/v1/disputes/{id}/evidence/{evidenceId}
/api/v1/disputes/{id}/note
/api/v1/disputes/{id}/accept
The list body is { page, limit, state?, showAll?, from?, to? }. With no state and no showAll it returns only the disputes that still need a response — received and under_review — soonest respondBy first, because a screen that opens on everything ever filed buries the three due this week under two years of resolved ones. from/to bound receivedAt. The response is { disputes, needsResponse, pagination }, where needsResponse is the count of open disputes regardless of the page — the number that belongs in a navigation badge. The detail adds a payment summary and the payment's refunds[].
| Field | Type | Description |
|---|---|---|
_id | string | The dispute's identifier. |
paymentId, paymentReference | string | The payment in question. paymentId is null when the notice could not be matched to one of your payments. |
state | enum | received — filed, nobody has acted. under_review — you have added evidence or a note. accepted — you conceded; final. won / lost — the acquirer decided. |
reasonCode, reason | string | The scheme's reason code and its plain-language meaning. |
amountMinor, currency | integer, enum | The disputed amount. |
feeMinor | integer | The dispute fee charged to you, whatever the outcome. |
receivedAt | timestamp | When the chargeback was filed. |
respondBy | timestamp | receivedAt + 7 days. See below. |
daysRemaining | integer | Days until respondBy, computed at read time — negative once it has passed. |
overdue | boolean | Open and past respondBy. |
customerName, cardLast4 | string | From the acquirer's notice, to help you find the sale. |
matchConfidence | enum | How the notice was matched to a payment: exact, inferred or none. |
evidence | array | What you have uploaded: [{ _id, name, mimeType, size, uploadedAt }]. A stored file is a stored file; there is no per-file acceptance state to watch. |
merchantNote | string | Your account of the sale, from POST /{id}/note. |
outcome | object | { decidedAt, note } once the acquirer has decided, otherwise null. |
acceptedAt | timestamp | When you accepted it, if you did. |
evidenceLimits | object | { maxFiles, maxFileBytes, maxTotalBytes, allowedTypes } — the upload limits, sent with every dispute so a client can enforce them before a merchant spends five minutes assembling a defence that is rejected on size. |
canRespond | boolean | Whether evidence, a note or an acceptance is still possible — true while the state is received or under_review. |
createdAt | timestamp | Record timestamp. |
The respondBy deadline#
An unanswered dispute is forfeited, not judged
Every dispute carries a respondBy timestamp — seven days from receivedAt — and the clock starts the moment the dispute is filed, not when you read the webhook, not when your support team gets to it. If nothing has been attached by that time there is nothing to forward, and the dispute is lost by default. Nobody weighs your case; there is no case.
Build an alert on dispute.created that a human sees the same day. As the deadline approaches, dispute.updated arrives with daysRemaining and a message, and once it passes, with overdue: true. The most expensive disputes in any account are the ones nobody looked at.
Evidence and your account of the sale#
Upload the documents that show the charge was legitimate: the receipt, the delivery confirmation, the signed terms, the correspondence. Upload each file with POST /{id}/evidence, remove a mistake with DELETE /{id}/evidence/{evidenceId}, and read one back with GET /{id}/evidence/{evidenceId}, which streams the file as an attachment. All three are possible only while canRespond is true.
The limits are 10 files per dispute, 5 MB per file and 25 MB in total, and the only accepted types are PDF, JPEG and PNG. The evidence endpoint takes the file as a raw request body rather than a JSON payload: set Content-Type to application/pdf, image/jpeg or image/png, and pass the file name in an X-File-Name header (percent-encoded) or a fileName query parameter. The answer is 201 with the updated dispute. A signature-required key signs the file bytes exactly as it would a JSON body.
curl -X POST https://api.wickerpay.com/api/v1/disputes/66f2…/evidence \
-H "Authorization: Bearer $WICKER_API_KEY" \
-H "Content-Type: application/pdf" \
-H "X-File-Name: receipt%201042.pdf" \
--data-binary @receipt-1042.pdfFiles are the exhibits, not the case. POST /{id}/note carries your written account — { "note" }, at least a sentence and up to 4,000 characters — and it is what the reviewer at the acquirer reads and decides on. State plainly what was bought, when it was delivered and what the attachments show. If you already refunded the cardholder, say so and name the refund's reference: it is often decisive on its own. Posting a note again replaces the previous one. Adding a note or a file moves the dispute to under_review. The dashboard's Disputes screen asks for the same explanation in a box labeled Your response.
POST /{id}/accept concedes the dispute without a fight. That is the right call when the cardholder is plainly correct: it settles the matter at once and stops you spending time on a case you would lose. The body is { "note" }, optional, up to 1,000 characters, recorded against the dispute. It is final: the disputed amount and the fee leave your open settlement as a chargeback entry, and in the dashboard the button — Accept liability — says the thing worth knowing before you press it: an accepted dispute still counts toward your chargeback ratio.
When the acquirer decides, the dispute moves to won or lost and the matching dispute.won or dispute.lost event fires with decidedAt and the reviewer's note. A win restores the payment to the status it had before the dispute; a loss posts the chargeback to your settlement ledger, if accepting it had not already.
Settlements & payouts#
/api/v1/settlements/list
/api/v1/settlements/{id}
A settlement is one processor batch, turned into a ledger: every payment the batch captured, every refund and bank return it carried, every chargeback posted against you, and the fees on each line, reduced to a single net figure. There is one per batch, batches close roughly daily, and each one is the object your bank statement will eventually agree with. Read-only: you cannot create, edit or approve one, and there is no “pay me now” — the payout of a settlement's net is recorded by the platform once the money has moved, and arrives as an event.
GROSS # totals.grossMinor — everything captured in the batch
− REFUNDS # totals.refundsMinor — refunds and bank returns, as a positive number
− CHARGEBACKS # totals.chargebacksMinor — disputes lost or accepted, as a positive number
− FEES # totals.feesMinor — processing, per-transaction, dispute and other fees
= NET # totals.netMinor — the sum of every entry's netMinor; what is paid outThe list body is { page, limit, status?, payoutState?, from?, to? } — status is open, closed or paid, payoutState is unpaid, held, paid or failed, and from/to bound batchDate. Rows come newest batch first, without their entries; GET /{id} returns the settlement with every entry, never truncated.
| Field | Type | Description |
|---|---|---|
_id | string | The settlement's identifier. |
batchReference | string | The processor's batch id — the number on your processing statement, and the same value each payment in the batch carries as nmiBatchId. A settlement that holds only a day's fee deductions is fees-YYYY-MM-DD instead. |
batchDate | timestamp | The day the batch belongs to. |
status | enum | open — still collecting entries. closed — the batch has closed and the net is fixed. paid — the net has been sent. |
currency | enum | USD or CAD. A settlement is single-currency. |
totals | object | { grossMinor, refundsMinor, feesMinor, chargebacksMinor, netMinor, count }. refundsMinor and chargebacksMinor are positive numbers that are subtracted; count is the number of entries. |
payout | object | { state, paidAt, failedAt, reference, note }. state is unpaid (closed, awaiting transfer), held (the platform has placed a hold on your payouts; the batch still closes and the ledger is still yours to read), paid (sent — reference is the transfer reference), or failed (the transfer did not go through — usually a bank-detail problem; note says what). |
closedAt, createdAt | timestamp | When the batch closed, and when the record was made. |
entries | array | Detail only. [{ reference, kind, paymentId, refundId, disputeId, label, periodKey, grossMinor, feeMinor, netMinor, settledAt }] — see below. |
| kind | What it is | Sign |
|---|---|---|
sale | A captured payment. paymentId names it; reference is its PAY- reference. | grossMinor positive, feeMinor the processing fee, netMinor the difference. |
refund | A refund that settled. refundId names it. | grossMinor negative. |
return | A bank debit the bank took back after paying it. | grossMinor negative, plus any return fee. |
chargeback | A dispute lost or accepted. disputeId names it. | grossMinor negative, feeMinor the dispute fee. |
fee | A standalone charge — a monthly or per-event fee not tied to one payment. label says which; periodKey which period it covers. | grossMinor is 0; feeMinor is the charge. |
A batch with more refunds and chargebacks than takings produces a negative net, which is carried rather than paid out. Payouts are the movement of a settlement's net into your bank account, and their outcomes arrive as events: settlement.created when a batch closes, payout.paid when the transfer has been made, and payout.failed when it has not. A failed payout does not unwind a settlement; the money is still with us and waiting to be sent, and the transfer is recorded again once it goes through.
Reconcile against settlements, not against individual payments. In the dashboard these are the Payouts screen, where the column to reconcile against is Net to bank, and each payment's own settledAt tells you which batch it landed in.
Webhooks#
Webhooks are how anything asynchronous reaches you: a card finally tapped on a terminal, a refund that settled, a dispute that opened, a subscription that failed to collect. If your integration only reads HTTP responses, it will miss most of what happens to your money.
Registering an endpoint#
You register one endpoint per environment in the dashboard — one for sandbox, one for production. There is no API for this on purpose: an API key that could repoint your webhook endpoint would be a stolen key that could redirect your payment notifications. We POST JSON to it. Each environment has its own webhook signing secret, and that secret is not your API key secret: they are separate credentials with separate lifecycles, and mixing them up produces a signature that never verifies.
The screen is Developers → Webhook endpoint, and it edits whichever environment the dashboard is currently set to — check the Sandbox/Live switch before you save, because there is one endpoint per environment and the save writes to the one named at the top. You supply an HTTPS URL, an optional description, an Enabled checkbox that stops delivery without discarding the configuration, and a list of event types. Leaving every type unticked means everything, including event types added after you set the endpoint up; ticking specific ones means exactly those and genuinely no new ones.
The signing secret is shown once, when the endpoint is first created — and again each time you press Rotate secret. Rotation gives you a grace window — 24 hours by default, configurable from none up to 7 days — during which every event is signed with both the new secret and the old one and the header carries both signatures, so your rollout does not have to be simultaneous with ours. That only helps if your verifier accepts any matching v1 value; see below.
| Header | Description |
|---|---|
X-Gateway-Signature | t=<unix seconds>,v1=<hex> — HMAC-SHA256 over <t>.<raw body>, keyed with your webhook signing secret. During a secret rotation the header carries more than one v1=, one per live secret; accept the delivery if any of them matches. |
X-Gateway-Event-Id | The unique id of this event. Deduplicate on it. |
X-Gateway-Timestamp | When the event was emitted, in unix seconds. |
Verifying a delivery#
- Compute the HMAC over the raw request body, exactly as received. Do not let a body-parsing middleware turn it into an object first — re-serializing changes the bytes and the signature will not match.
- Compare with a constant-time comparison. A plain
===on hex strings leaks timing information about how many leading characters were right. - Collect every
v1=in the header, not just one. While a signing secret is being rotated we sign each delivery with both the new secret and the outgoing one and send both signatures, so that your rollout does not need to be simultaneous with ours. A parser that keeps only the first or lastv1— anything built onObject.fromEntries, for example — will reject perfectly good deliveries for the length of every rotation. - Reject anything whose
tis outside a ±5 minute window. That is what stops a captured delivery being replayed at you later. - Respond
2xxquickly. We wait 10 seconds and then give up on that attempt, so acknowledge first and do the work afterwards on a queue. Any2xxis a success regardless of body. - Anything that is not a
2xx— including a timeout — is retried on a jittered exponential schedule: 10 attempts over just under 24 hours, starting 10 seconds later and ending 12 hours apart. After that the delivery is marked exhausted and a human has to look; it is not silently dropped. - Every attempt is listed under Developers → Deliveries with its status code, how long it took, the error if there was one, and your own endpoint's response body — which is usually the answer, because more often than not it contains your server's own stack trace. Deliveries can be filtered by delivered, retrying, exhausted or pending, and any one of them can be queued for redelivery with Replay. A replayed delivery is labeled as one, so it is distinguishable from a retry we made.
- An endpoint that keeps failing — 50 consecutive failed deliveries — is disabled automatically. When that happens we stop sending altogether and you are missing events until somebody re-enables it — possibly for days. The Webhook endpoint screen says so, with the last error, and consecutive failures show there before it gets that far. Nothing else will tell you, so alert on your own side too.
- Deduplicate on
X-Gateway-Event-Id. Delivery is at-least-once: a delivery we retried because your acknowledgment was lost will arrive twice, and both copies are genuine.
Our event shape, not somebody else's
We never forward a raw payload from our processing partner. What arrives at your endpoint is Wicker's own event shape, documented below. That keeps the processor out of your integration contract entirely: if the underlying arrangement ever changes, your webhook handler does not.
const express = require('express');
const crypto = require('node:crypto');
const app = express();
const SIGNING_SECRET = process.env.WICKER_WEBHOOK_SECRET;
const TOLERANCE = 300; // ±5 minutes, in seconds
// express.raw keeps the body as a Buffer. Signing depends on the exact bytes,
// so this route must NOT sit behind express.json().
app.post(
'/webhooks/wicker',
express.raw({ type: 'application/json' }),
async (req, res) => {
const header = req.get('X-Gateway-Signature') || '';
// Not fromEntries: a rotation sends several v1= values and an object
// keeps only the last one.
const fields = header
.split(',')
.map((p) => p.trim().split('='));
const t = Number(fields.find((f) => f[0] === 't')?.[1]);
const raw = req.body.toString('utf8');
// 1. Freshness — symmetric window, our clock may differ from yours.
if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > TOLERANCE) {
return res.status(400).send('stale timestamp');
}
// 2. Signature over "<t>.<raw body>".
const expected = crypto
.createHmac('sha256', SIGNING_SECRET)
.update(`${t}.${raw}`, 'utf8')
.digest();
// Any v1 that matches is a genuine delivery.
const ok = fields
.filter((f) => f[0] === 'v1')
.map((f) => Buffer.from(f[1] || '', 'hex'))
.some((sig) => sig.length === expected.length
&& crypto.timingSafeEqual(sig, expected));
if (!ok) {
return res.status(400).send('bad signature');
}
// 3. Deduplicate — delivery is at-least-once.
const eventId = req.get('X-Gateway-Event-Id');
if (await store.alreadySeen(eventId)) {
return res.status(200).send('ok');
}
await store.markSeen(eventId);
// 4. Acknowledge first, work afterwards.
const event = JSON.parse(raw);
await queue.enqueue(event);
res.status(200).send('ok');
}
);Event types#
The 35 events we emit today, and what each one means. Handle the ones you care about and ignore the rest gracefully — new names are added over time, and an unknown event must not crash your handler. Names are noun.verb in the past tense, and once published they are never renamed or repurposed. A webhook endpoint with no filter set receives all of them, including ones added after you configured it.
| Event | Meaning |
|---|---|
payment.created | A payment record exists. Fires for every payment, whatever happens next — including one the processor declined or one whose create timed out — and is followed at once by the outcome event. An order system that only listens for payment.succeeded never learns an attempt was made. |
payment.authorized | An authorization succeeded. Funds are held; capture or void them before expiresAt. |
payment.captured | An authorization was captured, in full or in part. |
payment.succeeded | The payment completed. For a bank debit this is the day the bank settled it; for a terminal sale, the same fact the 201 told you. |
payment.failed | The payment was declined or could not be completed. failureCode says why. Final. |
payment.voided | An uncaptured authorization was deliberately released. No money moved. |
payment.returned | A bank debit the bank paid and then took back — days later. Handle it, or you will ship goods against money that came back. |
payment.expired | An uncaptured hold aged out — roughly seven days — rather than being released by anyone. Nobody voided it and the order it was taken for has almost certainly not shipped. This event is the only signal you will get. |
| Event | Meaning |
|---|---|
refund.created | A refund was requested. Its amount is now reserved against the payment's headroom. |
refund.succeeded | The money has gone back to the customer. For a card refund this fires in the same moment the refund is created; for a bank refund, when the bank settles it. |
refund.failed | The refund was refused. refund.failureCode says why; the reservation is released and the payment becomes refundable again. |
| Event | Meaning |
|---|---|
dispute.created | A chargeback has been filed. The respondBy clock is already running — alert a human. |
dispute.updated | Something about the dispute changed. A deadline reminder carries daysRemaining and a message, and overdue: true once the deadline has passed; an acceptance carries accepted: true and acceptedBy. |
dispute.won | Decided in your favor. The payment is restored and the withdrawn amount comes back on your next settlement. Carries decidedAt and the reviewer's note. |
dispute.lost | Decided against you, or forfeited by not responding. The amount stays with the cardholder and the chargeback entry posts to your ledger. Carries decidedAt and note. |
| Event | Meaning |
|---|---|
subscription.created | A mandate was written. Nothing has been charged. |
subscription.updated | An editable field changed — amount, billing day, instrument, descriptors or metadata. |
subscription.paused | Collection has been suspended; the mandate still exists. When the issuer caused it the payload carries pausedBy: "issuer", failureCode and failureMessage — ask the customer for another card. |
subscription.resumed | Collection has restarted on the existing schedule. |
subscription.canceled | The mandate has ended. Final. canceledVia says who ended it. |
subscription.completed | The subscription reached its totalBillingPeriods and finished normally. Not a cancellation. |
subscription.payment_failed | A scheduled collection failed and the retry ladder is running. Emitted once per failed attempt, so a single period can produce several. The window in which emailing the customer still saves the mandate. |
subscription.dunning_exhausted | The retry ladder ran out without collecting. Carries cancelsAt. Stop providing the service. |
| Event | Meaning |
|---|---|
settlement.created | A batch closed and its lines are on your ledger. data is { id, batchReference, batchDate, status, currency, totals, payout: { state } }. Net = gross − refunds − chargebacks − fees; the payout itself is a separate fact, below. |
payout.paid | The net has been sent to your bank account. data is { settlementId, state, netMinor, currency, reference, paidAt, failedAt, note }. |
payout.failed | The transfer did not go through — usually a bank-detail problem. Same payload; note says what. The money is still with us. |
| Event | Meaning |
|---|---|
merchant.approved | Your application was approved. The rest of the dashboard opens and your processing account is provisioned from here. |
merchant.rejected | Your application was declined. It can be corrected and resubmitted. |
merchant.suspended | The account has been suspended. Every API call now answers 403 until it is lifted. |
instrument.updated | A stored card's details changed — the issuer reissued it and the account updater picked up the new number or expiry. data is { id, buyerId, brand, last4, expirationMonth, expirationYear, updateType, actionRequired }; when actionRequired is non-empty the issuer would not update the card automatically and you need to ask the customer for current details. Otherwise nothing to do; the mandate keeps working. |
instrument.disabled | A stored card or bank account can no longer be charged — the issuer reports it closed, or declined it in a way that must not be retried. data is { id, buyerId, last4, reason, code }. Ask the customer for a new one before the next collection fails. |
compliance.due | A PCI self-assessment has been issued, due 90 days out. data is the form: { _id, environment, type, periodKey, state, dueAt, daysRemaining, validFrom, validUntil, … }. Signing it takes minutes. |
compliance.overdue | It was not signed by dueAt. Reminders continue until it is. |
compliance.completed | Signed. Carries validUntil — roughly a year out, and a date nobody remembers to go and read — and the attestation that was made. |
{
"id": "evt_9c1f4a02b7de5183aa60c4e2f8b31d70",
"event": "payment.succeeded",
"created_at": "2026-08-28T09:31:19.404Z",
"data": {
"_id": "66f1c1b8a2b7e10c9d4a3f5c",
"reference": "PAY-000043",
"status": "succeeded",
"source": "terminal",
"amountMinor": 1260,
"tipAmountMinor": 210,
"currency": "USD",
"deviceId": "66f0a1c4e2b7d9a3f5c81b02",
"succeededAt": "2026-08-28T09:31:19.211Z"
}
}
// The event name is "event", not "type", and the timestamp is snake_case.
// "id" is the same value as the X-Gateway-Event-Id header.
// For payment.* events, "data" is the full payment object from the Payments section.
// For refund.* events, "data" is { "payment": …, "refund": … } —
// the refund and the payment it belongs to travel together.
// Asked for 1050. Took 1260, because the cardholder tipped 210.Testing in sandbox#
Sandbox behaves like production, with one useful difference: the amount decides the outcome. There is no table of magic card numbers — any well-formed test card tokenizes — so send the amount that produces the result you want to exercise.
| amountMinor | Outcome | Use it to test |
|---|---|---|
anything under 100 | Declined, failureCode: "200". | The one rule the test processor itself enforces: every amount below $1.00 declines. A “quick 50-cent smoke test” is a scripted decline, not a bug in your integration. |
202 | Insufficient funds. | A soft decline the customer can fix with another card. Retryable. |
223 | Expired card. | The dunning path on a subscription, and the “update your card” email that should follow it. |
225 | CVV did not match. | Asking the customer to re-enter the security code rather than switch cards. |
240 | Call issuer. | A decline the cardholder can resolve with their bank — worth wording differently from a hard refusal. |
250 | Pick up card. | A hard decline: the stored instrument is disabled and instrument.disabled fires. failureMessage is deliberately generic — never repeat the reason to the person holding the card. |
261 | Stop all recurring. | The issuer refusing recurring charges: a subscription collecting this amount is paused with pausedBy: "issuer" instead of dunned, and the card is disabled. |
264 | Retry later. | The issuer asking for the charge to be presented again in a few days. Retryable. |
300 | Rejected before the network. | The processor refusing the request itself. failed with failureCode: "300". |
410 | Account misconfiguration. | Our problem, not the cardholder's: answered as a 500 rather than as a decline, so nobody concludes the card is bad. The record is still there, failed, with failureCode: "410". |
420 | Communication error after the charge landed. | The outcome-unknown path: 504, a pending payment, and the same Idempotency-Key replaying that answer until the poller finds the charge and resolves it to succeeded. The most valuable test on this page. |
Any other amount of $1.00 or more approves. Two more sandbox behaviours are worth designing for, because they are exactly what production does:
- Duplicates are refused. The same card charged the same amount within the processor's duplicate window — 15 minutes in sandbox — is refused with a
409, and the payment is recordedfailedwithfailureCode: "DUPLICATE". That is not your idempotency key at work; it is the processor's own check, keyed on the card and the amount regardless of what else differs. Vary the amount between test charges, or sendallowDuplicates: truewhere your account permits it. - Bank debits stay
pending. A sandbox check answers201withstatus: "pending"and stays there until it is settled —payment.succeeded— or returned —payment.returned, withbankReturnpopulated. In sandbox that happens when we drive it, not on a clock; ask support to settle or return a specific test payment for you. If your checkout cannot show a “payment in progress” state, you will discover it here rather than on a customer.
Testing without a browser#
When your sandbox runs on the built-in simulator — the tokenization config says driver: "mock" — there is no script to load, and token accepts a literal test token instead, so a server-side test suite can exercise every path above without a browser in the loop. Against driver: "live" the sandbox is the processor's real test environment and the tokens must come from the hosted fields.
| token | Produces |
|---|---|
mock:card:<pan>:<MMYY>[:<cvv>] | A card. Any well-formed test number — mock:card:4111111111111111:1030:999 is a Visa credit card. |
mock:check:<account>:<routing>[:<name>] | A bank account — mock:check:24413815:490000018. Send it with a check object, or on its own; the payment will be pending. |
mock:applepay:<pan>:<MMYY> | An Apple Pay token. Send it with wallet: "apple_pay". |
mock:googlepay:<pan>:<MMYY> | A Google Pay token. Send it with wallet: "google_pay". |
Terminals can be tested the same way: on the simulator any 4–12 character code registers a device, a code beginning AX registers an Axium DX8000 and anything else a Lane/3000, and codes are not single-use. A sale sent to a simulated terminal waits exactly as a real one would — nobody is standing at it — so left alone it ends as a 504 after two minutes, and POST /devices/{id}/cancel from a second connection turns it into the 402 with TERMINAL_CANCELLED. To drive the paid path end to end, ask support to complete a specific request for you.
Sandbox and production are separate worlds
An object created in one does not exist in the other. Customers, stored instruments, payment links, devices and subscriptions must all be created again with live credentials — and the tokenization key and script URL differ too. Plan for that in your go-live runbook rather than discovering it on the morning you switch over.
Testing webhooks#
- Register a sandbox endpoint and verify with your sandbox webhook signing secret — it is a different value from the production one.
- Press Send test on the Webhook endpoint screen. The test event is delivered while you wait and the dashboard reports the answer your endpoint actually gave, so a verifier that rejects everything fails here rather than on your first real payment.
- Deliberately return a
500once and watch the retry arrive under Deliveries. Confirm your deduplication onX-Gateway-Event-Idmeans the retry does not double-fulfill the order, and use Replay on that delivery to prove the same thing a second time. - Send a request with a timestamp deliberately six minutes old and confirm your handler rejects it.
- Charge
420and confirm your system parks the504as unknown, polls, and then acts on thepayment.succeededthat follows — without a second charge. - Take a card-machine payment and confirm your till treats
402as “not taken” and never as a crash.
Going live#
- Register. This creates the account. At this point the dashboard shows two things and no more: Onboarding and Settings. Everything else — Payments, Terminals, Payouts, Disputes, Developers — appears only once the account is approved, because until then there is nothing behind those screens.
- Complete the onboarding application. Five steps on the Onboarding screen: Business, Owners, Payout account, How you sell, then Review & submit. Each step unlocks when the one above it is complete, and your answers are kept as you go, so it can be done over several sittings. Incomplete applications are the single biggest cause of a slow go-live.
- Submit, and wait for our review. A reviewer checks the details, usually within one to two business days, and you are emailed the decision. Two outcomes are not the end of the road: an application sent back for correction is not a decline — the Onboarding screen shows the reviewer's own words and a button to correct and resubmit — and even a declined application can be corrected and resubmitted.
- Approval. This is the hinge. It opens the rest of the dashboard and it is what provisions your processing account, for whichever environments were opened for you.
- Create a sandbox key and build. Developers → API keys → Create key, with the environment set to Sandbox. This is the first moment a key of any kind can exist.
- Account activation. A newly provisioned processing account takes a little time to activate, and the Onboarding screen tracks each environment until it reads Ready to accept payments. If the reviewer needs a document — a bank statement, a voided check, identification — they name it in their message and you upload it on that same screen.
- Live processing enabled. Once the production account is active, the environment switch offers Live; it asks you to type a confirmation, because every payment from there charges a real card.
- Generate live keys. Create a
gw_live_key, store the secret in your secret manager, and deploy it. Sandbox keys keep working; they simply cannot see live data. - Configure the production webhook endpoint. It is a second endpoint, not the sandbox one repointed — switch the dashboard to Live first, then set the URL, take the signing secret it shows you once, and confirm a real event verifies before you take real money.
Two things that catch people out
Live processing is refused until the production processing account is active. Generating a live key early does not change that — the key will exist and the payments will be refused. The dashboard will even let you switch to Live before then, with a standing warning across the top saying exactly this. Do not schedule a launch date before approval has landed.
A PCI attestation must be signed. It appears on the Compliance screen once the account is live, and signing it is a typed name, a job title and a checkbox. An unsigned attestation does not block processing, but it is chased: compliance.due arrives when it is issued, compliance.overdue when the 90-day window passes, and the reminders keep coming until somebody signs. For a standard integration using the hosted card fields, the attestation is the short SAQ-A one — a few minutes of work that costs real money to ignore, and it has to be renewed every year.
Pre-launch checklist#
- Every money-moving write sends an
Idempotency-Keygenerated per operation, not per HTTP attempt. - Nothing branches on error
messagetext. - Card-machine payments treat
201as paid,402as not taken, and504as unknown-until-polled — never as a decline. - Reconciliation reads amounts off the payment object, so tips are not lost.
- The webhook handler verifies the signature over the raw body, compares in constant time, enforces the ±5 minute window, and deduplicates on
X-Gateway-Event-Id. dispute.createdalerts a human the same day.- Live secrets live in a secret manager, and key rotation has been rehearsed once before you need it.
- Statement descriptors say something a cardholder will recognize on a bank statement.
When all of that is true, you are ready. If something in these pages is wrong, ambiguous or missing, tell us — documentation that quietly disagrees with the API is a defect like any other.