API documentation

One base URL, three REST endpoints, and an MCP server. All pure compute. Authenticate with ?key= or an Authorization: Bearer header. Get a free key →

Prefer a spec? Import the OpenAPI 3.1 spec into Postman, Insomnia, or RapidAPI. Wiring up an AI agent? Jump to Connect your AI agent.

BIN / IIN lookup

Returns the scheme, valid lengths, and CVV length for a BIN. Issuer/country are returned for known sample BINs only. This is a QA helper, not a comprehensive BIN database. Try it interactively in the BIN inspector.

GET /api/v1/bin?bin=424242&key=YOUR_KEY

{
  "bin": "424242",
  "scheme": "visa",
  "brand": "Visa",
  "type": "credit",
  "bank": "Stripe test",
  "country": "US",
  "lengths": [13, 16, 19],
  "cvvLength": 3
}

curl "https://www.testcards.io/api/v1/bin?bin=424242&key=YOUR_KEY"

# Or send the key as a Bearer token instead of ?key=
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://www.testcards.io/api/v1/bin?bin=424242"

Luhn validation

Checks the mod-10 checksum and detects the scheme.

GET /api/v1/luhn?number=4242424242424242&key=YOUR_KEY

{ "number": "4242424242424242", "luhnValid": true, "scheme": "visa", "brand": "Visa", "lengthValid": true }

curl "https://www.testcards.io/api/v1/luhn?number=4242424242424242&key=YOUR_KEY"

# Or send the key as a Bearer token instead of ?key=
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://www.testcards.io/api/v1/luhn?number=4242424242424242"

Generate test cards

Returns Luhn-valid, non-functional QA fixtures. These are declined by real processors.

GET /api/v1/generate?network=visa&count=5&key=YOUR_KEY

{
  "network": "visa",
  "count": 5,
  "cards": [{ "number": "4...", "formatted": "4... ...", "valid": true }]
}

curl "https://www.testcards.io/api/v1/generate?network=visa&count=5&key=YOUR_KEY"

# Or send the key as a Bearer token instead of ?key=
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://www.testcards.io/api/v1/generate?network=visa&count=5"

Connect your AI agent (MCP)

TestCards ships a streamable-HTTP MCP server so coding agents can validate, inspect, and generate test-card fixtures with a metered key. No SDK. It exposes the validate_card, lookup_bin, and generate_test_cards tools.

Add this to your client config: Claude Desktop / Claude Code (claude_desktop_config.json), Cursor (.cursor/mcp.json), or any MCP client’s mcpServers block:

mcpServers (Claude / Cursor)

{
  "mcpServers": {
    "testcards": {
      "url": "https://www.testcards.io/mcp?key=YOUR_KEY"
    }
  }
}

You can also pass the key via an Authorization: Bearer header or an apiKey tool argument. The endpoint is plain JSON-RPC 2.0 over POST:

MCP endpoint:  https://www.testcards.io/mcp   (POST, JSON-RPC 2.0)

The server is also published for discovery on Glama and Smithery so agents can find it from their MCP registries.

OpenAPI / Postman / RapidAPI

The full REST surface is described by an OpenAPI 3.1 document. Import it into Postman, Insomnia, RapidAPI, or generate a client from it.

import URL

https://www.testcards.io/openapi.json

Parameters

Param	Applies to	Description
key	required	Your API key (or send as Authorization: Bearer <key>).
bin	required for /bin	A BIN/IIN or full card number. Scheme & length are computed; issuer fields fill in for known sample BINs.
number	required for /luhn	The card number to validate against the Luhn checksum.
network	for /generate	visa \| mastercard \| amex \| discover \| diners \| jcb \| unionpay \| maestro. Default visa.
count	for /generate	How many numbers to generate, 1–50. Default 1.

Errors

401 invalid/missing key · 429 monthly limit reached · 400 bad parameter · 422 unrecognized card number.

For software testing and QA only. Generated numbers are format-valid (they pass the Luhn check) but are not issued to anyone, hold no funds, and are declined by every real payment processor. Do not use this API for fraud, “carding,” or to bypass any payment control. Those uses are prohibited.