Core APIs

Payments API

Accept crypto and card payments. Create hosted checkout sessions, retrieve them, and cancel open ones. Every session generates a signed webhook when its status changes.

Base URL

https://blockcade.app/gateway/api

Content-Type

application/json

POST /sessions/ — Create a checkout session

Creates a new payment session and returns a hosted checkout URL to redirect your customer to.

Request

POST /gateway/api/sessions/
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

Body parameters

Field	Type	Required	Description
amount	number	Yes	Amount to charge in the currency below. Minimum `1`.
currency	string	Yes	ISO 4217 code — `USD`, `EUR`, `GBP`, `NGN`, `KES`, etc.
accepted_currencies	string[]	No	Which crypto the customer can pay with. Defaults to `["USDC","USDT","BTC","ETH"]`.
method	string	No	`"crypto"` (default) or `"card"`. Crypto routes through CoinGate. Card routes through Alchemy Pay.
customer_email	string	No	Emails receipts and updates to this address.
description	string	No	Human-readable line item shown to customer on checkout. Max 120 chars.
success_url	string	No	Where to send the customer after payment succeeds.
cancel_url	string	No	Where to send the customer if they cancel before paying.
metadata	object	No	Arbitrary key/value pairs. Returned unchanged on webhooks. Useful for order IDs.

Example request

curl -X POST https://blockcade.app/gateway/api/sessions/ \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 99.00,
    "currency": "USD",
    "accepted_currencies": ["USDC", "USDT"],
    "method": "crypto",
    "customer_email": "buyer@example.com",
    "description": "Blockcade Pro Plan · monthly",
    "success_url": "https://mysite.com/thanks",
    "cancel_url":  "https://mysite.com/cart",
    "metadata": {"order_id": "ORD-1234", "sku": "PRO-M"}
  }'

Response — 201 Created

{
  "id":                  "9e73...uuid",
  "reference":           "ref_a8Kj29Xz10",
  "status":              "open",
  "amount":              "99.00",
  "currency":            "USD",
  "accepted_currencies": ["USDC", "USDT"],
  "customer_email":      "buyer@example.com",
  "metadata":            {"order_id": "ORD-1234", "sku": "PRO-M"},
  "paid_via":            "",
  "paid_tx_hash":        "",
  "created_at":          "2026-08-07T21:15:03.291Z",
  "paid_at":             null,
  "success_url":         "https://mysite.com/thanks",
  "cancel_url":          "https://mysite.com/cart",
  "url":                 "https://blockcade.app/gateway/pay/ref_a8Kj29Xz10/"
}

Redirect customers to url. That's the hosted checkout page — Blockcade-branded, mobile-responsive, with QR codes, countdown timer, and card fallback. Don't build your own checkout UI.

Session statuses

open Awaiting customer payment. Default state after creation.

paid Payment received and confirmed. Terminal state.

expired Session timed out (default 30 minutes) without payment.

cancelled Merchant or customer explicitly cancelled.

GET /sessions/{reference}/ — Retrieve a session

Fetch the current state of any session you created. Idempotent — call as often as you like.

curl https://blockcade.app/gateway/api/sessions/ref_a8Kj29Xz10/ \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx"

Returns the same shape as create, without url. Prefer webhooks over polling — they're pushed the moment status changes.

GET /sessions/ — List sessions

Returns your 100 most recent sessions, newest first.

curl https://blockcade.app/gateway/api/sessions/ \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx"

{
  "data": [
    { "reference": "ref_a8Kj29Xz10", "status": "paid", ... },
    { "reference": "ref_Xy7Bq15Ll2", "status": "open", ... }
  ]
}

POST /sessions/{reference}/cancel/ — Cancel an open session

Marks the session as cancelled. Returns 409 Conflict if the session is already paid, expired, or cancelled.

curl -X POST https://blockcade.app/gateway/api/sessions/ref_a8Kj29Xz10/cancel/ \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx"

Rate limits

POST /sessions/ is limited to 100 requests per second per API key. Hitting the limit returns 429 Too Many Requests. Use exponential backoff and honor the Retry-After header.

Idempotency

Sessions are created without server-side deduplication. If your request times out and you retry, you may create two sessions. To avoid this, include an Idempotency-Key header — coming in a future release. For now, treat session creation as at-least-once and reconcile via metadata like order_id.

Testing

Use a sk_test_… key for test-mode sessions. Test sessions render with a "🧪 Simulate successful payment" button on the hosted checkout — clicking it triggers the same webhook + email flow as a real payment.

Set up webhooks → Use an SDK → Handle errors →