KuvarPay Merchant API – Comprehensive Overview

This document provides a complete overview of how to integrate with the KuvarPay Merchant API to accept crypto payments and receive fiat payouts in African markets. It explains authentication, idempotency, core payment flows, real-time status monitoring (SSE), sandbox testing, error handling, and best practices.

SDK for Easy Integration

KuvarPay provides an official SDK to simplify integration.
You can explore the SDK documentation here: SDK Integration Guide

Versioning and Base URLs

Invoice/Payment Link base URL: https://kuvarpay.com.

Other endpoint baseurl: https://payment.kuvarpay.com

Authentication

KuvarPay uses two authentication mechanisms, plus a session-scoped token for SSE.

API Key (ApiKeyAuth)

Header: x-api-key: <your_api_key>

Business ID

Header: x-business-id: <your_business_id>

Bearer JWT (for SSE only)

Header: Authorization: Bearer <session_authToken>

Obtained from the checkout session resource when created/fetched.

Notes

Always send both x-api-key and x-business-id for partner-facing endpoints (Transactions, Checkout Sessions, Currencies, etc.).

Use client key for calls originating from the browser/frontend and secret key for calls originating from your server/backend.

Invoice/Payment Link endpoints requires the secret key to be used.

if keys are used wrongly, requests will be rejected by the server.

SSE endpoints require the session-scoped JWT instead of x-api-key.

Idempotency

Use the Idempotency-Key header on POST requests to safely retry without creating duplicates.

Header: Idempotency-Key: <unique_key_per_request>

On retry with the same key, the server will return the original response (if still valid).

Metadata

You can attach custom key-value data to checkout sessions and transactions using the optional metadata field.

Pass metadata as a JSON object when creating a checkout session (POST /api/v1/checkout-sessions) or a transaction (POST /api/v1/transactions/create).

Metadata is stored with the session/transaction and returned in API responses, webhook payloads, and the merchant dashboard.

Metadata is not displayed to the customer on the payment page.

Use cases: linking payments to internal order IDs, tracking campaign sources, attaching plan details, or any custom merchant reference data.

Example:

{
  "metadata": {
    "order_id": "ORD-12345",
    "plan": "pro",
    "source": "checkout_page"
  }
}

Core Integration Flow

Below is the recommended high-level flow for a typical checkout.

Create a Checkout Session

Endpoint: POST /api/v1/checkout-sessions

Body includes the fiat target (toCurrency, toAmount) and an optional metadata object (arbitrary key-value pairs for your internal tracking — e.g., order IDs, plan names). Customer details (customerEmail, customerName) are required for production integrations but are supplied when creating the transaction (POST /api/v1/transactions/create) that links to this session, not during session creation.

Response contains the sessionId, initial status, and an authToken for SSE.

Fetch Supported Currencies and Networks

Endpoint: GET /api/v1/currencies

Required headers: x-api-key, x-business-id

Use the response to let the user select their preferred crypto fromCurrency and fromNetwork (and verify available fiat toCurrency). The crypto list includes a networks array per asset.

Create the Transaction (linked to the session)

Endpoint: POST /api/v1/transactions/create

Include: checkoutSessionId from step 1, the user-selected fromCurrency/fromNetwork, your fiat target (toCurrency, toAmount), and customer details (customerEmail, customerName).

Headers: x-api-key, x-business-id, and Idempotency-Key: <unique>

The response includes transaction details and a deposit address.

Track Session Status

Real-time (recommended): SSE stream

GET /api/v1/sse/session/{sessionId} with headers Accept: text/event-stream and Authorization: Bearer <authToken>

Receive server-sent events as the session status transitions (e.g., PENDING → ARMED → PROCESSING → COMPLETED)

Polling (fallback):

GET /api/v1/checkout-sessions/{sessionId} periodically (e.g., every 2–5 seconds with jitter/backoff)

React to Terminal States

Terminal statuses include COMPLETED, FAILED, EXPIRED, or CANCELLED.

Stop listening/polling and reconcile on your side (fulfill order, show error, retry, etc.).

Example SSE Connection

Event examples (data payloads are JSON strings):

event: session_update
id: 1
data: {"sessionId":"sess_123","status":"ARMED","updatedAt":"2025-01-01T12:00:15Z"}

id: 2
event: session_update
data: {"sessionId":"sess_123","status":"PROCESSING"}

id: 3
event: session_update
data: {"sessionId":"sess_123","status":"COMPLETED"}

Calculating Required Crypto Amount

Use POST /api/v1/transactions/calculate-payment to compute the crypto amount for a fiat target.

Required headers: x-api-key, x-business-id

Typical request body includes: fromCurrency, fromNetwork, toCurrency, and toAmount.

Creating a Transaction (Direct API Flow)

While most integrations use checkout sessions, you can create transactions directly:

POST /api/v1/transactions/create

Include Idempotency-Key to avoid duplicate submissions.

The response includes transaction details and a deposit address.

Customer Details (Required)

Required fields for production integrations:

customerEmail (must be a valid email format)

customerName (non-empty string)

Where to provide: Include these fields when creating the transaction via POST /api/v1/transactions/create (whether you link it to a previously created checkout session using checkoutSessionId or create a direct transaction).

Current enforcement status (as implemented today):

The POST /api/v1/transactions/create schema accepts customerEmail and customerName but does not mark them as required, and the service validates customerEmail only if provided. If you omit these fields, the API currently does not return a validation error (no 400 is thrown for their absence); they will be stored as null and certain features (e.g., direct customer notifications) may be skipped.

Checkout Session creation (POST /api/v1/checkout-sessions) does not accept customer fields; you must supply them when creating the linked transaction.

Recommendation: Always include customerEmail and customerName for every production transaction to enable notifications, risk checks, and downstream operations. Enforcement may become strict in a future revision.

Example request:

POST /api/v1/transactions/create
Headers:
  x-api-key: <api_key>
  x-business-id: <business_id>
  Idempotency-Key: <unique>
Body:
{
  "fromCurrency": "USDT",
  "fromNetwork": "bsc",
  "toCurrency": "NGN",
  "toAmount": 10000,
  "checkoutSessionId": "sess_123",
  "customerEmail": "buyer@example.com",
  "customerName": "Jane Doe",
  "metadata": {
    "order_id": "ORD-12345",
    "source": "website"
  }
}

Webhooks

You can configure webhooks to receive asynchronous events (e.g., completed transactions, payout updates).

Webhook payloads include any metadata you attached during session or transaction creation, so you can reconcile events with your internal records without additional API calls.

Ensure your endpoint validates signatures (if enabled) and is idempotent.

Sandbox and Testing

The sandbox lets you simulate end-to-end flows without real funds.

Use your sandbox API key and business ID.

Notable endpoints:

POST /api/v1/sandbox-simulator/start — start the simulator

POST /api/v1/sandbox-simulator/stop — stop the simulator

GET /api/v1/sandbox-simulator/status — view simulator status/config

POST /api/v1/sandbox-simulator/config — update probabilities and timings

POST /api/v1/sandbox-simulator/force-scenario — force a scenario for the next eligible transaction

POST /api/v1/sandbox-simulator/force/{transactionId} — force a scenario for a specific transaction

GET /api/v1/sandbox-simulator/pending-transactions — list pending sandbox transactions (paginate)

POST /api/v1/sandbox-simulator/reset-transactions — reset transactions back to PENDING (with confirm flag)

Tips

Use the simulator to test success/failure paths, partial/excess payments, compliance holds, and timeouts.

Validate that your webhook processing is idempotent by replaying events.

Error Handling and Retries

Always handle 4xx (client) and 5xx (server) errors.

Implement retries for transient errors with exponential backoff (e.g., network issues, 5xx).

For POST requests, use Idempotency-Key to ensure safe retries.

Security Best Practices

Treat API keys and tokens as secrets — never log them.

Use HTTPS-only endpoints and validate TLS certificates.

Validate and sanitize all inputs on your side even if server-side validation exists.

Use allowlists for callbacks/webhook targets in your infrastructure.

Rate Limiting and Backoff

Respect any rate limits indicated by response headers or errors.

Implement client-side backoff and jitter when polling or retrying.

Observability

Log request IDs, correlation IDs, and timestamps to help trace issues.

Capture SSE events and state transitions in your logging for debugging.

Support

For production support, contact the KuvarPay team on integration@kuvarpay.com.

For sandbox/trial access, register on KuvarPay Merchant to generate your api key.

Overview

KuvarPay Merchant API – Comprehensive Overview#

SDK for Easy Integration#

Versioning and Base URLs#

Authentication#

Idempotency#

Metadata#

Core Integration Flow#

Example SSE Connection#

Calculating Required Crypto Amount#

Creating a Transaction (Direct API Flow)#

Customer Details (Required)#

Webhooks#

Sandbox and Testing#

Error Handling and Retries#

Security Best Practices#

Rate Limiting and Backoff#

Observability#

Support#