KuvarPay Web SDK Integration Guide

This guide shows how to embed KuvarPay's checkout modal on your website using the Web SDK. It lets your customers pay in crypto while you receive fiat payouts.

Overview

One line to include the SDK script

Initialize once with your publishable API key and business ID

Call KuvarPay.openPayment(...) for one-time payments

Call KuvarPay.openSubscription(...) for subscription approvals (supports FIXED and METERED billing)

Handle onSuccess, onCancel, and onError callbacks

Built-in idempotency for safe retries

Prerequisites

Before integrating the SDK, you need:

A KuvarPay Merchant Account — Sign up at merchant.kuvarpay.com and complete business verification.

API Keys — Go to your Merchant Dashboard → Settings → API Keys to generate:

A Publishable (Client) Key — used in the browser SDK (starts with rsp_test_ or rsp_live_).

A Secret Key — used only on your server (starts with kp_sk_test_ or kp_sk_live_). Never expose this in client-side code.

Business ID — Found in your Merchant Dashboard → Settings → Business Info.

Supported Currencies

KuvarPay supports the following settlement (fiat) currencies:

NGN (Nigerian Naira)

RWF (Rwandan Franc)

KES (Kenyan Shilling)

Customers can pay using popular cryptocurrencies including USDT, USDC, BNB, ETH, AVAX, and more across multiple networks (BSC, Ethereum, Avalanche, Polygon, etc.). Use the Currencies API to fetch the full list of supported crypto assets and networks dynamically.

1) Include the SDK Script

Or include with auto-initialization using data attributes (recommended when possible):

2) Initialize the SDK

Call KuvarPay.init as early as possible (e.g., on page load):

Notes:

Use a publishable API key intended for client-side usage.

baseUrl is REQUIRED. Set it to https://pay.kuvarpay.com.

In redirect mode (inlineCheckout: false), the SDK navigates away from your page; therefore onSuccess/onCancel/onError callbacks will not fire on the originating page.

Use your redirectUrl (provided during session creation) to bring the user back to a success page on your site once payment completes.

Trigger the modal when the customer clicks a button or when your flow requires payment.

Option A: Create New Session (Default Behavior)

Option B: Use Existing Session (Recommended for Server-Side Integration)

If you've already created a checkout session on your server, you can use it directly:

Attach to your checkout button:

4) How It Works

New Session Creation (Option A)

The SDK creates a Checkout Session on your behalf.

Built-in idempotency ensures repeated clicks or retries won't create duplicate sessions.

The secure checkout is displayed in a modal overlay on your page.

Existing Session Usage (Option B)

The SDK skips session creation and directly loads the existing session in the modal.

This prevents duplicate session creation when you've already created a session on your server.

Recommended for server-side integrations where you control session creation timing and parameters.

5) Payment Data Parameters

Parameter	Type	Required	Description
`amount`	number	Yes (new sessions)	Payment amount in the target fiat currency
`currency`	string	Yes (new sessions)	Settlement currency code (e.g., `'NGN'`, `'RWF'`, `'KES'`)
`description`	string	No	Payment description shown to the customer
`customerEmail`	string	No	Customer's email address
`customerName`	string	No	Customer's full name
`redirectUrl`	string	No	URL to redirect after successful payment
`callbackUrl`	string	No	Server-side webhook URL — KuvarPay will POST payment status updates to this URL
`expiresIn`	number	No	Session time-to-live in seconds. Default: `1800` (30 minutes)
`metadata`	object	No	Custom key-value data for your internal tracking. Stored with the session and transaction, accessible in dashboards and webhook payloads, but not displayed to the customer
`sessionId`	string	No	Existing session ID — skips session creation and opens the modal directly

Init options:

inlineCheckout (boolean): When false, the SDK redirects to the standalone checkout page after creating/using a session. Default true (embedded modal).

6) Options and Callbacks

options.theme: 'light' | 'dark' (default 'light').

callbacks.onSuccess(sessionId): invoked when the payment session completes successfully.

callbacks.onCancel(): invoked when the user closes/cancels the modal.

callbacks.onError(error): invoked on network/validation failures.

Redirect mode considerations:

When inlineCheckout: false, callbacks will not run because the page navigates away to the standalone checkout.

Handle success/failure on your own route using the redirectUrl or server-side webhooks via callbackUrl.

7) Security Notes

Use only your publishable (client) API key on the frontend.

Keep secret keys on your server. Never embed secret keys in client code.

8) Troubleshooting

If the modal doesn't open, ensure KuvarPay.init ran without errors (check console if debug: true).

Verify your amount and currency are valid and within min/max limits configured on your KuvarPay account.

When using existing sessions, ensure the sessionId is valid and the session hasn't expired.

Server SDK (Backend Integration)

For server-side operations (verifying sessions, creating checkout sessions, fetching transaction status), use the KuvarPay Server SDK.

Constructor

Methods

`createCheckoutSession(data)` — Create a checkout session

Parameter	Type	Required	Description
`amount`	number	Yes	Payment amount
`currency`	string	Yes	Settlement currency (e.g., `'NGN'`)
`description`	string	No	Payment description
`customerEmail`	string	No	Customer's email
`customerName`	string	No	Customer's name
`redirectUrl`	string	No	Redirect URL after payment
`callbackUrl`	string	No	Webhook URL for status updates
`expiresIn`	number	No	Session TTL in seconds (default `1800`)
`metadata`	object	No	Custom key-value data
`businessId`	string	No	Override the default business ID

Returns: { sessionId, authToken?, approvalUrl?, raw }

`verifyPayment(sessionId)` — Verify a payment

Returns: { verified, status, sessionId, transactionId, metadata, raw }

`getSessionStatus(sessionId)` — Get session details

Returns: { sessionId, status, transactionId, metadata, raw }

`getTransactionStatus(transactionId)` — Get transaction details

Returns: { transactionId, status, metadata, raw }

`createSubscriptionCheckoutSession(data)` — Create a subscription session

Returns: { sessionId, approvalUrl?, raw }

`getSubscription(subscriptionId)` — Get subscription details

`cancelSubscription(subscriptionId)` — Cancel subscription

`createMeteredInvoice(subscriptionId, data)` — Create a metered invoice

Example Usage

Node (ESM) example:

Security notes:

Keep SECRET keys server-side only. Never expose them in client-side code.

Always use HTTPS in production.

Prefer server-side verification to confirm final payment states like COMPLETED.

End-to-End Integration Example

This shows the recommended flow: create the session on your server, pass the sessionId to the frontend, open the modal, and verify on your server.

Step 1: Server — Create the checkout session

Step 3: Server — Verify the payment

Subscription Integration

The SDK also supports embedded subscription approvals via KuvarPay.openSubscription(...). This loads the subscription approval UI and communicates status back to your page using callbacks, similar to one-time payments.

Redirect (Non-Embedded) Subscription Approval

When inlineCheckout: false is set at init, openSubscription(...) will redirect to the standalone approval page instead of opening a modal.

As with payments, callbacks will not fire on the original page because the browser navigates away; use your return routes or server-side notifications to update user state.

Option A: Use Existing Subscription Session

If you have already created a subscription checkout session on your backend (recommended), you can pass either the session ID or the approval URL returned by your backend. When both are provided, the SDK will prefer the approval URL.

Option B: Create New Session From the Browser (Metered-only)

If you prefer to let the SDK create the session from the browser, pass the required metered parameters.

2) Callback Events

The SDK handles all communication between the subscription modal and your page automatically. Use the callbacks provided to openSubscription(...) to respond to events:

Success — fired when the subscription is successfully approved/activated

Error — fired when approval fails (insufficient funds, network errors, authorization issues, etc.)

Cancel — fired when the user cancels/closes the approval flow

3) Parameters for `openSubscription(...)`

Required for new session creation (metered-only):

customer — { email: string; firstName: string; lastName: string }

expectedUsage — { amount: number; currency: string } (REQUIRED)

strategy — 'conservative' | 'moderate' | 'liberal' | 'custom' (REQUIRED)

customMultiplier — number (REQUIRED if strategy is 'custom', must be > 0)

Optional:

metadata — object (e.g., { planName, planDescription })

sessionId — use when you already have a session created (skip creation)

approvalUrl — alternatively, pass the approval URL returned by your backend

options.theme — 'light' | 'dark'

businessId — optional per-call override; SDK will use the businessId provided at KuvarPay.init(...) if not specified

Callbacks:

onSuccess(result) — subscription confirmed; result typically includes { sessionId, subscriptionId, status, txHash? }

onCancel() — closed/cancelled

onError(error) — any failure in session creation or approval flow

Verifying Session Status Programmatically

If you need to confirm whether a checkout session completed successfully (or fetch its latest status/details), the SDK provides a helper:

Notes:

The response includes the current session status (PENDING, COMPLETED, etc.).

This is useful in redirect flows where you land on a confirmation page and want to double-check the final status.

Subscription Invoices (Client-Side Helper)

For existing subscriptions, you may need to generate usage-based invoices programmatically. The SDK provides helpers:

KuvarPay.createSubscriptionInvoice(subscriptionId, data) — create an invoice immediately or scheduled based on chargeSchedule

KuvarPay.scheduleSubscriptionInvoice(subscriptionId, data) — convenience wrapper that enforces a future dueDate and sets chargeSchedule: 'SCHEDULED'

For backward compatibility, KuvarPay.createMeteredInvoice(...) remains available as an alias.

Notes:

The SDK does not automatically create invoices after subscription approval. Merchants decide when to invoice.

For trials, you can either:

Schedule the invoice for after the trial ends using chargeSchedule: 'SCHEDULED' and a dueDate (Unix seconds);

Or create the invoice on the day the trial expires with chargeSchedule: 'IMMEDIATE'.

SDK Versioning and Notes

New in this version:

Metadata support for payments: Pass a metadata object in openPayment(...) or createCheckoutSession(...) to attach custom key-value data to sessions and transactions. Metadata is stored server-side, included in webhooks and dashboards, but not shown to customers on the payment page.

Metered-only subscription creation parameters (expectedUsage, strategy, customMultiplier).

Client-side helper to create subscription invoices for existing subscriptions (alias: createMeteredInvoice).

New helper: KuvarPay.getSessionStatus(sessionId) to verify the latest status of a checkout session.

Backward-compatible: Passing sessionId to openSubscription continues to work as before.

Auto-initialization: If your script tag includes data-api-key, data-business-id, and data-base-url, the SDK will initialize itself automatically.

SDK Integration Guide

KuvarPay Web SDK Integration Guide#

Overview#

Prerequisites#

Supported Currencies#

1) Include the SDK Script#

2) Initialize the SDK#

3) Open the Payment Modal#

Option A: Create New Session (Default Behavior)#

Option B: Use Existing Session (Recommended for Server-Side Integration)#

4) How It Works#

New Session Creation (Option A)#

Existing Session Usage (Option B)#

5) Payment Data Parameters#

6) Options and Callbacks#

7) Security Notes#

8) Troubleshooting#

Server SDK (Backend Integration)#

Constructor#

Methods#

createCheckoutSession(data) — Create a checkout session#

verifyPayment(sessionId) — Verify a payment#

getSessionStatus(sessionId) — Get session details#

getTransactionStatus(transactionId) — Get transaction details#

createSubscriptionCheckoutSession(data) — Create a subscription session#

getSubscription(subscriptionId) — Get subscription details#

cancelSubscription(subscriptionId) — Cancel subscription#

createMeteredInvoice(subscriptionId, data) — Create a metered invoice#

Example Usage#

End-to-End Integration Example#

Step 1: Server — Create the checkout session#

Step 2: Frontend — Open the modal with the sessionId#

Step 3: Server — Verify the payment#

Subscription Integration#

Redirect (Non-Embedded) Subscription Approval#

1) Open the Subscription Modal#

Option A: Use Existing Subscription Session#

Option B: Create New Session From the Browser (Metered-only)#

2) Callback Events#

3) Parameters for openSubscription(...)#

Verifying Session Status Programmatically#

Subscription Invoices (Client-Side Helper)#

SDK Versioning and Notes#

KuvarPay Web SDK Integration Guide

Overview

Prerequisites

Supported Currencies

1) Include the SDK Script

2) Initialize the SDK

3) Open the Payment Modal

Option A: Create New Session (Default Behavior)

Option B: Use Existing Session (Recommended for Server-Side Integration)

4) How It Works

New Session Creation (Option A)

Existing Session Usage (Option B)

5) Payment Data Parameters

6) Options and Callbacks

7) Security Notes

8) Troubleshooting

Server SDK (Backend Integration)

Constructor

Methods

`createCheckoutSession(data)` — Create a checkout session

`verifyPayment(sessionId)` — Verify a payment

`getSessionStatus(sessionId)` — Get session details

`getTransactionStatus(transactionId)` — Get transaction details

`createSubscriptionCheckoutSession(data)` — Create a subscription session

`getSubscription(subscriptionId)` — Get subscription details

`cancelSubscription(subscriptionId)` — Cancel subscription

`createMeteredInvoice(subscriptionId, data)` — Create a metered invoice

Example Usage

End-to-End Integration Example

Step 1: Server — Create the checkout session

Step 2: Frontend — Open the modal with the sessionId

Step 3: Server — Verify the payment

Subscription Integration

Redirect (Non-Embedded) Subscription Approval

1) Open the Subscription Modal

Option A: Use Existing Subscription Session

Option B: Create New Session From the Browser (Metered-only)

2) Callback Events

3) Parameters for `openSubscription(...)`

Verifying Session Status Programmatically

Subscription Invoices (Client-Side Helper)

SDK Versioning and Notes