API Documentation

Oxin Pay provides a REST API for creating invoices, managing balances, and receiving webhook notifications. All authenticated endpoints require HMAC-SHA256 signing.

Base URL: https://pay.oxinchain.io

HMAC Authentication

Requests to /v1/* endpoints require a signature in the X-Signature header. Compute it as HMAC-SHA256(secret_key, method + path + timestamp + body_json).

// Example: Create invoice
const ts = Date.now().toString();
const body = JSON.stringify({ amount: "10.00", currency: "USDT", chain: "BSC" });
const sig = hmacSha256(apiSecret, "POST" + "/v1/invoices" + ts + body);

fetch("https://pay.oxinchain.io/v1/invoices", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": apiKey,
    "X-Timestamp": ts,
    "X-Signature": sig,
  },
  body,
});

Authentication

All API requests must be signed with HMAC-SHA256 using your API secret key.

POST/web/v1/auth/loginMerchant login with email + password
POST/web/v1/auth/signupCreate merchant account
GET/web/v1/auth/verify-emailVerify email address with token

Invoices

Create and manage payment invoices. Each invoice generates a unique deposit address.

POST/v1/invoicesCreate a new payment invoice
GET/v1/invoices/:idGet invoice details
GET/v1/invoicesList invoices with filters
GET/web/v1/invoices/public/:publicIdPublic checkout data (no auth)

Checkout

Hosted checkout page and real-time payment status updates via Server-Sent Events.

GET/checkout/:invoiceIdHosted checkout page
GET/web/v1/checkout/:publicId/eventsSSE stream for live updates

Balances & Withdrawals

Query your available balances and initiate withdrawals to configured addresses.

GET/v1/balancesGet balance per token/chain
POST/v1/withdrawalsCreate withdrawal request
GET/v1/withdrawalsList withdrawal history

Webhooks

Receive real-time notifications when payment status changes. Verified with HMAC-SHA256.

POST/v1/webhooksRegister webhook endpoint
GET/v1/webhooksList webhook endpoints
DELETE/v1/webhooks/:idRemove webhook endpoint

API Keys

Manage API keys for programmatic access. Keys can be scoped and revoked at any time.

POST/web/v1/api-keysCreate new API key
GET/web/v1/api-keysList API keys
DELETE/web/v1/api-keys/:idRevoke API key

Webhook Payload

When a payment event occurs, Oxin Pay POSTs a JSON payload to your registered endpoint. Verify authenticity using the X-Oxinpay-Signature header.

{
  "event": "invoice.completed",
  "timestamp": "2025-01-01T12:00:00Z",
  "data": {
    "invoice_id": "inv_abc123",
    "public_id": "pub_xyz789",
    "status": "completed",
    "amount": "10.000000",
    "currency": "USDT",
    "chain": "BSC",
    "tx_hash": "0xabc...",
    "confirmations": 12,
    "paid_at": "2025-01-01T12:00:05Z"
  }
}

Ready to integrate?

Create your merchant account and generate an API key in seconds.

Create Account