Checkout SDK

Learn how to harness our collections of tools when integrating payment into your application

Kidapay Checkout SDK

Server-side calls to this API must be done from a secured and trusted environment (e.g. via your backend server, not directly from frontend web).

The Kidapay Checkout SDK provides a collection of methods that allow you accept payment in your website or application.

Introduction

The KidaPay Checkout SDK is an official JavaScript/TypeScript toolkit designed to let developers seamlessly integrate KidaPay’s cryptocurrency payment solutions into their websites or applications. It provides methods for initiating payments, with customizable UI components and robust backend communication — all while handling the complexities of blockchain transactions behind the scenes.

Installation

KidaPay Checkout SDK can be included in your application via CDN, NPM or Yarn:

CDN
NPM
Yarn

<script src="https://unpkg.com/kidapay-checkout-sdk@latest/dist/index.umd.js"></script>

npm install kidapay-checkout-sdk

yarn add kidapay-checkout-sdk

If you used NPM or Yarn, ensure you import the library as shown below:

Initialization

// Add for NPM, Yarn
import { Kidapay } from 'kidapay-checkout-sdk';

 const kidapay = new Kidapay();

Kidapay object

The Kidapay object gives access to the methods and interfaces available in Kidapay Checkout SDK. It exposes methods, alongside configuration options that can help you accept crypto payment seamlessly in your web application. The methods exposed by the Kidapay object include:

checkout(options: CheckoutOptions): Creates and opens a checkout session (browser only).
createCheckout(request: CreateCheckoutRequest): Creates a checkout session (backend).
getCheckout(checkoutId: string): Retrieves checkout details.

Callbacks

The KidaPay object also exposes callbacks that can be used to monitor certain states during the lifecycle of a transaction.

onSuccess

This is called when the customer successfully completes a transaction. It returns an instance of a transaction object:

Option	Type	Description
id	String	Unique identifier for the checkout session.
order_id	String	Unique identifier for the merchant’s order associated with this payment.
pay_amount	String	Amount the customer paid (in the crypto currency they selected).
pay_currency	String	The cryptocurrency used for payment (e.g., BTC, ETH, USDT).
pay_network	String	The blockchain network used for the payment (e.g., Ethereum, Algo, BTC).
receieve_currency	String \| null	The currency the merchant will receive after conversion, if applicable (e.g., USDT).
receieve_amount	String \| null	The amount the merchant will receive in the settlement currency.
address	String	The crypto wallet address to which the customer sent the payment.
status	String	Current payment status (e.g., NEW, SUCCESSFUL, FAILED, EXPIRED, CANCELLED, REFUNDED, PARTIALLY_PAID).

onError

This is called when there is an issue loading the transaction.

interface PaymentError {
  code: string;        // Short error code (e.g., "INVALID_ADDRESS")
  message: string;     // Human-readable error description
  checkoutId?: string; // The checkout session ID (if available)
  details?: any;       // Extra context (e.g., validation errors, network logs)
}

onCancel

This is called when the transaction is cancelled. It returns no response.

onCancel: () => {
  console.log("User cancelled")
}

onPending

This is called when the checkout has been initialized but no payment has been detected yet, or a payment is still awaiting blockchain confirmations.

Option	Type	Description
id	String	Unique identifier for the checkout session.
order_id	String	Unique identifier for the merchant’s order associated with this payment.
pay_amount	String	Amount the customer paid in the chosen cryptocurrency.
pay_currency	String	The cryptocurrency used for payment (e.g., BTC, ETH, USDT).
pay_network	String	The blockchain network used (e.g., Ethereum, Bitcoin, Polygon).
receieve_currency	String \| null	Settlement currency the merchant receives after conversion (nullable).
receieve_amount	String \| null	Settlement amount the merchant receives (nullable).
address	String	Crypto wallet address used for the payment.
status	String	Current payment status (e.g., NEW, SUCCESSFUL, FAILED, EXPIRED, CANCELLED, REFUNDED, PARTIALLY_PAID).

onPartiallyPaid

Option	Type	Description
id	String	Unique identifier for the checkout session.
order_id	String	Unique identifier for the merchant’s order associated with this payment.
pay_amount	String	Amount the customer has paid so far (partial payment in the selected crypto currency).
pay_currency	String	The cryptocurrency used for payment (e.g., BTC, ETH, USDT).
pay_network	String	The blockchain network used for the payment (e.g., Ethereum, Algo, BTC).
receieve_currency	String \| null	The currency the merchant will receive after conversion, if applicable (e.g., USDT).
receieve_amount	String \| null	The amount the merchant will receive in the settlement currency for the partial payment.
address	String	The crypto wallet address to which the customer sent the partial payment.
status	String	Current payment status (e.g., PARTIALLY_PAID while awaiting full payment).

Display Modes

Kidapay provides flexible display modes so you can decide how customers interact with the payment interface.

Popup (Default)

Opens the payment interface in a popup window.

await kidapay.checkout({
    amount: 10.00,
    currency: 'USD',
    displayMode: 'popup'
    // ... other options
});

Iframe

Embeds the payment interface in an overlay iframe.

await kidapay.checkout({
    amount: 10.00,
    currency: 'USD',
   displayMode: 'iframe'
    // ... other options
});

Redirect

Redirects the user to the payment page.

await kidapay.checkout({
    amount: 10.00,
    currency: 'USD',
   displayMode: 'redirect'
    // ... other options
});

Supported Currencies

Kidapay enables merchants to accept payments in cryptocurrencies and withdraw funds in either crypto or fiat, depending on their preference.

This dual support allows customers to pay seamlessly with digital assets, while merchants enjoy the flexibility of withdrawing in either their local fiat currency or preferred crypto.

Type	Usage	Supported Currencies
Fiat	Withdrawals only	KES (Kenyan Shilling), NGN (Nigerian Naira), ZAR (South African Rand), GHS (Ghanaian Cedi), LRD (Liberian Dollar), EUR (Euro), USD (US Dollar)
Crypto	Payments & Withdrawals	BTC (Bitcoin), LTC (Litecoin), ETH (Ethereum), SOL (Solana), USDC (USD Coin), USDT (Tether), TRON (Tron), ALGO (Algorand), …and more

Error Handling

The SDK provides comprehensive error handling with specific error types:

ValidationError: Invalid input parameters
ApiError: API request failures
NetworkError: Network connectivity issues
KidapayError: Base error class

Environment Variables

When using the SDK in a backend environment, ensure you set the following environment variables:

KIDAPAY_SECRET_KEY=sk_test_your_secret_key_here
KIDAPAY_API_KEY=pk_test_your_public_key_here

Testing

The SDK includes comprehensive test coverage:

# Run tests

npm test

# Run tests with coverage

npm run test:coverage

# Run tests in watch mode

npm run test:watch

Development

The SDK provides scripts to streamline both local development and production builds.

Local Development Server
Building

# Start backend development server

npm run dev:backend

# Start frontend development server  

npm run dev:server

# Build the SDK - Compiles the SDK for production use:

npm run build

# Build in watch mode - Automatically rebuilds the SDK whenever changes are detected:

npm run build:watch

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import { Kidapay, CheckoutOptions, PaymentSuccessData } from 'kidapay-checkout-sdk';

const kidapay = new Kidapay({
    apiKey: 'your-api-key',
    environment: 'sandbox'
});

const options: CheckoutOptions = {
    amount: 10.00,
    currency: 'USD',
    onSuccess: (data: PaymentSuccessData) => {
        console.log('Payment successful:', data.transactionHash);
    }
};

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Checkout SDK

Kidapay Checkout SDK​

Introduction​

Installation​

Initialization

Kidapay object​

Callbacks​

Display Modes​

Supported Currencies​

Error Handling​

Environment Variables​

Testing​

Development​

TypeScript Support​

Contributing​