Crypto Payment Gateway Integration Guide

The Crypto Payment Gateway allows businesses to accept cryptocurrency payments easily. The system generates a specialized checkout session with a unique deposit address or payment instructions.

Base URL: https://payments-api-dev-966260606560.europe-west2.run.app/api/v1

Authentication

All requests require a valid API Key in one of these headers:

• Primary: X-API-Key: <your_business_api_key>
• Alternative: Authorization: Bearer <your_business_api_key>
• Restriction: This API is available for Business Accounts only. Individual accounts cannot access the Crypto Payment Gateway.

---

1. Create Checkout Session

Initialize a payment session. This will generate a payment link and (optionally) a direct crypto deposit address.

• Endpoint: POST /checkout/create

Request

{
  "amount": 100.50,         // Fiat amount
  "currency": "USD",        // Fiat currency (USD, GBP, EUR, NGN)
  "customer_email": "customer@example.com",
  "customer_name": "John Doe",
  "reference": "YOUR_ORDER_REF_123", // Unique merchant reference
  "description": "Payment for Order #123",
  "callback_url": "https://your-site.com/webhook",
  "payment_method": "crypto", // "crypto" (default) or "fiat"
  "network": "BSC"          // Optional: Pre-select network (BSC, ETH, POL, SOL, TRON)
}

Response

{
  "session_id": "11fec830-6b48-4e1e-b504-eef2ad0bbc01",
  "payment_url": "https://payments-api-dev-966260606560.europe-west2.run.app/pay/11fec830-6b48-4e1e-b504-eef2ad0bbc01",
  "reference": "YOUR_ORDER_REF_123",
  "amount": 100.50,
  "currency": "USD",
  "status": "pending",
  "payment_method": "crypto",
  "deposit_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "network": "BSC",
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANS...",
  "instructions": {
    "instruction": "Please visit the payment URL to select your preferred cryptocurrency."
  },
  "expires_at": "2024-01-01T13:00:00Z"
}

---

2. Verify Payment

Check the status of a checkout session.

• Endpoint: GET /checkout/verify/:sessionId

Response

{
  "session_id": "cs_test_123...",
  "reference": "YOUR_ORDER_REF_123",
  "amount": 100.50,
  "currency": "USD",
  "status": "paid", // pending, paid, expired, failed
  "payment_method": "crypto",
  "paid_at": "2024-01-01T12:15:00Z",
  "expires_at": "2024-01-01T13:00:00Z"
}

---

3. List Payments

Retrieve a list of payment sessions.

• Endpoint: GET /checkout/list
• Query Params:
  • status: Filter by status (paid, pending, etc.)
  • payment_method: Filter by method
  • page: Page number (default 1)
  • limit: Items per page (default 50)

Response

{
  "payments": [
    {
      "session_id": "cs_test_123...",
      "reference": "REF_123",
      "amount": 100.50,
      "status": "paid",
      "created_at": "..."
    }
  ],
  "total": 15,
  "page": 1,
  "limit": 50
}

---

4. Get Payment Stats

Get aggregate statistics for your business payments.

• Endpoint: GET /checkout/stats

Response

{
  "total_volume_usd": 5000.00,
  "total_transactions": 50,
  "successful_transactions": 48,
  "success_rate": 96.0
}

---

Webhooks

When a payment is completed, we will send a POST request to your callback_url.

Payload (Event: payment.confirmed)

{
  "event": "payment.confirmed",
  "data": {
    "session_id": "cs_test_123...",
    "reference": "YOUR_ORDER_REF_123",
    "amount": 100.50,
    "currency": "USD",
    "status": "paid",
    "tx_hash": "0xABC...", // Blockchain Transaction Hash
    "network": "BSC"
  }
}