Oxin Pay Integration Guide

Complete guide for integrating Oxin Pay into any project — e-commerce, SaaS, donations, POS, and more.

1. Introduction

Oxin Pay accepts cryptocurrency payments on behalf of your customers. You create an invoice via API; the customer pays on a hosted checkout page; Oxin Pay sends a webhook when the payment confirms on-chain; you fulfill the order.

Oxin Pay is custodial — funds are held in Oxin Pay's custody and your merchant balance is credited (minus fee). You withdraw to your own wallets through the dashboard. You do not manage private keys.

Supported chains: BTC, LTC, DOGE, ETH, BSC, Polygon, Avalanche, Cronos, Tron, Solana, Oxin Chain — 39+ tokens total.

2. Quickstart (5 Minutes)

Step 1 — Get your API key

Sign up at pay.oxinchain.io → verify email → your key is emailed once. It starts with oxp_live_. New accounts get 100 test calls in pre-approval mode.

Step 2 — Create an invoice

USDT on BSC has token ID 20. Use it for testing:

curl -X POST https://pay.oxinchain.io/v1/invoices \
  -H "Authorization: Bearer oxp_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenId": 20,
    "amountFiat": 1.00,
    "fiatCurrency": "USD",
    "merchantReference": "test-001",
    "redirectUrl": "https://example.com/thank-you",
    "cancelUrl": "https://example.com/cancel"
  }'

Step 3 — Redirect the customer

The response contains checkoutUrl. Redirect the customer there. The hosted page shows a QR code and deposit address.

Step 4 — Watch the status

curl https://pay.oxinchain.io/v1/invoices/INVOICE_PUBLIC_ID \
  -H "Authorization: Bearer oxp_live_YOUR_KEY_HERE"

Status moves: created → pending → confirming → completed. See webhooks to be notified automatically.

3. Prerequisites for Production

• Merchant account approved by the Oxin Pay team
• API key approved (no pre-approval banner in responses)
• Chain and token access requested and approved (Settings → Payment methods)
• Withdrawal addresses whitelisted for each chain (24–48h review)
• Webhook endpoint registered at an HTTPS URL
• TOTP 2FA enabled on your merchant account (recommended)

4. Authentication

All merchant API calls use Bearer token authentication:

Authorization: Bearer oxp_live_YOUR_FULL_KEY_HERE

5. Supported Chains and Tokens

Fetch the live catalog — do not hardcode token IDs:

# All chains
curl https://pay.oxinchain.io/v1/public/chains

# All tokens (optional chainId filter)
curl "https://pay.oxinchain.io/v1/public/tokens?chainId=5"

# Your approved tokens
curl https://pay.oxinchain.io/v1/currencies \
  -H "Authorization: Bearer oxp_live_YOUR_KEY_HERE"

6. Core Concepts

Invoice lifecycle

created → pending → confirming → completed
                               ↘ underpaid

Fees

Default: 0.1% (10 bps) deducted from received amount. Each invoice shows feeBps, feeAmount, and netToMerchant.

Rate locking

Exchange rate is locked at invoice creation. amountCrypto does not change if the market moves. Rate risk is absorbed by the merchant.

7. Webhooks

Register a webhook URL in the dashboard (Settings → Webhooks). Oxin Pay POSTs to it when payment events occur.

Event types

Headers Oxin Pay sends

Signature verification (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(rawBody, sigHeader) {
  // rawBody must be Buffer — read before JSON parsing
  const [algo, provided] = (sigHeader ?? '').split('=');
  if (algo !== 'sha256' || !provided) return false;

  const expected = crypto
    .createHmac('sha256', process.env.OXIN_PAY_WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');

  const a = Buffer.from(provided, 'hex');
  const b = Buffer.from(expected, 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Retry policy

Up to 10 attempts with exponential backoff: min(5 × 2^(attempt−1), 86400) seconds. Timeout per attempt: 10 seconds. After 10 failures the delivery is marked dead.

8. API Reference

All responses: { ok: true, data: {...}, request_id: "..." } or { ok: false, error: { code, message } }

POST /v1/invoices — request fields

9. Integration Patterns

The full guide covers 9 patterns with working code snippets:

• E-commerce checkout (one-time purchase)
• SaaS subscription / account unlock (pay-per-period)
• Donation widget (variable amount)
• Marketplace / multi-vendor
• POS / in-person terminal
• Pay-per-API / metered credits
• Recurring / subscription-style (manual renewal reminder)
• Tipping / content monetization
• Game top-up / virtual currency

See the full Markdown guide for complete code per pattern: docs/OXIN_PAY_INTEGRATION_GUIDE.md § 9

10. Frontend Integration

Redirect flow (recommended)

// Your backend creates the invoice and returns checkoutUrl
document.getElementById('pay-btn').addEventListener('click', async () => {
  const { checkoutUrl } = await fetch('/checkout/crypto', { method: 'POST' })
    .then(r => r.json());
  window.location.href = checkoutUrl;
});

Success page — do not fulfill immediately on redirect

// Poll status — fulfillment happens via webhook
async function pollStatus(publicId) {
  for (let i = 0; i < 60; i++) {
    await new Promise(r => setTimeout(r, 5000));
    const { status } = await fetch(`/api/status/${publicId}`).then(r => r.json());
    if (status === 'completed') { showSuccess(); return; }
    if (status === 'underpaid') { showUnderpaid(); return; }
  }
  showPendingLong(); // "We'll email you when it confirms"
}

11. Code Examples (5 Languages)

Runnable examples are in the repository at examples/:

Each example includes a complete webhook handler with constant-time signature verification.

12. Error Reference

13. Rate Limits

Rate limiting is per source IP. When exceeded, the response is 429 with a Retry-After header. Implement exponential backoff on 429 responses.

14. Security Best Practices

• Store API key and webhook secret in environment variables, never in source code
• Always verify webhook signatures — reject requests without a valid signature
• Read raw body bytes before JSON parsing, then verify, then parse
• Use constant-time comparison for signatures in every language
• Use HTTPS-only webhook URLs
• Whitelist your server's IPs on your API key
• Wrap order fulfillment in a DB transaction (atomic mark-paid + provision)
• Deduplicate webhook deliveries by X-Oxinpay-Delivery
• Rotate keys quarterly or after team member departures

15. Testing

There is no sandbox. Test with real small amounts — TRON USDT (token ID 36) costs ~$0.01 in fees and confirms in ~3 seconds.

Local webhook testing

ngrok http 3000
# Register the ngrok URL in Settings → Webhooks

Replay a webhook manually

SECRET="your_secret"
BODY='{"event":"invoice.completed","data":{"invoiceId":"TEST"},"timestamp":"2026-06-22T12:00:00Z"}'
SIG=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
curl -X POST http://localhost:3000/webhook \
  -H "X-Oxinpay-Signature: sha256=$SIG" \
  -H "X-Oxinpay-Event: invoice.completed" \
  -H "X-Oxinpay-Delivery: test-001" \
  -H "Content-Type: application/json" \
  -d "$BODY"

16. Going Live Checklist

• API key approved (no X-Oxin-Pay-Approval: pending header)
• Chain and token access approved in dashboard
• Webhook endpoint registered with HTTPS URL
• Signature verification implemented and tested with bad signatures
• Webhook idempotency implemented (same delivery → processed once)
• Webhook handler responds within 10 seconds
• DB transaction wraps order fulfillment
• At least one real-money end-to-end test passed
• Withdrawal addresses whitelisted for each chain
• IP whitelist configured on API key
• Monitoring on webhook delivery failures
• Customer support process for 'paid but order not showing'

17. Common Pitfalls

1. Parsing JSON before signature verification (breaks HMAC byte-for-byte match)
2. Using == instead of constant-time comparison for signatures
3. Not deduplicating webhook deliveries → double fulfillment
4. Fulfilling on pending or confirming → unconfirmed deposit
5. Not handling underpaid → stuck invoices requiring support
6. Polling for status instead of using webhooks → hits rate limits
7. Hardcoding token IDs → breaks when tokens are added
8. Skipping the real-money test → misses chain-specific issues

18. FAQ

See the full guide for 15+ additional FAQ entries, migration guides from Stripe / Coinbase Commerce / NOWPayments / BTCPay / PayPal, a complete glossary, and the versioning policy.

19–22. Migration, Glossary, Versioning, Support

The full Markdown guide covers migration from Stripe, Coinbase Commerce, NOWPayments, BTCPay Server, and PayPal; a 30-term glossary; the versioning policy (v1 is current, breaking changes introduce v2); and support contacts.