The reference.

X-Api-Key: cards402_a1b2c3d4e5f6...

POST /v1/orders
X-Api-Key: cards402_your_key_here
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "amount_usdc": "25.00",
  "webhook_url": "https://your-agent.com/webhook"
}

{
  "order_id": "a3f7c2d1-4e8b-4f0a-9c2d-1b3e5a7f9c0e",
  "status": "pending_payment",
  "phase": "awaiting_payment",
  "amount_usdc": "25.00",
  "payment": {
    "type": "soroban_contract",
    "contract_id": "CAAAA...cards402_receiver_contract...",
    "order_id": "a3f7c2d1-4e8b-4f0a-9c2d-1b3e5a7f9c0e",
    "usdc": {
      "amount": "25.0000000",
      "asset": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
    },
    "xlm": { "amount": "192.84" }
  },
  "poll_url": "/v1/orders/a3f7c2d1-4e8b-4f0a-9c2d-1b3e5a7f9c0e",
  "budget": {
    "spent_usdc": "15.00",
    "limit_usdc": "100.00",
    "remaining_usdc": "85.00"
  }
}

{
  "order_id": "a3f7c2d1-4e8b-4f0a-9c2d-1b3e5a7f9c0e",
  "phase": "awaiting_approval",
  "approval_request_id": "ar_9f3a1b2c",
  "amount_usdc": "25.00",
  "message": "Amount exceeds per-txn cap of $10.00",
  "note": "The account owner has been notified. Poll GET /v1/orders/<id> to check status.",
  "expires_at": "2026-04-08T14:00:00.000Z"
}

npx -y cards402@latest purchase --amount 25
# optional: --asset xlm|usdc
# default is "auto" — picks USDC if the wallet has enough, else XLM

: connected

id: 1776023489012
event: phase
data: {"order_id":"a3f7c2d1-...","status":"pending_payment","phase":"awaiting_payment","amount_usdc":"25.00","updated_at":"2026-04-08T12:00:00Z"}

id: 1776023510234
event: phase
data: {"order_id":"a3f7c2d1-...","status":"ordering","phase":"processing","updated_at":"2026-04-08T12:00:21Z"}

id: 1776023534567
event: phase
data: {"order_id":"a3f7c2d1-...","status":"delivered","phase":"ready","amount_usdc":"25.00","card":{"number":"4111 2345 6789 0123","cvv":"847","expiry":"12/27","brand":"Visa"},"updated_at":"2026-04-08T12:00:45Z"}

const res = await fetch(`${apiUrl}/orders/${orderId}/stream`, {
  headers: { 'X-Api-Key': key, Accept: 'text/event-stream' },
});
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buf = '';
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });
  let i;
  while ((i = buf.indexOf('\n\n')) !== -1) {
    const event = buf.slice(0, i); buf = buf.slice(i + 2);
    const line = event.split('\n').find((l) => l.startsWith('data: '));
    if (!line) continue;
    const state = JSON.parse(line.slice(6));
    if (state.phase === 'ready') { console.log(state.card); return; }
    if (['failed','refunded','expired','rejected'].includes(state.phase)) {
      throw new Error(state.error ?? state.phase);
    }
  }
}

import json
import httpx

TERMINAL = {"failed", "refunded", "expired", "rejected"}

def wait_for_card(api_url: str, order_id: str, key: str):
    headers = {"X-Api-Key": key, "Accept": "text/event-stream"}
    url = f"{api_url}/orders/{order_id}/stream"
    with httpx.stream("GET", url, headers=headers, timeout=None) as res:
        buf = ""
        for chunk in res.iter_text():
            buf += chunk
            while "\n\n" in buf:
                event, buf = buf.split("\n\n", 1)
                data_line = next(
                    (l for l in event.split("\n") if l.startswith("data: ")),
                    None,
                )
                if not data_line:
                    continue
                state = json.loads(data_line[6:])
                if state["phase"] == "ready":
                    return state["card"]
                if state["phase"] in TERMINAL:
                    raise RuntimeError(state.get("error") or state["phase"])

    raise RuntimeError("stream ended before terminal phase")

curl -N \
  -H "X-Api-Key: cards402_..." \
  -H "Accept: text/event-stream" \
  https://api.cards402.com/v1/orders/<order_id>/stream

{
  "order_id": "a3f7c2d1-4e8b-4f0a-9c2d-1b3e5a7f9c0e",
  "status": "payment_confirmed",
  "phase": "processing",
  "amount_usdc": "25.00",
  "payment_asset": "usdc_soroban",
  "created_at": "2026-04-08T12:00:00.000Z",
  "updated_at": "2026-04-08T12:00:05.000Z"
}

{
  "order_id": "a3f7c2d1-4e8b-4f0a-9c2d-1b3e5a7f9c0e",
  "status": "delivered",
  "phase": "ready",
  "amount_usdc": "25.00",
  "created_at": "2026-04-08T12:00:00.000Z",
  "updated_at": "2026-04-08T12:01:02.000Z",
  "card": {
    "number": "4111 2345 6789 0123",
    "cvv": "847",
    "expiry": "12/27",
    "brand": "Visa"
  }
}

{
  "order_id": "a3f7c2d1-4e8b-4f0a-9c2d-1b3e5a7f9c0e",
  "status": "failed",
  "phase": "failed",
  "amount_usdc": "25.00",
  "error": "Stage 1 scrape timed out after 3 retries.",
  "created_at": "2026-04-08T12:00:00.000Z",
  "updated_at": "2026-04-08T12:03:15.000Z"
}

{
  "order_id": "a3f7c2d1-4e8b-4f0a-9c2d-1b3e5a7f9c0e",
  "status": "refunded",
  "phase": "refunded",
  "amount_usdc": "25.00",
  "error": "Stage 1 scrape timed out after 3 retries.",
  "refund": {
    "stellar_txid": "e4f5a1b2c3d4...9e0f"
  },
  "created_at": "2026-04-08T12:00:00.000Z",
  "updated_at": "2026-04-08T12:05:27.000Z"
}

[
  {
    "id": "a3f7c2d1-4e8b-4f0a-9c2d-1b3e5a7f9c0e",
    "status": "delivered",
    "amount_usdc": "25.00",
    "payment_asset": "usdc_soroban",
    "created_at": "2026-04-08T12:00:00.000Z",
    "updated_at": "2026-04-08T12:01:02.000Z"
  },
  {
    "id": "b9e1f3a2-7c4d-4b0e-8f1a-2c4e6a8b0d2f",
    "status": "pending_payment",
    "amount_usdc": "10.00",
    "payment_asset": "usdc_soroban",
    "created_at": "2026-04-08T11:59:12.000Z",
    "updated_at": "2026-04-08T11:59:12.000Z"
  }
]

{
  "order_id": "a3f7c2d1-4e8b-4f0a-9c2d-1b3e5a7f9c0e",
  "status": "delivered",
  "amount_usdc": "25.00",
  "payment_asset": "usdc_soroban",
  "card": {
    "number": "4111 2345 6789 0123",
    "cvv": "847",
    "expiry": "12/27",
    "brand": "Visa"
  }
}

{
  "order_id": "a3f7c2d1-4e8b-4f0a-9c2d-1b3e5a7f9c0e",
  "status": "failed",
  "amount_usdc": "25.00",
  "payment_asset": "usdc_soroban",
  "error": "Stage 1 scrape timed out after 3 retries."
}

{
  "order_id": "a3f7c2d1-4e8b-4f0a-9c2d-1b3e5a7f9c0e",
  "status": "expired",
  "phase": "expired",
  "note": "Payment window expired. No funds were taken."
}

{
  "order_id": "a3f7c2d1-4e8b-4f0a-9c2d-1b3e5a7f9c0e",
  "status": "pending_payment",
  "phase": "awaiting_payment",
  "note": "Approved."
}

{
  "order_id": "a3f7c2d1-4e8b-4f0a-9c2d-1b3e5a7f9c0e",
  "status": "rejected",
  "phase": "rejected",
  "error": "Outside approved merchant category."
}

const { createHmac, timingSafeEqual } = require('crypto');

function verifyWebhook(rawBody, signature, timestamp, secret) {
  if (Math.abs(Date.now() - parseInt(timestamp)) > 5 * 60 * 1000) return false;
  const expected = 'sha256=' + createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody).digest('hex');
  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

import hmac, hashlib, time

def verify_webhook(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    # Reject anything older than 5 minutes to thwart replay attacks.
    if abs(time.time() * 1000 - int(timestamp)) > 5 * 60 * 1000:
        return False
    message = f"{timestamp}.".encode() + raw_body
    expected = "sha256=" + hmac.new(
        secret.encode(), message, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

{
  "error": "invalid_amount",
  "message": "amount_usdc must be a positive number"
}

import {
  Cards402Client,
  SpendLimitError,
  RateLimitError,
  ServiceUnavailableError,
  InvalidAmountError,
  AuthError,
  OrderFailedError,
  WaitTimeoutError,
  ResumableError,
} from 'cards402';

const client = new Cards402Client({ apiKey });

try {
  const card = await client.waitForCard(orderId);
} catch (err) {
  if (err instanceof SpendLimitError) {
    // err.limit, err.spent — ask the operator to raise the cap
  } else if (err instanceof RateLimitError) {
    // back off before retrying
  } else if (err instanceof ServiceUnavailableError) {
    // circuit breaker tripped; retry in a few minutes
  } else if (err instanceof OrderFailedError) {
    // err.orderId, err.refund.stellar_txid — payment refunded
  } else if (err instanceof WaitTimeoutError) {
    // err.orderId — order may still complete; poll again later
  } else if (err instanceof ResumableError) {
    // err.orderId — resume with cards402 purchase --resume <id>
  } else if (err instanceof AuthError) {
    // key is missing or revoked
  } else {
    // Cards402Error base, or a non-cards402 error — rethrow
    throw err;
  }
}

{
  "api_key_id": "ak_a3f7c2d1",
  "label": "production-agent",
  "budget": {
    "spent_usdc": "15.00",
    "limit_usdc": "100.00",
    "remaining_usdc": "85.00"
  },
  "orders": {
    "total": 3,
    "delivered": 2,
    "failed": 0,
    "refunded": 1,
    "in_progress": 0
  }
}