API Reference

The complete API reference is in progress. This page is a roadmap of what’s in the platform today and where the detailed reference will land.

If you need exact request/response shapes before the reference ships, contact [email protected] with your integration use case — we’ll send you the current shape directly.

Base URL

https://api.soxara.com

All endpoints are versioned under /v1. We follow semver at the API level — breaking changes go into a new major version (/v2), additive changes ship on the current version.

Conventions

Authentication: Bearer key on every request.
Content type: application/json for everything.
Amounts: integer cents, see Money.
Idempotency: required on every mutation, see Idempotency.
Envelopes: { success, data } or { success: false, error }, see Errors.
Trace IDs: every response carries X-Trace-Id — include it when contacting support.

Endpoints, by resource

Auth (Public — for Soxara’s own apps)

These power Soxara’s own WhatsApp + mobile surfaces. Most integrators don’t call these; you authenticate to us with a merchant key, your customers authenticate to us via Soxara directly.

POST  /v1/auth/request-otp
POST  /v1/auth/verify-otp
POST  /v1/auth/refresh

Payments

The primary integration surface for accepting payments from your customers.

POST  /v1/payments              Create a PaymentIntent
GET   /v1/payments/{id}         Retrieve a PaymentIntent
POST  /v1/payments/{id}/cancel  Cancel before completion
POST  /v1/refunds               Refund a payment
GET   /v1/refunds/{id}          Retrieve a refund

Wallets

For platforms that build on top of Soxara user wallets (e.g., your users’ Soxara balance is part of your product surface).

GET   /v1/wallets               List wallets (you have access to)
GET   /v1/wallets/{id}          Retrieve a wallet
GET   /v1/wallets/{id}/transactions   List transactions

Transfers

Wallet-to-wallet sends, including the viral claim flow.

POST  /v1/transfers             Create a transfer
GET   /v1/transfers/{id}        Retrieve a transfer
POST  /v1/transfers/claim       Claim a viral transfer

Gift cards

Merchant gift card lifecycle.

POST  /v1/gift-cards            Issue a card (buyer pays)
POST  /v1/gift-cards/bulk-share Issue a bulk batch (one buyer, many recipients)
POST  /v1/gift-cards/{id}/redeem    Redeem at POS
GET   /v1/gift-cards/{id}       Retrieve
GET   /v1/gift-cards/mine       List cards the calling user holds

Memberships

Recurring subscriptions to merchant tiers.

POST  /v1/memberships           Subscribe
PATCH /v1/memberships/{id}      Change tier
DELETE /v1/memberships/{id}     Cancel
GET   /v1/memberships           List active memberships

Bill payments

Utility and biller payments via the TIMM rail.

GET   /v1/billers               List supported billers (LEC, LWSC, etc.)
POST  /v1/bill-payments         Initiate a bill payment
GET   /v1/bill-payments/{id}    Retrieve status (and electricity tokens, when applicable)

Webhooks

POST   /v1/webhook-endpoints           Register a webhook endpoint
GET    /v1/webhook-endpoints           List endpoints
PATCH  /v1/webhook-endpoints/{id}      Update events list or URL
DELETE /v1/webhook-endpoints/{id}      Delete an endpoint

Merchant administration

GET   /v1/merchant              Retrieve your merchant profile
GET   /v1/merchant/api-keys     List your API keys
POST  /v1/merchant/api-keys     Mint a new key
POST  /v1/merchant/api-keys/{id}/revoke   Revoke a key

What’s not in this API today

Card issuance (Stripe Issuing) — Soxara issues virtual cards to its users; integrators don’t issue cards through this API.
KYC — your customers complete KYC inside Soxara’s own surfaces, not through your platform.
Internal admin (fraud review, dispute evidence handling, manual settlements) — these run from Soxara’s admin dashboard, not the public API.

OpenAPI spec

An OpenAPI 3.1 spec covering the full surface is shipping next. It will be hosted at https://api.soxara.com/openapi.yaml and generated alongside this docs site so they can’t drift.

Errors Overview