Skip to main content
This guide assumes you’re familiar with the Pandabase API and have a store set up. If you haven’t already, complete the Quickstart first.

​
Enable onchain payments

Enable onchain payments for your store in the dashboard under Settings → Payment Methods → Onchain Payments.

​
Create a checkout session

Onchain payments work through the same checkout flow as card payments. When you create a checkout session, the customer can choose to pay with crypto at checkout. 
const response = await fetch(
  `https://api.pandabase.io/v2/stores/${storeId}/checkouts`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      items: [
        {
          name: "Pro License",
          amount: 4999,
          quantity: 1,
        },
      ],
    }),
  },
);

const { data } = await response.json();
// Redirect customer to data.checkout_url
No additional parameters are needed. If onchain payments are enabled on your store, the crypto option appears automatically at checkout.

​
Handle webhooks

Onchain payments fire the same webhook events as card payments. The data.order object includes onchain-specific fields: 
{
  "event": "PAYMENT_COMPLETED",
  "data": {
    "order": {
      "id": "ord_xxx",
      "status": "COMPLETED",
      "amount": 4999,
      "currency": "USD",
      "paymentMethod": "ONCHAIN",
      "onchain": {
        "chain": "ETH",
        "token": "USDC",
        "tokenAmount": "49.99",
        "txHash": "0xabc123...",
        "fromAddress": "0xdef456...",
        "toAddress": "0x789abc...",
        "confirmations": 12,
        "exchangeRate": "1.0001"
      }
    }
  }
}

​
Onchain-specific fields

FieldTypeDescription
chainstringBlockchain network (e.g. ETH, SOL, BTC)
tokenstringToken symbol (e.g. USDC, ETH, SOL)
tokenAmountstringAmount in the token’s native decimals
txHashstringOn-chain transaction hash
fromAddressstringCustomer’s wallet address
toAddressstringPandabase deposit address
confirmationsintegerNumber of block confirmations at the time of completion
exchangeRatestringUSD exchange rate at the time the payment was locked

​
Underpayment and overpayment

Crypto payments may not arrive in the exact expected amount due to wallet UI rounding or network fees.
ScenarioDefault behavior
Underpayment (within 1%)Accepted — the order is completed
Underpayment (over 1%)Payment marked as failed, customer refunded to their wallet
OverpaymentAccepted — excess amount is credited to your balance
You can configure the underpayment tolerance in your store settings.

​
Payment expiry

Once a customer selects a chain and token, they have 30 minutes to send the payment. The exchange rate is locked for this window. If no payment is detected within 30 minutes, the checkout session expires and the customer must start over.
The exchange rate lock protects both you and the customer from price volatility during the payment window.