API Reference

Complete reference for all Checkout API endpoints.

Checkout Endpoints

List Checkouts

Retrieve a list of checkouts for your project.

GET /v1/checkouts

Headers

Header	Required	Description
x-api-key	Yes	Server Key (volr_server_...)

Query Parameters

Parameter	Type	Default	Description
status	string	-	Filter by status: PENDING, PAID, SETTLED, EXPIRED, etc.
take	number	20	Number of results (1-100)
skip	number	0	Offset for pagination
referenceId	string	-	Filter by your order ID

Response

{
  "ok": true,
  "data": [
    {
      "id": "cm5xyz123...",
      "status": "PAID",
      "amount": "10000000",
      "referenceId": "ORDER-12345",
      "createdAt": "2026-01-30T10:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 150,
    "take": 20,
    "skip": 0
  }
}

---

Get Checkout

Retrieve details of a specific checkout.

GET /v1/checkouts/:id

Headers

Header	Required	Description
x-api-key	Yes	Server Key (volr_server_...)

Response

Returns the full checkout object. See Create Checkout for field descriptions.

---

Get Checkout (Public)

Retrieve public checkout information for payment pages.

GET /c/:checkoutId

No authentication required. Returns limited public information suitable for displaying to customers.

Response

{
  "ok": true,
  "data": {
    "id": "cm5xyz123...",
    "chainId": 8453,
    "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "amount": "10000000",
    "depositAddress": "0xabc123...",
    "status": "PENDING",
    "expiresAt": "2026-01-30T11:00:00.000Z",
    "itemName": "Americano",
    "fiatAmount": "4.50",
    "fiatCurrency": "EUR",
    "merchantName": "Coffee Shop",
    "merchantLogoUrl": "https://...",
    "token": {
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6,
      "iconUrl": "https://..."
    },
    "network": {
      "name": "Base",
      "blockExplorerUrl": "https://basescan.org"
    },
    "totalPaid": "0",
    "isPaid": false,
    "paymentTxHash": null
  }
}

---

Verify Payment

Submit a transaction hash for payment verification.

POST /c/:checkoutId/verify

No authentication required. Customers can submit their transaction hash for faster payment confirmation.

Request Body

{
  "txHash": "0xdef456...",
  "chainId": 8453
}

Response

{
  "ok": true,
  "data": {
    "status": "DETECTED",
    "message": "Payment detected, awaiting confirmation"
  }
}

---

Cancel Checkout

Cancel a pending checkout.

POST /v1/checkouts/:id/cancel

Headers

Header	Required	Description
x-api-key	Yes	Server Key (volr_server_...)

Response

{
  "ok": true,
  "data": {
    "id": "cm5xyz123...",
    "status": "CANCELLED"
  }
}

경고

Only PENDING checkouts can be cancelled. Checkouts with detected or confirmed payments cannot be cancelled.

Checkout Status Flow

PENDING → DETECTED → PAID → SETTLED
    ↓         ↓
 EXPIRED   LATE_PAID
    ↓
CANCELLED

Status	Description
PENDING	Waiting for payment
DETECTED	Payment detected on-chain, awaiting confirmation
PAID	Payment confirmed
SETTLED	Funds transferred to merchant
EXPIRED	Checkout expired without payment
LATE_PAID	Payment received after expiry
CANCELLED	Cancelled by merchant