Skip to main content

​
Merchant Registration

Before integrating, you need a Surge merchant account. You can register via the dashboard or the API. Sign up at merchant.gosurge.xyz/register. Once approved, log in to find your Merchant ID under Settings → API Keys.
1

Register

Go to merchant.gosurge.xyz/register and fill in your business details.
2

Wait for approval

New accounts are reviewed within 24 hours. You’ll receive an email when approved.
3

Generate your API key

Once approved, the Surge team enables API access for your account. Log in to the merchant dashboard, go to Settings → API Keys, and click Generate API Key. Copy the key immediately — it is only shown once. Your Merchant ID (mer_...) is shown on the same page.
Store your credentials as environment variables (SURGE_API_KEY, SURGE_MERCHANT_ID) and never commit them to version control.

​
Via API

POST /api/v1/auth/merchant/register
Request 
{
  "email": "you@yourstore.com",
  "password": "your-password",
  "business_name": "Your Store Name",
  "business_url": "https://yourstore.com"
}
Response 
{
  "ok": true,
  "data": {
    "merchantId": "mer_998877",
    "status": "pending",
    "email": "you@yourstore.com"
  }
}
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

​
Authentication

Authenticate with your API key on every request: 
Authorization: Bearer surge_live_sk_...

​
Request Headers

HeaderRequiredDescription
Authorization✅Bearer surge_live_sk_... (your Surge API key)
Idempotency-KeyRecommendedA UUID v4 to prevent duplicate sessions on network retries.

​
Payload Parameters

FieldTypeDescription
merchant_idstringYour merchant ID from the dashboard.
amountintegerTotal amount in kobo (e.g., 120000 for ₦1,200.00).
currencystringISO 4217 currency code (e.g., NGN).
titlestringProduct or order name shown in the widget.
order_referencestringYour internal unique reference for this order.
customer_emailstring(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 surge_live_sk_..." \
  -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": "customer@example.com"
  }'

​
Response — Success

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

​
Error Responses

StatusReason
404 Not FoundThe merchant_id does not exist in our system.
403 ForbiddenThe merchant account is not currently active.
400 Bad RequestThe 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_API_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 are reusable, shareable URLs that let customers check out without needing a server-side session. Ideal for sharing via WhatsApp, Instagram, or email. 
POST /api/v1/payment-links
Authorization: Bearer surge_live_sk_...
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",
    "merchantId": "mer_998877",
    "title": "Nike Air Max 270",
    "amount": { "amount": 85000, "currency": "NGN" },
    "redirectUrl": "https://yourstore.com/thank-you",
    "isActive": true,
    "createdAt": "2026-05-01T10:00:00Z",
    "updatedAt": "2026-05-01T10:00:00Z"
  }
}
All fields in the payment link response use camelCase (redirectUrl, isActive, createdAt, merchantId, publicUrl). The response schema uses Pydantic’s alias_generator=to_camel.
If redirectUrl is set, the customer is redirected there after a successful checkout instead of their Surge dashboard. 
GET /api/v1/payment-links/merchant/{merchant_id}
Authorization: Bearer surge_live_sk_...

PATCH /api/v1/payment-links/{id}/toggle
Authorization: Bearer surge_live_sk_...
Content-Type: application/json

{ "is_active": false }