KuvarPay API
Home
Home
  1. Home
  • Overview
  • SDK Integration Guide
  • Webhooks Integration Guide
  • Subscriptions Guide
  • Transactions
    • Calculate required crypto amount for a fiat target
      POST
    • Create a new fiat transaction
      POST
    • Get transaction by ID
      GET
    • List transactions
      GET
    • Public transaction status by reference
      GET
    • Demo pay (sandbox/testing)
      POST
  • Checkout Sessions
    • Create a checkout session (returns authToken for SSE)
      POST
    • Get a checkout session
      GET
    • Receive payment status webhook for session
      POST
  • SSE
    • Subscribe to transaction updates (SSE)
      GET
    • Subscribe to session updates (SSE)
      GET
  • Currencies
    • List supported currencies
      GET
  • Sandbox
    • Simulate sandbox error scenarios for a transaction
      POST
    • Deliver a test webhook to a URL
      POST
    • List available sandbox error scenarios
      GET
    • Get sandbox environment info
      GET
    • Reset all sandbox data for your business (destructive)
      DELETE
  • Sandbox Simulator
    • Start the sandbox transaction simulator
      POST
    • Stop the sandbox transaction simulator
      POST
    • Get current status of the sandbox transaction simulator
      GET
    • Update simulator configuration
      PUT
    • Force execute a specific scenario for a transaction (testing only)
      POST
    • Force execute a specific scenario for a transaction (URL param)
      POST
    • List pending sandbox transactions available for simulation
      GET
    • Reset sandbox transactions to PENDING for testing
      POST
  • Invoices
    • Create a new invoice
    • Send invoice email to customer
  • Payment Links
    • Create a new payment link
  • Subscriptions
    • Create subscription checkout session
    • Get a subscription checkout session by UID
    • Confirm subscription checkout session
    • Get stablecoin currencies supported for subscriptions
    • Submit relay authorization for subscription
    • Create a new subscription
    • Get a subscription by UID
    • Get relay authorization status for a subscription
    • Update a subscription
    • Cancel a subscription
    • Create a new subscription plan
    • List subscription plans
    • Get a subscription plan by UID
    • Update a subscription plan
    • Create a price for a subscription plan
    • Get prices for a subscription plan
    • Update a subscription price
    • Create a subscription invoice
    • List subscription invoices
    • Create a metered subscription invoice
    • Get a subscription invoice by UID
    • Charge a subscription invoice
    • Get charge attempts for an invoice
  • Payment Fiat Rates
    • Get fiat rate for a specific currency
    • Get multiple fiat rates
    • Update NGN rate from CryptoCompare
    • Update all supported fiat rates
    • Get Flutterwave transfer rates (debug/testing)
    • List supported bank transfer and mobile money currencies
    • Clear the fiat rates cache
    • Get cache statistics
  • Transfer Fees
    • Get transfer fee for a specific amount and currency
    • Get optimal transfer fee (bank vs mobile money)
    • Get all stored transfer fees
    • Manually update transfer fees from Flutterwave
    • Get currencies supported for transfers
  • Schemas
    • Schemas
      • CalculatePaymentRequest
      • CalculatePaymentResponse
      • CreateTransactionRequest
      • Transaction
      • CreateTransactionResponse
      • CheckoutSessionCreateRequest
      • CheckoutSession
      • CheckoutSessionDetails
      • CheckoutSessionGetResponse
      • PaymentStatusWebhookPayload
      • SimpleAck
      • ErrorResponse
      • CurrenciesResponse
      • SandboxDeliveryResult
      • SandboxSimulateErrorRequest
      • SandboxSimulateErrorResponse
      • SandboxTestWebhookRequest
      • SandboxTestWebhookResponse
      • SandboxErrorScenariosResponse
      • SandboxInfoResponse
      • SandboxResetRequest
      • SandboxResetResponse
      • CreateInvoiceRequest
      • CreateSubscriptionCheckoutSessionRequest
      • InvoiceResponse
      • CreateSubscriptionCheckoutSessionResponse
      • CreateInvoiceResponse
      • ConfirmSubscriptionCheckoutSessionRequest
      • SendInvoiceEmailRequest
      • ConfirmSubscriptionCheckoutSessionResponse
      • SendInvoiceEmailResponse
      • SubscriptionCurrency
      • CreatePaymentLinkRequest
      • SubscriptionCurrenciesResponse
      • PaymentLinkResponse
      • CreatePaymentLinkResponse
      • CreateSubscriptionRequest
      • Subscription
      • UpdateSubscriptionRequest
      • SubscriptionResponse
      • CreatePlanRequest
      • UpdatePlanRequest
      • SubscriptionPlan
      • CreatePriceRequest
      • UpdatePriceRequest
      • SubscriptionPrice
      • PlanResponse
      • PlansListResponse
      • PriceResponse
      • PricesListResponse
      • SubscriptionInvoice
      • ChargeInvoiceRequest
      • ChargeAttempt
      • InvoicesListResponse
      • ChargeResponse
      • ChargeAttemptsListResponse
      • SubscriptionCheckoutSession
      • SubscriptionCheckoutSessionResponse
  1. Home

SDK Integration Guide

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):
Notes:
Use your client API key intended for client-side usage.
baseUrl is REQUIRED. Set it to KuvarPay Pay frontend host.
Production: https://pay.kuvarpay.com
Local testing (recommended): still use https://pay.kuvarpay.com

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
Previous
Overview
Next
Webhooks Integration Guide
Built with