Crypto Payment Gateway - Quick Reference

TL;DR

Two Ways to Accept Crypto Payments:

1. 🎨 Hosted Page (Easiest)

# Don't include "network" in request
POST /api/v1/checkout/create
{ "payment_method": "crypto", ... }

# Get back: payment_url
# Customer selects network on hosted page

2. 🔧 Direct Payment (Custom UI)

# Include "network" in request
POST /api/v1/checkout/create
{ "payment_method": "crypto", "network": "BSC", ... }

# Get back: deposit_address, qr_code
# Display in your own UI

---

Request Comparison

Feature	Hosted Page	Direct Payment
Include network?	❌ No	✅ Yes (required)
Returns payment_url?	✅ Yes	❌ No
Returns deposit_address?	❌ No	✅ Yes
Returns qr_code?	❌ No	✅ Yes
Customer selects network?	✅ Yes (on page)	❌ No (pre-selected)
Best for	Simple integration	Custom UI

---

Hosted Page Flow

1. Create checkout (no network)
   ↓
2. Get payment_url
   ↓
3. Redirect customer to URL
   ↓
4. Customer selects network
   ↓
5. Customer pays
   ↓
6. You receive webhook

Request:

{
  "amount": 100,
  "currency": "USD",
  "customer_email": "user@example.com",
  "reference": "ORDER-123",
  "payment_method": "crypto"
}

Response:

{
  "payment_url": "https://payments-api-dev-966260606560.europe-west2.run.app/pay/abc-123"
}

---

Direct Payment Flow

1. Create checkout (with network)
   ↓
2. Get deposit_address + qr_code
   ↓
3. Display in your UI
   ↓
4. Customer pays
   ↓
5. Poll /verify or receive webhook

Request:

{
  "amount": 100,
  "currency": "USDT",
  "customer_email": "user@example.com",
  "reference": "ORDER-124",
  "payment_method": "crypto",
  "network": "BSC"
}

Response:

{
  "deposit_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "qr_code": "data:image/png;base64,..."
}

---

Networks

Code	Name	Token Standards
BSC	Binance Smart Chain	BEP-20
ETH	Ethereum	ERC-20
POL	Polygon	Polygon
TRX	Tron	TRC-20
SOL	Solana	SPL

Supported Currencies: USDT, USDC

---

Key Endpoints

POST   /api/v1/checkout/create           # Create session
GET    /api/v1/checkout/verify/:uuid      # Check status
POST   /api/v1/checkout/:uuid/verify-now  # Manual verification

---

Status Values

• pending - Waiting for payment
• paid - Payment confirmed ✅
• failed - Expired without payment

---

Webhooks

{
  "event": "payment.confirmed",
  "session_id": "abc-123",
  "reference": "ORDER-123",
  "amount": 100.00,
  "currency": "USDT",
  "status": "paid",
  "network": "BSC",
  "blockchain_tx_hash": "0xabc123...",
  "paid_at": "2026-01-30T18:10:23Z"
}

---

Common Mistakes

❌ Wrong: Including network when you want hosted page

{ "payment_method": "crypto", "network": "BSC" }  // No payment_url returned!

✅ Right: Exclude network for hosted page

{ "payment_method": "crypto" }  // payment_url returned ✅

---

❌ Wrong: Not specifying network when you want direct payment

{ "payment_method": "crypto" }  // No deposit_address!

✅ Right: Include network for direct payment

{ "payment_method": "crypto", "network": "BSC" }  // deposit_address ✅

---

Test Mode

Use test API key: test_sk_...

• BSC Testnet
• Sepolia (Ethereum)
• Mumbai (Polygon)
• No real funds needed

Use production key: live_sk_...

• Mainnet networks
• Real cryptocurrency
• 1% platform fee

---

Full Docs

📚 See Crypto Gateway Overview for complete documentation