POST /api/v1/checkout/crypto

Create a new crypto payment checkout session.

Authentication

Required: X-API-Key header

Use your production or test API key depending on the mode.

---

Request

Endpoint

POST https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/checkout/crypto

Headers

Header	Value	Required
X-API-Key	Your API key	✅ Yes
Content-Type	application/json	✅ Yes

Body Parameters

Parameter	Type	Required	Description
amount	float	✅	Payment amount (USD equivalent)
currency	string	✅	USDT or USDC
network	string	✅	BSC, ETH, POL, TRX, or SOL
customer_email	string	✅	Customer's email address
customer_name	string	❌	Customer's full name
reference	string	✅	Unique transaction reference (max 255 chars)
description	string	❌	Payment description
callback_url	string	❌	Webhook URL for payment notifications
metadata	object	❌	Custom metadata (JSON object)

---

Example Requests

cURL

curl -X POST 'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/checkout/crypto' \
  -H 'X-API-Key: rach_live_abc123...' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 100.00,
    "currency": "USDT",
    "network": "BSC",
    "customer_email": "customer@example.com",
    "customer_name": "Jane Smith",
    "reference": "ORDER-12345",
    "description": "Premium subscription",
    "callback_url": "https://yoursite.com/webhooks/payment",
    "metadata": {
      "user_id": "usr_123",
      "plan": "premium"
    }
  }'

JavaScript

const checkout = await fetch('https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/checkout/crypto', {
  method: 'POST',
  headers: {
    'X-API-Key': 'rach_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 100.00,
    currency: 'USDT',
    network: 'BSC',
    customer_email: 'customer@example.com',
    customer_name: 'Jane Smith',
    reference: 'ORDER-12345',
    description: 'Premium subscription',
    callback_url: 'https://yoursite.com/webhooks/payment',
    metadata: {
      user_id: 'usr_123',
      plan: 'premium'
    }
  })
});

const data = await checkout.json();
console.log('Session ID:', data.session_id);
console.log('Deposit Address:', data.deposit_address);

Python

import requests

response = requests.post(
    'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/checkout/crypto',
    headers={
        'X-API-Key': 'rach_live_abc123...',
        'Content-Type': 'application/json'
    },
    json={
        'amount': 100.00,
        'currency': 'USDT',
        'network': 'BSC',
        'customer_email': 'customer@example.com',
        'customer_name': 'Jane Smith',
        'reference': 'ORDER-12345',
        'description': 'Premium subscription',
        'callback_url': 'https://yoursite.com/webhooks/payment',
        'metadata': {
            'user_id': 'usr_123',
            'plan': 'premium'
        }
    }
)

data = response.json()
print(f"Session ID: {data['session_id']}")
print(f"Deposit Address: {data['deposit_address']}")

---

Response

Success Response (201 Created)

{
  "session_id": "chk_sess_abc123def456",
  "deposit_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "amount": 100.00,
  "currency": "USDT",
  "network": "BSC",
  "payment_method": "crypto",
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "status": "pending",
  "expires_at": "2025-12-23T12:00:00Z",
  "instructions": {
    "title": "Send USDT to complete payment",
    "amount": "100 USDT",
    "network": "BSC (BEP-20)",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "important_notes": [
      "Send only USDT on BSC network (BEP-20)",
      "Payment expires in 24 hours",
      "You will be notified once payment is confirmed"
    ]
  }
}

Response Fields

Field	Type	Description
session_id	string	Unique checkout session identifier
deposit_address	string	Blockchain address to receive payment
amount	float	Payment amount
currency	string	Cryptocurrency (USDT/USDC)
network	string	Blockchain network
qr_code	string	Base64-encoded QR code image (data URI)
status	string	Payment status: pending
expires_at	string	ISO8601 expiration timestamp (24h)
instructions	object	Customer-facing payment instructions

---

Error Responses

400 Bad Request

Invalid network:

{
  "error": "Invalid network. Supported networks: BSC, ETH, POL, TRX, SOL"
}

Duplicate reference:

{
  "error": "Transaction reference 'ORDER-12345' already exists"
}

401 Unauthorized

{
  "error": "Invalid API key"
}

403 Forbidden

{
  "error": "Business account not active. Please complete KYC verification."
}

---

Important Notes

Transaction References

The reference field must be unique across all your transactions. Use order IDs, invoice numbers, or generate UUIDs.

Webhook Notifications

Always provide a callback_url to receive real-time payment notifications. See Webhooks.

Network Selection

Ensure the customer sends payment on the correct network. Sending USDT on the wrong network will result in lost funds!

---

Next Steps

After creating a checkout:

1. Display the deposit address and QR code to your customer
2. Show clear network instructions (e.g., "BSC BEP-20 only")
3. Monitor payment status
4. Handle webhook notifications

---

See Also

• Get Checkout Status
• Supported Chains
• QR Code Implementation