KEY TAKEAWAYS
- Authenticate with the API key in a header — never in URLs.
- Branch on the result field: live/dead/unknown/error.
- Retry only transient errors, with backoff.
- Every response includes the current balance.
- AVS adds a second dimension where the route supports it.
- Watch classified rate and latency trends, not just the balance.
If card verification is part of your product rather than a manual task, the API is how you do it. This guide covers the integration path end to end.
Authentication
Every account gets an API key from the dashboard. Send it with each request using the documented header — never put it in URLs, query strings or client-side code, where it can leak into logs and browser history. Rotate the key immediately if it may have been exposed. Read API key security best practices before going live.
The request
A verification request is small: one card and the gateway you want to use. The response maps directly onto the result states described in live, dead, unknown explained so your code can branch cleanly.
POST /api/v1/check
X-API-Key: your_key
Content-Type: application/json
{ "card": "4307410000000000|01|2030|123", "gateway": "new" }
The response
{
"status": true,
"result": "Live",
"balance": "49.95",
"charge": "0.0500"
}
Always branch on result and treat anything that is not a clean classification as a retry candidate. Check status first: when it is false, the check was not billed and the error field explains why.
Error handling
- 401/403: key missing, wrong or revoked — fix configuration, do not retry blindly.
- 402: insufficient balance — top up; requests are rejected before spending.
- 429: rate limited — back off with jitter and retry.
- 5xx / timeouts: transient — retry with exponential backoff.
Never retry a request whose key or payload is invalid; you will only generate noise and possibly lock your own automation.
Billing
Checks are billed per classified result from your prepaid balance; a request that never reaches a usable answer is not charged. Each response includes the current balance so your integration can warn before running dry. Every charge appears in your history with the exact amount and reference.
Going to production
- Store the key in a secret manager or environment variable.
- Log request IDs, not full card strings.
- Set conservative timeouts and a retry budget per batch.
- Use a secondary gateway for error retries if throughput matters.
Full endpoint reference: API documentation.
The API is deliberately the same checker the web interface uses, exposed as one endpoint with header authentication. A request carries a gateway, a card in that gateway's format and an optional JSON flag; a response carries the result class, the balance and the charge. There is no state to manage beyond the key and the balance.
Design your integration around the guarantees rather than around provider uptime assumptions: errors are never billed, every response is self-metering, and the key can be rotated instantly. Those three properties make a simple retry strategy both safe and cheap.
Key points about API integration
- One endpoint, header key, JSON responses
- Branch on the result field, not on HTTP status alone
- Retries for errors are free; retries for dead cards are waste
- Rotate keys without downtime
The API side of API integration
Branch on the result field rather than the HTTP status alone: a successful response can still carry an error outcome. Errors produce no classification and no charge, which makes a careful retry strategy effectively free. Log request identifiers and outcomes, never full card numbers or the API key itself. Keep the integration boring: one endpoint, one key, explicit handling for the four result classes. That distinction is what keeps API integration decisions clean.
Security rules for API integration
The dashboard shows the key once and lets you rotate it at will; rotation is cheap, leaks are not. Log identifiers and outcomes, not card numbers. Debugging almost never requires a PAN. Encrypted transport and account-scoped access are defaults; nothing about the integration requires changing them. API keys are server-side secrets: they belong in environment configuration, never in URLs, logs or client bundles. That distinction is what keeps API integration decisions clean.
Interpreting outcomes in API integration
- Errors in API integration return to the queue after the cause is fixed, because they produced no answer at all.
- Dead results in API integration route to recovery: dunning, an update-payment prompt or list cleanup.
- In API integration, live results route forward: billing, approval or completion, depending on the workflow.
- Unknown results in API integration get one fallback pass on a second route, then a defined resting state.
When a result contradicts other evidence, re-check once after a reasonable interval rather than assuming the checker is wrong. A result is only as fresh as its timestamp. High-value decisions should use checks that ran close to the moment of the decision. Errors are free by design: no classification means no charge, so retrying after fixing the cause costs nothing but effort. It is a small rule that changes how API integration behaves at scale.
Putting API integration to work
When results look wrong, diagnose in order: input format, route, provider health, and only then the cards themselves. Size batches to the provider ceiling. Past that line, extra concurrency converts into timeouts rather than throughput. Keep a small balance buffer so an interrupted run never leaves a half-classified list and the temptation to re-check everything. Deduplicate before submitting: the same card in a list twice is billed twice if both copies classify. It is a small rule that changes how API integration behaves at scale.
Using API integration on the right side of the line
Check only cards you own or are authorised to process; verification is not a shortcut around cardholder authorization. The platform does not trade card data, and nothing in the system is designed to bypass a cardholder's consent. A check does not move money, does not create a charge and does not touch the cardholder's credit file. Write it down; API integration workflows live and die on small consistencies.
Operating API integration at scale
Track cost per classified card rather than cost per request; it is the only metric that reflects retries and unknown rates. Keep one primary gateway and one fallback, and switch on evidence — error spikes and classified-rate drops — rather than on price alone. Treat provider outages as routing problems: switch routes, recover the unclassified remainder, keep the answers you already paid for. Document the route, the batch policy and the retry rules next to each production run; six months later that note is the diagnosis. Keep it in mind whenever API integration results are reviewed.
Reading API integration results honestly
A live answer is evidence about the account, not a guarantee about a specific future transaction; issuer rules can change between the check and the charge. A result is only as fresh as its timestamp. High-value decisions should use checks that ran close to the moment of the decision. The four result classes are a decision matrix, not a score: live proceeds, dead recovers, unknown gets one careful retry, error returns to the queue. Two metrics describe any run: how many cards classify, and how long the pass takes. Everything else is commentary. The habit costs nothing and removes a recurring class of mistakes.
What aggregate data says about API integration
When the classified rate moves, the cause is usually a route or provider change rather than the underlying cards. Aggregate numbers describe populations, not individual cards. Use them to size timeouts and retry budgets, never to judge one account. The reference BIN table covers hundreds of thousands of issuer ranges, and it is deliberately separate from account-status data: one describes issuers, the other describes cards. Latency percentiles matter more than averages: the p90 and p99 tell you what a slow run actually feels like. In API integration work, that is the difference between a signal and a guess.