📖 Integration Guide

Start Accepting Payments

Add payments to your website in 5 minutes. SDK v5.0

v5.0Binance CryptoHosted Progress

⚡ Quick Start — 3 Steps

1
🔑 Get API Keys
Register and copy keys from dashboard
2
📦 Create Order
Call our API from your server
3
💳 Open Checkout
Add SDK to your page and open modal

🎉 What's New in SDK v5.0

🌐
Hosted Checkout + ProgressNew
openHosted() opens payment in new tab with real-time progress tracking modal
Binance CryptoNew
USDT, BTC, ETH, BNB with Gmail auto-verification
Cancel ConfirmationNew
Beautiful confirmation UI when user tries to close modal
🌙
Dark ModeImproved
Auto-detects system preference, seamless theming
⏱️
Live StatusImproved
Real-time SSE updates with fallback polling
📱
Manual ReviewImproved
UPI offline mode with "I've Paid" button

Step 1 — Get Your API Keys

Create an account, then go to your Dashboard to find these keys:

pk_live_xxxxxxxx
Public KeyFrontend

Use in your frontend / SDK. Safe to expose in browser.

sk_live_xxxxxxxx
Secret KeyServer Only

Use ONLY on your server. Never put this in frontend code.

whsec_xxxxxxxx
Webhook SecretVerification

Use to verify webhook signatures on your server.

⚠️Never expose your Secret Key in frontend code, mobile apps, or public repositories.

Step 2 — Create Order (Your Server)

When a customer clicks "Buy" on your site, your server creates an order using the Secret Key:

your-server.js (Node.js example)
// This runs on YOUR backend — never in the browser

app.post('/api/create-order', async (req, res) => {
  const { amount, productName, userId } = req.body;

  const response = await fetch('https://YOUR_GATEWAY_URL/api/v1/orders', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer sk_live_YOUR_SECRET_KEY'  // Secret key
    },
    body: JSON.stringify({
      amount: amount,        // Amount in INR (e.g. 499)
      currency: 'INR',
      receipt: 'order_' + Date.now(),  // Your internal reference
      customer: {
        name: 'Customer Name',
        email: 'customer@email.com',
        phone: '9876543210'
      }
    })
  });

  const data = await response.json();

  // Send order_id back to your frontend
  res.json({
    order_id: data.data.id,        // e.g. "order_abc123"
    payment_id: data.data.payment_id
  });
});
💡
Response format:
{
  "success": true,
  "data": {
    "id": "order_abc123",
    "payment_id": "pay_xyz789",
    "amount": 499,
    "status": "created"
  }
}

Step 3 — Open Checkout (Frontend)

Add the SDK script tag and open the payment modal. The SDK handles everything — QR code, UPI apps, Razorpay, Binance crypto.

gateway.open()Inline popup modal
your-checkout-page.html
<!-- 1. Add PayGate SDK v5.0 -->
<script src="https://YOUR_GATEWAY_URL/sdk/pay.js"></script>

<!-- 2. Payment button -->
<button onclick="pay()">Pay ₹499</button>

<script>
async function pay() {
  // First, create order on YOUR server
  const res = await fetch('/api/create-order', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ amount: 499, productName: 'Pro Plan' })
  });
  const { order_id } = await res.json();

  // Then open PayGate checkout
  const gateway = new PayGate({
    key: 'pk_live_YOUR_PUBLIC_KEY',   // Public key (safe for frontend)
    order_id: order_id,                // From your server
    amount: 499,
    name: 'My Store',                  // Shows in modal header
    description: 'Pro Plan',           // Shows below name
    base_url: 'https://YOUR_GATEWAY_URL',  // Your gateway URL
    customer: {
      name: 'John Doe',
      email: 'john@example.com'
    },
    theme: {
      color: '#6C5CE7'                 // Brand color
    },

    // Called when payment succeeds
    handler: function(response) {
      console.log('Payment ID:', response.payment_id);
      console.log('Order ID:', response.order_id);
      console.log('Method:', response.method);
      console.log('Ref:', response.upi_ref);

      // Verify on your server, then show success to user
      verifyPayment(response);
    },

    // Called when user closes modal without paying
    modal: {
      ondismiss: function() {
        console.log('Payment cancelled');
      }
    }
  });

  // Open inline modal
  gateway.open();
}
</script>

Hosted Checkout with Progress Tracking

New in v5.0gateway.openHosted()

Opens payment page in a new tab while showing a progress-tracking modal in the current page. Perfect for complex checkouts or when you want users to have the full payment page experience.

Order Created
Instant
Awaiting Payment
Real-time updates
🎉
Complete
Auto-closes tab
Hosted checkout with progress
const gateway = new PayGate({
  key: 'pk_live_YOUR_PUBLIC_KEY',
  order_id: order_id,
  amount: 499,
  name: 'My Store',
  base_url: 'https://YOUR_GATEWAY_URL',
  
  handler: function(response) {
    // Called when payment completes
    console.log('Paid via:', response.method);
    window.location.href = '/success?order=' + response.order_id;
  },
  
  modal: {
    ondismiss: function() {
      console.log('Modal closed');
    }
  }
});

// Opens payment in new tab + shows progress modal here
gateway.openHosted();
💡
How it works:
  • Opens /pay/ORDER_ID in a new browser tab
  • Shows a progress modal in current page with live status
  • Polls order status every 3 seconds
  • Auto-closes payment tab when payment completes
  • Calls your handler with payment details

Choosing a Checkout Method

MethodCodeBest ForUser Experience
📱 Inline Modalgateway.open()Quick payments, SPA appsPopup over your page
🌐 Hosted + Progressgateway.openHosted()Complex flows, mobileNew tab + progress tracker
↗️ Full Redirectwindow.location.hrefServer-rendered sitesFull page redirect
Full redirect example
// For server-rendered sites, just redirect:
const payUrl = 'https://YOUR_GATEWAY_URL/pay/' + order_id + '?key=pk_live_xxx';
window.location.href = payUrl;

// User pays on hosted page, then redirects to your success_url
// (Configure success_url in dashboard or per-order)

Step 4 — Verify Payment (Your Server)

After the handler fires, always verify on your server before fulfilling the order:

your-server.js
app.post('/api/verify-payment', async (req, res) => {
  const { order_id, payment_id } = req.body;

  // Check with PayGate server
  const response = await fetch(
    'https://YOUR_GATEWAY_URL/api/v1/orders/' + order_id,
    {
      headers: {
        'Authorization': 'Bearer sk_live_YOUR_SECRET_KEY'
      }
    }
  );

  const data = await response.json();

  if (data.data.status === 'paid') {
    // ✅ Payment confirmed!
    // - Save to your database
    // - Send confirmation email
    // - Activate subscription
    // - Deliver product

    console.log('Paid via:', data.data.payment_method_used);
    // UPI: 'upi_qr'
    // Gateways: 'razorpay' | 'phonepe' | 'paytm'
    // Binance: 'binance_usdt_bep20' | 'binance_btc' | 'binance_eth' | 'binance_bnb'
    // Crypto: 'btc' | 'eth' | 'usdt_trc20' | 'sol'

    res.json({ verified: true });
  } else {
    res.json({ verified: false, status: data.data.status });
  }
});

Webhooks — Real-time Notifications

Set your webhook URL in the Dashboard. We send a POST request when payment succeeds. This is more reliable than the frontend handler alone.

your-server.js — Webhook handler
const crypto = require('crypto');

app.post('/api/payment-webhook', (req, res) => {
  const body = req.body;
  const signature = req.headers['x-gateway-signature'];
  const event = req.headers['x-gateway-event'];

  // 1. Verify signature
  const expected = crypto
    .createHmac('sha256', 'whsec_YOUR_WEBHOOK_SECRET')
    .update(JSON.stringify(body))
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // 2. Handle event
  if (event === 'payment.success') {
    console.log('Order:', body.order_id);
    console.log('Amount:', body.amount);
    console.log('Method:', body.payment_method);
    console.log('Ref:', body.upi_ref || body.binance_tx_hash);

    // Fulfill order, send email, etc.
  }

  res.json({ received: true });
});
Webhook Payload Example
{
  "event": "payment.success",
  "order_id": "order_abc123",
  "payment_id": "pay_xyz789",
  "amount": 499,
  "currency": "INR",
  "status": "paid",
  "payment_method": "binance_usdt_bep20",
  "upi_ref": null,
  "binance_tx_hash": "0x1234abcd...",
  "customer": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "paid_at": 1710856200000
}

React / Next.js Integration

PayButton.jsx
import { useState } from 'react';

const GATEWAY_URL = 'https://YOUR_GATEWAY_URL';
const PUBLIC_KEY = 'pk_live_YOUR_PUBLIC_KEY';

// Load SDK v5.0
function loadPayGate() {
  return new Promise((resolve, reject) => {
    if (window.PayGate) return resolve();
    const s = document.createElement('script');
    s.src = GATEWAY_URL + '/sdk/pay.js';
    s.onload = () => window.PayGate ? resolve() : reject('SDK not found');
    s.onerror = () => reject('Failed to load SDK');
    document.body.appendChild(s);
  });
}

export default function PayButton({ plan, user, useHosted = false }) {
  const [loading, setLoading] = useState(false);

  const handlePay = async () => {
    setLoading(true);

    try {
      // 1. Create order on YOUR server
      const res = await fetch('/api/create-order', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          amount: plan.price,
          planId: plan.id
        })
      });
      const { order_id } = await res.json();

      // 2. Load SDK
      await loadPayGate();

      // 3. Open checkout
      const gw = new window.PayGate({
        key: PUBLIC_KEY,
        order_id: order_id,
        amount: plan.price,
        name: 'My App',
        description: plan.name + ' Plan',
        base_url: GATEWAY_URL,
        customer: {
          name: user?.name || '',
          email: user?.email || ''
        },
        theme: { color: '#6C5CE7' },

        handler: async (response) => {
          // 4. Verify on your server
          await fetch('/api/verify-payment', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
              order_id: response.order_id,
              payment_id: response.payment_id,
              method: response.method
            })
          });

          alert('Payment successful! 🎉');
          window.location.reload();
        },

        modal: {
          ondismiss: () => setLoading(false)
        }
      });

      // Choose checkout method
      if (useHosted) {
        gw.openHosted();  // New tab + progress
      } else {
        gw.open();        // Inline modal
      }
    } catch (err) {
      alert('Error: ' + err.message);
      setLoading(false);
    }
  };

  return (
    <button onClick={handlePay} disabled={loading}>
      {loading ? 'Processing...' : `Pay ₹${plan.price}`}
    </button>
  );
}

SDK Options Reference

OptionTypeRequiredDescription
keystringYour public key (pk_live_xxx)
order_idstringOrder ID from Step 2
amountnumberAmount in INR
namestringStore name (shows in modal header)
descriptionstringProduct description
base_urlstringGateway URL (auto-detected from script src)
customer.namestringCustomer name
customer.emailstringCustomer email
customer.phonestringCustomer phone
theme.colorstringBrand color (default: #6C5CE7)
preferred_methodstringOpen specific tab: upi_qr, razorpay, binance, crypto
handlerfunctionCalled on successful payment
modal.ondismissfunctionCalled when user closes modal
SDK Methods
gateway.open()Opens inline modal popup
gateway.openHosted()Opens new tab + progress modalv5.0
gateway.close()Programmatically close modal

Payment Response (handler callback)

When payment succeeds, your handler function receives:

FieldExampleDescription
payment_idpay_abc123Unique payment identifier
order_idorder_xyz789Your order ID
amount499Amount paid (INR)
statuspaidAlways "paid" in handler
methodupi_qrPayment method used
upi_ref345678901234UPI reference (UPI payments)
Possible method values
📱 upi_qr💳 razorpay💜 phonepe💙 paytm🔶 binance🪙 usdt_trc20🪙 usdt_erc20 btc eth sol

Supported Payment Methods

All methods are enabled/disabled by the gateway admin. Your integration code stays the same regardless of which methods are active.

📱
UPI QR
QR scan + app deep links
💳
Razorpay
Cards, UPI, wallets, net banking
💜
PhonePe
PhonePe UPI gateway
💙
Paytm
Paytm wallet & UPI
v5.0
🔶
Binance
USDT, BTC, ETH, BNB
🪙
USDT
TRC20 / ERC20 / BEP20
Bitcoin
BTC on-chain
Ethereum
ETH on-chain
💡The SDK modal automatically shows only the methods that are enabled. You don't need to change your code when methods are toggled.

Binance Crypto Payments

New in v5.0

Accept crypto payments via Binance Pay with Gmail auto-verification. No manual confirmation needed when gateway admin has Gmail integration enabled.

🔶 Supported Coins
USDTBEP20 / TRC20BTCBitcoinETHEthereumBNBBSC
📧 Auto-Verification
Gateway monitors Binance email notifications and auto-confirms payments. No manual "I've Paid" needed.
Prefer Binance checkout
const gateway = new PayGate({
  key: 'pk_live_xxx',
  order_id: order_id,
  amount: 500,
  preferred_method: 'binance',  // Opens Binance tab first
  // ...
});

gateway.open();

Testing Your Integration

1
Register
Go to /register and create a merchant account.
2
Get Keys
Go to /dashboard → API Keys tab → copy Public Key and Secret Key.
3
Create Test Order
Terminal (curl)
curl -X POST https://YOUR_GATEWAY_URL/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY" \
  -d '{"amount":100,"customer":{"name":"Test","email":"test@test.com"}}'
4
Open Checkout
Use the order_id from above with the SDK to open the payment modal.
5
Pay
Scan QR code or use any payment method. Payment will be auto-detected.

Common Errors

401 UnauthorizedWrong API key. Check if you used pk_live_xxx (frontend) vs sk_live_xxx (server).
404 Not FoundWrong gateway URL or order_id doesn't exist.
403 ForbiddenOrder belongs to a different merchant.
410 GoneOrder has expired. Create a new one.
SDK not loadingCheck if YOUR_GATEWAY_URL/sdk/pay.js returns JavaScript (not 404).
API calls to wrong URLPass base_url in PayGate options to override auto-detection.
Binance not showingBinance methods must be enabled by admin in gateway settings.

Ready to integrate?

Get your API keys and start accepting payments today.