Skip to content
SanPay Docs

Integration Guide

Integration Guide

Learn how to accept crypto payments in your application. This guide covers everything from creating your first payment to handling webhooks.

Prerequisites

  • A SanPay account (sign up here)
  • An API key from the dashboard

Integration Options

API Integration

Full control with our REST API. Best for custom checkout experiences.

Hosted Checkout

Pre-built payment pages. The fastest way to start accepting crypto.

Option 1: API Integration

Full control over the payment experience.

  1. Create a Payment Request 

    curl -X POST https://api.sanpay.io/v1/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.99",
    "currency": "USD",
    "cryptoCurrency": "BTC",
    "description": "Pro Plan Subscription",
    "orderId": "order_12345",
    "redirectUrl": "https://your-app.com/thank-you",
    "webhookUrl": "https://your-app.com/webhooks/sanpay"
  }'
     Response: 
    {
  "id": "pay_abc123",
  "status": "pending",
  "amount": "49.99",
  "currency": "USD",
  "cryptoAmount": "0.00125000",
  "cryptoCurrency": "BTC",
  "address": "bc1qxy2kgdygjrsqvzq3rj...",
  "qrCode": "data:image/png;base64,...",
  "expiresAt": "2024-01-15T11:30:00Z"
}

  2. Display Payment Details

    Show the payment address and QR code to your customer:

    <div class="payment-container">
  <h2>Pay with Bitcoin</h2>
  <img src="${payment.qrCode}" alt="Payment QR Code" />
  <p>Send exactly <strong>${payment.cryptoAmount} BTC</strong></p>
  <code>${payment.address}</code>
  <p>Payment expires in 30 minutes</p>
</div>

  3. Handle Payment Webhook

    Process the webhook when payment is confirmed:

    app.post('/webhooks/sanpay', async (req, res) => {
  const { type, data } = req.body;
  
  if (type === 'payment.confirmed') {
    const { orderId, status } = data;
    
    // Update order status in your database
    await db.orders.update({
      where: { id: orderId },
      data: { status: 'paid' }
    });
    
    // Send confirmation email
    await sendOrderConfirmation(orderId);
  }
  
  res.status(200).send('OK');
});

  4. Redirect Customer

    After payment, we redirect the customer to your redirectUrl with payment status:

    https://your-app.com/thank-you?payment_id=pay_abc123&status=confirmed

Option 2: Hosted Checkout

The fastest way to start accepting payments. We handle the entire checkout UI.

  1. Create Checkout Session 

    curl -X POST https://api.sanpay.io/v1/checkout/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.99",
    "currency": "USD",
    "description": "Pro Plan Subscription",
    "orderId": "order_12345",
    "successUrl": "https://your-app.com/thank-you",
    "cancelUrl": "https://your-app.com/checkout"
  }'

  2. Redirect to Checkout 

    {
  "id": "cs_xyz789",
  "url": "https://checkout.sanpay.io/cs_xyz789"
}

    Redirect your customer to the url:

    window.location.href = session.url;

  3. Customer Completes Payment

    Our hosted checkout handles:

    • Currency selection
    • QR code display
    • Real-time payment status
    • Expiration countdown

  4. Customer Returns

    After payment (or cancellation), we redirect to your success or cancel URL.

Testing

Enable test mode by setting isTestnet: true in your payment request, or use your test API key:

curl -X POST https://api.sanpay.io/v1/payments \
  -H "Authorization: Bearer sk_test_YOUR_TEST_KEY" \
  ...

Test payments are processed on Bitcoin testnet and Ethereum Sepolia.

Next Steps