Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gosurge.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
Rendering the Checkout Widget

Once you have a sessionToken from your backend, you can launch the Surge widget on your frontend using our lightweight JavaScript SDK.

​
1. Include the SDK

Add the following script before the end of your <body> tag: 
<script src="https://consumer.gosurge.xyz/surge.js"></script>

​
2. Initialize and Open

Call init() and then openCheckout() with the token obtained from your server. 
// Initialize the SDK
const surge = SurgeConnect.init();

// Open the checkout modal
surge.openCheckout({
  sessionToken: "fcs_7a2b9d1e...", // The token from your backend

  onSuccess: ({ paymentPlanId }) => {
    // ✅ The customer has reviewed and confirmed the installment plan.
    // ⚠️ This does NOT mean payment has been collected yet.
    // Show a "Plan Confirmed — Processing" screen to the customer.
    console.log("Plan created:", paymentPlanId);
  },

  onCancel: () => {
    console.log("User closed the checkout widget.");
  },

  onError: (error) => {
    console.error("Surge Error:", error.message);
  }
});
Important: onSuccess fires when the customer confirms the installment plan, not when their card is charged. The initial deposit collection happens asynchronously. Always use Webhooks as the trigger to release goods.

​
Checking Customer Eligibility

Before showing the checkout button, you can check whether the logged-in customer is eligible to check out at your store. This lets you hide or disable the Surge option early rather than letting customers reach the widget only to be rejected.

​
Endpoint

GET /api/v1/checkout/sessions/{token}/eligibility
Authorization: Bearer <CUSTOMER_JWT>

​
Response — Eligible

{
  "ok": true,
  "data": {
    "eligible": true,
    "reason": null,
    "customer_score": 724,
    "customer_tier": "Surge Silver",
    "required_tier": "Surge Bronze"
  }
}

​
Response — Ineligible

{
  "ok": true,
  "data": {
    "eligible": false,
    "reason": "no_payment_method",
    "customer_score": 500,
    "customer_tier": "Surge Bronze",
    "required_tier": "Surge Bronze"
  }
}
Possible reason values:
ReasonMeaning
no_payment_methodCustomer has no linked card or bank account
delinquentCustomer has an active missed payment
tier_restrictedCustomer’s Surge Score tier is below the merchant’s minimum
insufficient_trust_tierCustomer has not completed identity verification

​
Session Constraints

When you fetch a checkout session (GET /api/v1/checkout/sessions/{token}), the response includes a constraints object that defines what plan options are available for this merchant: 
{
  "ok": true,
  "data": {
    "merchant_id": "mer_998877",
    "amount": 120000,
    "currency": "NGN",
    "title": "Apple AirPods Pro",
    "customer_email": "customer@example.com",
    "status": "pending",
    "expires_at": "2026-05-01T13:00:00Z",
    "constraints": {
      "allowed_frequencies": ["monthly", "weekly"],
      "max_weekly_duration": 12,
      "max_monthly_duration": 6,
      "min_upfront_pct": 20,
      "allowed_schedule_types": ["installment"]
    }
  }
}
The Surge widget reads these constraints automatically and only presents plan options that fall within the merchant’s configured limits. You do not need to enforce these yourself.