Checkout API Reference

Base URL: https://payments-api-dev-966260606560.europe-west2.run.app
Auth: X-API-Key header

---

Create a Payment Session

POST /api/v1/checkout/create

Creates a hosted crypto payment session. Returns a payment_url pointing to the hosted payment page. Requires an active API key, KYC approval, and a business account type.

POST /api/v1/checkout/create
X-API-Key: live_sk_...
Content-Type: application/json

Request Body

Field	Type	Required	Description
amount	number	✅	Payment amount (e.g. 100.00)
currency	string	✅	ISO 4217 fiat currency code (e.g. "USD", "EUR", "GBP")
reference	string	—	Your internal order reference
description	string	—	Human-readable payment description
customer_email	string	—	Customer's email address
customer_name	string	—	Customer's display name
callback_url	string	—	URL to redirect/notify on payment completion
payment_method	string	—	Defaults to "crypto"
metadata	object	—	Arbitrary key-value pairs attached to the session

Example:

{
  "amount": 100.00,
  "currency": "USD",
  "reference": "ORDER-001",
  "description": "Premium subscription — 1 month",
  "customer_email": "customer@example.com",
  "customer_name": "Alice Johnson",
  "callback_url": "https://yoursite.com/webhooks/payment",
  "metadata": {
    "order_id": "ord_abc123",
    "user_id": "usr_xyz789"
  }
}

Responses

201 Created — Session created

{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "payment_url": "https://payments-api-dev-966260606560.europe-west2.run.app/pay/a1b2c3d4-...",
  "amount": 100.00,
  "currency": "USD",
  "status": "pending",
  "expires_at": "2026-06-25T15:00:00Z"
}

402 Payment Required — Subscription expired or monthly transaction limit reached

{
  "error": "Monthly transaction limit reached. Please upgrade your plan.",
  "code": "TRANSACTION_LIMIT_EXCEEDED"
}

code is either SUBSCRIPTION_EXPIRED or TRANSACTION_LIMIT_EXCEEDED

403 Forbidden — Individual accounts cannot create checkout sessions (business only)

---

Verify Payment Session Status

GET /api/v1/checkout/verify/{sessionId}

Check whether a specific payment session has been paid. Use this for server-side order verification after your callback_url fires.

GET /api/v1/checkout/verify/a1b2c3d4-e5f6-7890-abcd-ef1234567890
X-API-Key: live_sk_...

Response 200 OK

{
  "session_id": "a1b2c3d4-e5f6-...",
  "reference": "ORDER-001",
  "amount": 100,
  "currency": "USD",
  "status": "paid",
  "payment_method": "crypto",
  "paid_at": "2026-06-25T14:12:33Z",
  "expires_at": "2026-06-25T15:00:00Z",
  "callback_url": "https://yoursite.com/webhooks/payment"
}

status	Meaning
pending	Session created, no payment received yet
paid	Payment confirmed on-chain — safe to fulfill
expired	Session timed out before payment
failed	Payment detected but failed to confirm

---

List Payment Sessions

GET /api/v1/checkout/list

Returns a paginated list of all payment sessions for your business.

GET /api/v1/checkout/list?status=paid&page=1&limit=50
X-API-Key: live_sk_...

Query Parameters

Parameter	Type	Default	Description
status	string	—	Filter by pending, paid, expired, failed
payment_method	string	—	Filter by payment method
page	integer	1	Page number
limit	integer	50	Results per page (max 100)

Response 200 OK

{
  "payments": [
    {
      "id": 1001,
      "session_id": "a1b2c3d4-...",
      "reference": "ORDER-001",
      "amount": 100,
      "currency": "USD",
      "status": "paid",
      "payment_method": "crypto",
      "network": "BSC",
      "customer_email": "customer@example.com",
      "customer_name": "Alice Johnson",
      "description": "Premium subscription",
      "paid_at": "2026-06-25T14:12:33Z"
    }
  ],
  "total": 243,
  "page": 1,
  "limit": 50
}

---

List Deposit Addresses

GET /api/v1/checkout/addresses

Returns all deposit addresses that have been assigned to checkout sessions. Useful for auditing and reconciliation.

GET /api/v1/checkout/addresses?currency=USDT&network=BSC&page=1
X-API-Key: live_sk_...

Query Parameters

Parameter	Type	Description
network	string	Filter by blockchain network
currency	string	USDT or USDC only
search	string	Search by address string
page	integer	Page number (default 1)
limit	integer	Results per page (default 50)

---

Payment Gateway Statistics

GET /api/v1/checkout/stats

Returns aggregated metrics for your payment gateway — total volume, success rate, network breakdown.

GET /api/v1/checkout/stats
X-API-Key: live_sk_...

---

Create a Refund

POST /api/v1/refunds

Initiates a refund for a paid checkout session. Supports full or partial refunds.

POST /api/v1/refunds
X-API-Key: live_sk_...
Content-Type: application/json

{
  "session_id": "a1b2c3d4-e5f6-...",
  "reason": "Customer requested cancellation",
  "amount": 50.00
}

Field	Type	Required	Description
session_id	string (UUID)	✅	The checkout session to refund
reason	string	✅	Reason for the refund
amount	number	—	Partial refund amount — omit for full refund

Response 201 Created — Refund initiated

Response 400 Bad Request — Session not refundable (not paid, already refunded, etc.)

---

List Refunds

GET /api/v1/refunds

GET /api/v1/refunds?page=1&limit=20
X-API-Key: live_sk_...

---

Get Refund by ID

GET /api/v1/refunds/{id}

GET /api/v1/refunds/ref_abc123
X-API-Key: live_sk_...

---

Hosted Payment Page (Public Checkout)

The hosted payment page handles network selection and QR code display for your customers. No integration required on your front end.

Render Hosted Payment Page

GET /pay/{uuid}

The payment_url in the checkout response points here. Customers land on a React-based UI that lets them:

1. Select a blockchain network (ETH, BSC, POL, TRX, SOL, BTC, etc.)
2. Select a currency (USDT, USDC, or native)
3. Scan the QR code or copy the deposit address
4. View real-time confirmation status

Get Session Details (Public)

GET /api/v1/checkout/{uuid}

Used by the hosted page to load session info without an API key. Also callable from your own custom payment UI.

GET /api/v1/checkout/a1b2c3d4-e5f6-...

Response 200 OK

{
  "session_id": "a1b2c3d4-...",
  "reference": "ORDER-001",
  "amount": 100,
  "currency": "USD",
  "status": "pending",
  "payment_method": "crypto",
  "expires_at": "2026-06-25T15:00:00Z",
  "business_name": "Acme Inc.",
  "callback_url": "https://yoursite.com/webhooks/payment"
}

Customer Selects Network

POST /api/v1/checkout/{uuid}/select-network

Called when the customer picks which blockchain they want to pay on. Returns the deposit address and QR code.

POST /api/v1/checkout/a1b2c3d4-.../select-network
Content-Type: application/json

{
  "network": "BSC",
  "currency": "USDT"
}

Supported network values: ETH, BSC, POL, TRX, SOL, BTC, LTC, BCH, XRP
Supported currency values: USDT, USDC, ETH, BNB, MATIC, TRX, SOL, BTC, LTC, BCH, XRP

Response 200 OK

{
  "address": "0x1a2b3c4d5e6f...",
  "network": "BSC",
  "currency": "USDT",
  "amount_crypto": "100.000000",
  "qr_code": "data:image/png;base64,iVBORw0KGgo...",
  "expires_at": "2026-06-25T15:00:00Z"
}

Force-Check Payment Status

GET /api/v1/checkout/{uuid}/verify-now

Triggers an immediate on-chain balance check — useful when you want to show the customer a real-time status check button.

GET /api/v1/checkout/a1b2c3d4-.../verify-now

Response 200 OK

{
  "status": "paid",
  "paid_at": "2026-06-25T14:12:33Z",
  "paid_amount": "100.00"
}

status	Meaning
pending	No deposit detected yet
paid	Fully confirmed
partial	Deposit received but underpaid
expired	Session timed out