Quickstart

Step 1 — Get your API key

Sign up at merchant.gosurge.xyz/register.
After your account is approved, the Surge team enables API access for your account.
Log in to your merchant dashboard, go to Settings → API Keys, and click Generate API Key.
Copy the key immediately — it is shown once. Note your Merchant ID (mer_...) on the same page.

Never hard-code your API key in source files. Use environment variables and never commit them to git.

Step 2 — Create a checkout session (backend)

Your server calls Surge to create a short-lived checkout session tied to the order. Pass the session token to your frontend to open the widget.

const express = require('express');
const { v4: uuidv4 } = require('uuid');

const app = express();

// ⚠️ Register the webhook route BEFORE app.use(express.json())
// so Express does not consume the raw body before signature verification.
// The full handler is defined below — JavaScript hoists function declarations.
app.post('/webhooks/surge', express.raw({ type: 'application/json' }), handleSurgeWebhook);

// Global JSON middleware for all other routes
app.use(express.json());

// --- Checkout session endpoint ---
// Called by your frontend when the customer clicks "Buy Now, Pay Later"
app.post('/api/surge-checkout', async (req, res) => {
  const { amount, title, orderReference, customerEmail } = req.body;

  try {
    const idempotencyKey = uuidv4();

    const response = await fetch('https://api.gosurge.xyz/api/v1/checkout/sessions', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.SURGE_API_KEY}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': idempotencyKey,
      },
      body: JSON.stringify({
        merchant_id: process.env.SURGE_MERCHANT_ID,
        amount,           // in kobo — e.g. 120000 = ₦1,200.00
        currency: 'NGN',
        title,
        order_reference: orderReference,
        customer_email: customerEmail,
      }),
    });

    if (!response.ok) {
      const error = await response.json();
      return res.status(response.status).json({ error: error.detail ?? 'Checkout failed' });
    }

    const { data } = await response.json();
    res.json({ sessionToken: data.session_token });

  } catch (err) {
    res.status(500).json({ error: 'Failed to create checkout session' });
  }
});

app.listen(3000);

import os
import uuid
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

# --- Checkout session endpoint ---
@app.route('/api/surge-checkout', methods=['POST'])
def surge_checkout():
    body = request.get_json()

    response = requests.post(
        'https://api.gosurge.xyz/api/v1/checkout/sessions',
        headers={
            'Authorization': f'Bearer {os.environ["SURGE_API_KEY"]}',
            'Content-Type': 'application/json',
            'Idempotency-Key': str(uuid.uuid4()),
        },
        json={
            'merchant_id': os.environ['SURGE_MERCHANT_ID'],
            'amount': body['amount'],   # in kobo
            'currency': 'NGN',
            'title': body['title'],
            'order_reference': body['order_reference'],
            'customer_email': body.get('customer_email'),
        }
    )

    data = response.json()
    if not response.ok:
        return jsonify({'error': data.get('detail')}), response.status_code

    return jsonify({'sessionToken': data['data']['session_token']})

Environment variables you need:

.env

SURGE_API_KEY=surge_live_sk_...
SURGE_MERCHANT_ID=mer_...
SURGE_WEBHOOK_SECRET=whsec_...

All amounts are in kobo (Nigerian lowest denomination). ₦1,200.00 = 120000 kobo. Never pass naira values directly — divide by 100 to display to the customer.

Once your server returns the sessionToken, open the Surge checkout modal.

import { useCallback } from 'react';

// Add this once to your index.html:
// <script src="https://consumer.gosurge.xyz/surge.js"></script>

export default function BuyNowPayLaterButton({ product }) {
  const handleSurgeCheckout = useCallback(async () => {
    // 1. Ask your backend to create a checkout session
    const res = await fetch('/api/surge-checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        amount: product.priceKobo,       // e.g. 120000 = ₦1,200
        title: product.name,
        orderReference: `ORD-${Date.now()}`,
        customerEmail: product.customerEmail,
      }),
    });

    const { sessionToken, error } = await res.json();
    if (error || !sessionToken) {
      alert('Could not start checkout. Please try again.');
      return;
    }

    // 2. Open the Surge widget
    const surge = window.SurgeConnect.init();
    surge.openCheckout({
      sessionToken,

      onSuccess: ({ paymentPlanId }) => {
        // Plan confirmed — NOT yet charged. Show a pending state.
        window.location.href = `/orders/pending?ref=${paymentPlanId}`;
      },

      onCancel: () => {
        console.log('Customer closed the widget.');
      },

      onError: (err) => {
        console.error('Surge error:', err.message);
      },
    });
  }, [product]);

  return (
    <button onClick={handleSurgeCheckout}>
      Buy Now, Pay Later with Surge
    </button>
  );
}

'use client';

import { useEffect, useRef, useCallback } from 'react';

// Safely load the Surge SDK and track when it's ready
function useSurgeSDK() {
  const ready = useRef(false);

  useEffect(() => {
    if (typeof window === 'undefined') return;
    if ((window as any).SurgeConnect) { ready.current = true; return; }

    const script = document.createElement('script');
    script.src = 'https://consumer.gosurge.xyz/surge.js';
    script.async = true;
    script.onload = () => { ready.current = true; };
    document.body.appendChild(script);
  }, []);

  return ready;
}

export default function CheckoutButton({ priceKobo, title, orderRef }: {
  priceKobo: number;
  title: string;
  orderRef: string;
}) {
  const sdkReady = useSurgeSDK();

  const handleClick = useCallback(async () => {
    if (!sdkReady.current) {
      alert('Checkout is still loading. Please try again in a moment.');
      return;
    }

    const res = await fetch('/api/surge-checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ amount: priceKobo, title, orderReference: orderRef }),
    });
    const { sessionToken } = await res.json();

    const surge = (window as any).SurgeConnect.init();
    surge.openCheckout({
      sessionToken,
      onSuccess: ({ paymentPlanId }: { paymentPlanId: string }) => {
        window.location.href = `/orders/pending?plan=${paymentPlanId}`;
      },
      onCancel: () => {},
      onError: (err: { message: string }) => console.error(err.message),
    });
  }, [priceKobo, title, orderRef]);

  return <button onClick={handleClick}>Pay in installments</button>;
}

<!-- Include the SDK -->
<script src="https://consumer.gosurge.xyz/surge.js"></script>

<button id="surge-btn">Buy Now, Pay Later</button>

<script>
  document.getElementById('surge-btn').addEventListener('click', async () => {
    const res = await fetch('/api/surge-checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        amount: 120000,   // 120000 kobo = ₦1,200.00
        title: 'Apple AirPods Pro',
        orderReference: 'ORD-' + Date.now(),
      }),
    });

    const { sessionToken } = await res.json();

    const surge = SurgeConnect.init();
    surge.openCheckout({
      sessionToken,
      onSuccess: ({ paymentPlanId }) => {
        console.log('Plan confirmed:', paymentPlanId);
      },
      onCancel: () => console.log('Cancelled'),
      onError: (err) => console.error(err.message),
    });
  });
</script>

onSuccess fires when the customer confirms the plan, not when their deposit is charged. Always use the payment.success webhook (Step 4) as your trigger to fulfill the order.

Step 4 — Listen for webhooks

Surge sends a payment.success event to your configured webhook URL after the deposit is collected and the plan is activated.

Configure your webhook URL

In your merchant dashboard go to Settings → Webhooks and enter your endpoint URL. Set a strong random string as your Webhook Secret and save it to your SURGE_WEBHOOK_SECRET env var.

Handle the event

Node.js

// ⚠️ This function must be declared BEFORE app.use(express.json()) is called,
// and the route is registered at the top of the file (see Step 2).
// JavaScript function declarations are hoisted, so this works even though
// it appears later in the file.

const crypto = require('crypto');

function handleSurgeWebhook(req, res) {
  const signature = req.headers['x-surge-signature'];
  const expected = crypto
    .createHmac('sha256', process.env.SURGE_WEBHOOK_SECRET)
    .update(req.body)  // req.body is a Buffer when using express.raw()
    .digest('hex');

  // timingSafeEqual throws if buffers differ in length, so check first
  const sigBuf = Buffer.from(signature ?? '');
  const expBuf = Buffer.from(expected);
  if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(expBuf, sigBuf)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body.toString());

  if (event.eventType === 'payment.success') {
    const { orderReference, resourceId } = event.data;
    // ✅ Safe to fulfill the order now
    fulfillOrder(orderReference, resourceId);
  }

  res.status(200).send('OK');
}

Surge signs outbound webhooks with HMAC-SHA256 using your webhook_secret. The header is X-Surge-Signature. Return 200 OK immediately and process fulfillment asynchronously to avoid retry storms.

See the Webhooks guide for all event types and retry behaviour.

You’re done

Step	What you built
Step 1	Merchant account + API key
Step 2	Server endpoint that creates a checkout session
Step 3	Frontend button that opens the Surge widget
Step 4	Webhook handler to fulfill orders after payment

Next steps:

Check customer eligibility before showing the button
Create payment links for WhatsApp / social selling
Handle payment methods for returning customers

Getting Started

Guides

Step 1 — Get your API key

Step 2 — Create a checkout session (backend)

Step 3 — Open the widget (frontend)

Step 4 — Listen for webhooks

Configure your webhook URL

Handle the event

You’re done

​Step 1 — Get your API key

​Step 2 — Create a checkout session (backend)

​Step 3 — Open the widget (frontend)

​Step 4 — Listen for webhooks

​Configure your webhook URL

​Handle the event

​You’re done

Step 1 — Get your API key

Step 2 — Create a checkout session (backend)

Step 3 — Open the widget (frontend)

Step 4 — Listen for webhooks

Configure your webhook URL

Handle the event

You’re done