Skip to main content

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:

2. Initialize and Open

Call init() and then openCheckout() with the token obtained from your server.
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

This endpoint is called from the Surge widget / consumer app context, not from your merchant server. It requires a customer JWT (the Surge account token for the shopper, not your merchant token). Most merchant storefronts do not call this directly — the widget handles eligibility internally. Use this only if you are building a custom checkout experience where the customer is already logged into Surge.
Once a customer is authenticated with Surge, you can check their eligibility to surface or hide the BNPL option before opening the widget.

Endpoint

Response — Eligible

Response — Ineligible

Possible reason values:

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:
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.