Server Integration

Learn how to initialize a Surge checkout session from your backend and register as a merchant.

Merchant Registration

Before integrating, you need a Surge merchant account. You can register via the dashboard or the API.

Via Dashboard (Recommended)

Sign up at merchant.gosurge.xyz/register. Once approved, retrieve your Secret Key from Settings → API Keys.

Via API

POST /api/v1/auth/merchant/register

Request

{
  "email": "[e-mail]",
  "password": "your-password",
  "full_name": "Your Name",
  "business_name": "Your Store Name",
  "phone": "08012345678",
  "country": "NG"
}

Response

{
  "ok": true,
  "data": {
    "token": "eyJ...",
    "merchant_id": "mer_998877"
  }
}

New merchant accounts require approval before they can create live checkout sessions. You will be notified by email once your account is activated.

---

Creating a Checkout Session

Before rendering the checkout widget, your backend must initialize a transaction by creating a Checkout Session. This session is short-lived (30 minutes) and secures the transaction details server-side.

Endpoint

POST /api/v1/checkout/sessions

Request Headers

Header	Required	Description
Authorization	✅	Bearer <YOUR_SECRET_KEY>
Idempotency-Key	Recommended	A UUID v4 to prevent duplicate sessions on network retries.

Payload Parameters

Field	Type	Description
merchant_id	string	Your merchant ID from the dashboard.
amount	integer	Total amount in kobo (e.g., 120000 for ₦1,200.00).
currency	string	ISO 4217 currency code (e.g., NGN).
title	string	Product or order name shown in the widget.
order_reference	string	Your internal unique reference for this order.
customer_email	string	(Optional) Pre-fills the login form for the customer.

Request Example

curl -X POST https://api.gosurge.xyz/api/v1/checkout/sessions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "merchant_id": "mer_998877",
    "amount": 120000,
    "currency": "NGN",
    "title": "Apple AirPods Pro",
    "order_reference": "ORD-9912384",
    "customer_email": "[e-mail]"
  }'

Response — Success

{
  "ok": true,
  "data": {
    "session_token": "fcs_7a2b9d1e...",
    "expires_at": "2026-03-11T13:00:00Z"
  }
}

Error Responses

Status	Reason
404 Not Found	The merchant_id does not exist in our system.
403 Forbidden	The merchant account is not currently active.
400 Bad Request	The Idempotency-Key header is not a valid UUID.

Store the session_token returned from this request and pass it to the Frontend SDK in the next step.

---

Previewing a Payment Plan

Before completing checkout, you can preview what the installment schedule will look like for a given amount and plan configuration. This is useful for showing customers a breakdown before they confirm.

Endpoint

POST /api/v1/checkout/preview

Request

{
  "merchant_id": "mer_998877",
  "customer_id": "cust_xyz",
  "amount": 120000,
  "schedule_type": "monthly",
  "installment_count": 3
}

Response

{
  "ok": true,
  "data": {
    "schedule_type": "monthly",
    "installment_count": 3,
    "deposit_amount": 40000,
    "installment_amounts": [40000, 40000, 40000],
    "due_dates": ["2026-04-01", "2026-05-01", "2026-06-01"],
    "total_amount": 120000
  }
}

---

Idempotency

The POST /checkout/sessions endpoint supports the Idempotency-Key header to protect against duplicate requests caused by network timeouts, client retries, or double-clicks.

How it works

1. Generate a UUID v4 and attach it as the Idempotency-Key header on your request.
2. If your request times out or fails at the network layer, re-send the exact same request with the same Idempotency-Key.
3. Surge will return the original session — no duplicate session or double-charge will occur.
4. Keys expire after 24 hours. After expiry, the same key will create a fresh session.

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

const idempotencyKey = uuidv4(); // e.g. "550e8400-e29b-41d4-a716-446655440000"

// First attempt (or any retry) — safe to call multiple times
const response = await fetch('https://api.gosurge.xyz/api/v1/checkout/sessions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SURGE_SECRET_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': idempotencyKey,
  },
  body: JSON.stringify({
    merchant_id: 'mer_998877',
    amount: 120000,
    currency: 'NGN',
    title: 'Apple AirPods Pro',
    order_reference: 'ORD-9912384',
  }),
});

Generate a new UUID for each distinct order. Reusing the same key for a different order will return the original session, not a new one.

---

Payment Links

Payment links are reusable, shareable URLs that let customers check out without needing a server-side session. Ideal for sharing via WhatsApp, Instagram, or email.

Create a Payment Link

POST /api/v1/payment-links
Authorization: Bearer <YOUR_SECRET_KEY>

Request

{
  "merchant_id": "mer_998877",
  "title": "Nike Air Max 270",
  "amount": 85000,
  "currency": "NGN",
  "description": "Limited edition — sizes 40–45 available.",
  "redirect_url": "https://yourstore.com/thank-you"
}

Response

{
  "ok": true,
  "data": {
    "id": "pl_abc123",
    "slug": "aX8kP2mQ",
    "publicUrl": "https://consumer.gosurge.xyz/l/aX8kP2mQ",
    "title": "Nike Air Max 270",
    "amount": { "amount": 85000, "currency": "NGN" },
    "redirect_url": "https://yourstore.com/thank-you",
    "is_active": true,
    "created_at": "2026-05-01T10:00:00Z"
  }
}

If redirect_url is set, the customer is redirected there after a successful checkout instead of their Surge dashboard.

List Your Payment Links

GET /api/v1/payment-links/merchant/{merchant_id}
Authorization: Bearer <YOUR_SECRET_KEY>

Toggle a Link On/Off

PATCH /api/v1/payment-links/{id}/toggle
Authorization: Bearer <YOUR_SECRET_KEY>
Content-Type: application/json

{ "is_active": false }