API Reference
| Method | Endpoint | Auth | Purpose |
|---|---|---|---|
POST | /session/deposit | operator key | Create a deposit session → widget URL. Body: externalUserId, lang, platformFiatCurrency, userBalance, amount (+ optional email, operatorReference) |
POST | /session/withdraw | operator key | Create a withdraw session → widget URL (201). Required: externalUserId, lang, platformFiatCurrency, userBalance, amount; optional: email, operatorReference. For executionMode:"HEADLESS", operatorReference, address, chainId and tokenAddress are additionally required; it returns sessionRef + expiry, not a widget URL. |
POST | /session/:uuid/test-webhook | operator key | Self-service test: fire a real, signed completion webhook for one of your sessions at your own webhookUrl — no funds move. See note |
POST | /depositor/address | session (sid) | Get the deposit address — body: sid, currency, chainId |
GET | /chain | public | List networks + token contracts/decimals |
POST | /withdraw/direct-transfer | session (sid) | Initiate a withdrawal |
POST | /withdraw/:id/decision | operator key | Approve / reject a withdrawal (external-approval mode) |
GET | /withdraw/options | operator key | Headless: supported chains/tokens + availability in token units (AVAILABLE/UNAVAILABLE/UNKNOWN). Optional ?sessionRef= for a final pre-execute check |
POST | /withdrawals/:sessionRef/execute | operator key | Headless: bodyless, idempotent — reserve, price and queue settlement → 202 |
GET | /withdrawals/:sessionRef | operator key | Headless: safe status — domain status, tx-hash/confirmation state, retryability, callback state |
POST | /withdrawals/:sessionRef/cancel | operator key | Headless: cancel — succeeds only before a tx hash exists; releases the reservation |
GET | /admin/withdrawals | admin (dashboard-only) | List withdrawals (management panel) |
PATCH | /admin/withdrawals/:id/status | admin (dashboard-only) | Approve / reject a withdrawal |
POST | /admin/withdrawals/:id/retry | admin (dashboard-only) | Headless: safe requeue of a WAITING_FOR_GAS / FAILED(retryable) payout with no tx hash — bodyless; never re-broadcasts |
POST /depositor/address is session-scoped: it is authenticated by the sid in the request body (called by the hosted widget), and takes no Bearer key. It requires the body fields sid, currency, and chainId.
POST /withdraw/:id/decision is operator-authenticated with your OPERATOR_SECRET_KEY (Bearer) — used only when your operator is on external-approval mode. :id is the withdrawal UUID from the async WITHDRAW_REQUEST webhook; body: { "decision": "APPROVE" | "REJECT", "reason"?: string }. See Withdrawals → External approval. Unlike the /admin/* endpoints, this one is partner-callable with your operator key.
POST /session/:uuid/test-webhook fires a real, signed webhook at your own webhookUrl without moving funds, so you can verify your integration end-to-end. Authenticate with your OPERATOR_SECRET_KEY (Bearer); :uuid is the session UUID (the sid returned when you created the session). The payload is identical to a production DEPOSIT / WITHDRAW_COMPLETE event apart from an extra test: "true" field, and delivery is synchronous, so the response carries your endpoint's real result:
{ "status": "success", "data": { "delivered": true, "status": 200, "event": "DEPOSIT" } }Optional body overrides: { "amount", "currency", "chainId", "address" }. Scoped to your own operator (and sub-operators); rate-limited to 5/minute. Your handler must check test === "true" and skip all real ledger side effects. Full guide: Webhooks → Testing Your Integration.
The headless withdrawal endpoints (/withdraw/options, /withdrawals/:sessionRef/execute, /withdrawals/:sessionRef, /withdrawals/:sessionRef/cancel) are operator-authenticated with your OPERATOR_SECRET_KEY (Bearer), scoped to your own operator, and available only when the AbstraPay team has enabled headless for you (otherwise HEADLESS_NOT_ENABLED). They are keyed on the sessionRef returned by POST /session/withdraw when you pass executionMode:"HEADLESS" — that call returns { sessionRef, expiresAt }, not a sid or widget URL. execute takes no body and is idempotent (safe to retry; never a second reservation or payout). Full walk-through: Withdrawals → Mode C — Headless. Scope: EVM / ERC-20 only.
The /admin/* endpoints are dashboard/admin-only — used internally by the management panel under a separate admin login. They are not partner-callable with your OPERATOR_SECRET_KEY. POST /admin/withdrawals/:id/retry is a safe recovery action for headless payouts: it only requeues a WAITING_FOR_GAS or FAILED(retryable) request that has no transaction hash, is bodyless, and never broadcasts on-chain from the HTTP request.