Developers

One request. Every method.

Create a payment, get a status, receive a signed webhook. Test cards and a full sandbox from the moment your account opens — no sales call needed to start building.

Get a test key Read the docs

Base URL: https://cleared-pay.com/api/v1
API version: 2026-08-19
Magic cards: 9, in the sandbox from day one

Integration

Two requests to a capture

A card number never reaches POST /v1/payments — that is what keeps your SAQ A scope. In the sandbox you tokenise a magic card first, then create the payment with the token. In production the token comes from hosted fields or the hosted checkout page instead; the second request is identical.

Step 1 · POST /v1/sandbox/tokens

Tokenise a test card

curl https://cleared-pay.com/api/v1/sandbox/tokens \
  -H "Authorization: Bearer $CLEARED_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "card",
    "number": "4242424242424242",
    "exp_month": 12,
    "exp_year": 2029,
    "cvc": "123"
  }'

# 201 Created
# {
#   "id": "tok_01JBXQ2M4K7T9V3ZC8HR5N6PWD",
#   "object": "token",
#   "type": "card",
#   "card": { "brand": "visa", "last4": "4242", "bin": "424242",
#             "exp_month": 12, "exp_year": 2029 },
#   "livemode": false,
#   "created": "2026-08-19T10:15:00Z",
#   "expires_at": "2026-08-19T10:30:00Z"
# }

Step 2 · POST /v1/payments

Create the payment

curl https://cleared-pay.com/api/v1/payments \
  -H "Authorization: Bearer $CLEARED_SECRET_KEY" \
  -H "Idempotency-Key: 4f0a2c6e-9b31-4c0d-9a7e-1f2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2000,
    "currency": "eur",
    "reference": "ORDER-10432",
    "capture_method": "automatic",
    "payment_method": { "type": "card", "token": "tok_01JBXQ2M4K7T9V3ZC8HR5N6PWD" },
    "description": "Order 10432",
    "metadata": { "cart_id": "c_881" }
  }'

# 201 Created
# {
#   "id": "pay_01JBXQ2M4K7T9V3ZC8HR5N6PWD",
#   "object": "payment",
#   "status": "captured",
#   "amount": 2000,
#   "amount_captured": 2000,
#   "amount_refunded": 0,
#   "currency": "eur",
#   "livemode": false,
#   ...
# }

Omit payment_method.token in step 2 and the payment is created pending instead, waiting for POST /v1/payments/:id/confirm with the token. That is the two-step flow; alternative payment methods never need a token at all. The quickstart walks the whole path.

Where to start

Four ways in

Read in this order if you are integrating for the first time.

Libraries and tooling

No SDKs yet

There are no Cleared-pay client libraries yet — not for Node, not for Python, not for PHP. Anything you find under that name is not ours. The API is plain REST and the samples on this page are the whole integration surface; when a library exists it will be announced here and nowhere else.

REST over HTTPS, JSON in and out — available
One base URL, bearer authentication, lowercase ISO 4217 currencies and integer minor units. Any HTTP client is enough.
Idempotency keys on every POST — available
Send Idempotency-Key and a retry replays the original response byte for byte for 24 hours, including a 4xx.
Signed webhooks — available
HMAC-SHA256 over the raw body with a 300-second tolerance, one signature per active secret for 24 hours after a roll. Verification snippets in Node, Python and PHP.
Dated API versions — available
A version is pinned on the key and overridable per request with the Cleared-Version header. One version is live today: 2026-08-19.
Sandbox simulator — available
Test keys route to a simulator with nine magic cards, per-request outcome overrides, a simulated challenge page and webhook simulation.
OpenAPI description — planned
TODO(openapi): not published yet. When it ships it will be generated from the same Zod schemas that validate every request, so it cannot drift from the API.

Build against the sandbox before you talk to anyone.

A test key comes with the account, and the qualification form takes a few minutes.

Get started Read the docs