REST API

Base URL: https://api.payment.zelapay.xyz. All requests and responses are JSON. Authenticate server-to-server calls with Authorization: Bearer sk_live_….

Create a session

POST /v1/sessions — requires a secret key.

{
  "amount": "19.99",          // required — decimal string, in USDC, up to 6 decimals
  "successUrl": "https://…",  // optional — http(s) only
  "cancelUrl": "https://…",   // optional — http(s) only
  "metadata": { "orderId": "…" } // optional — up to 20 string keys
}

Returns { session, checkoutUrl }.

Create a session (publishable key)

POST /v1/sessions/public — used by the widget. Send the publishable key in an X-Publishable-Key header instead of a bearer token. Same request/response shape as above. Rate-limited to 20 requests/minute/IP.

Retrieve a session

GET /v1/sessions/:id — no authentication required. Returns { session, merchant }.

The session object

{
  "id": "cs_...",
  "merchantId": "merch_...",
  "network": "arc-mainnet" | "arc-testnet",
  "amountSettlement": "19.99",
  "settlementToken": "USDC",
  "paymentPath": "zela_app" | "wallet_connect" | "qr_code" | null,
  "payerAddress": string | null,
  "depositAddress": "0x...",
  "status": "awaiting_payment" | "settling" | "settled" | "expired" | "failed",
  "paymentTxHash": string | null,
  "settlementTxHash": string | null,
  "platformFeeBps": 100,
  "platformFeeAmount": string | null,
  "successUrl": string | null,
  "cancelUrl": string | null,
  "metadata": { "...": "..." },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "expiresAt": "2026-01-01T00:30:00.000Z"
}

Payment URI

GET /v1/sessions/:id/payment-uri — returns { uri }, an EIP-681 payment request URI for the generic QR path.

Errors

Non-2xx responses return { error: string }. 400 for invalid input, 401 for a missing/invalid/revoked key, 404 for an unknown session, 429 when rate-limited.