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(...) to launch the modal
Handle onSuccess, onCancel, and onError callbacks
Built-in idempotency for safe retries
1) Include the SDK Script#
2) Initialize the SDK#
Call KuvarPay.init as early as possible (e.g., on page load):Use your client API key intended for client-side usage.
baseUrl is REQUIRED. Set it to KuvarPay Pay frontend host. 3) Open the Payment Modal#
Trigger the modal when the customer clicks a button or when your flow requires payment.Attach startCheckout() to your checkout button:4) How It Works Under the Hood#
The SDK creates a Checkout Session by calling your KuvarPay payment server (/api/checkout/create-session).
It sets and manages an idempotency key so repeated clicks or retries won’t create duplicate sessions.
It embeds the secure checkout in a modal (iframe) and communicates using postMessage for success/cancel events.
5) 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.
6) 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.
7) 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.
For local testing, ensure the payment server is reachable from the browser (CORS, correct host/port).
Modified at 2025-09-15 18:10:57
