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.