Ir al contenido
SanPay Docs

Guía de Integración

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 using your test API key (starts with sk_test_):

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