Skip to Content
đź‘‹ Welcome to 100Pay Developers
DocsPaymentsCheckout

Checkout

Accept payments online on your website or app with ease. The 100Pay Checkout SDK provides an embeddable hosted checkout that supports:

  • Crypto payments across multiple currencies with automatic conversions
  • Multiple payments in a single session
  • Underpayment and overpayment detection

Before integrating, make sure you have set up your account and obtained your API keys.

Using the Checkout SDK

Install

Add the 100Pay Checkout SDK to your project:

npm install @100pay-hq/checkout

Import

import { shop100Pay, CURRENCIES, COUNTRIES } from "@100pay-hq/checkout";
// or with CommonJS:
// const { shop100Pay } = require("@100pay-hq/checkout");

Example Usage

import { v4 as uuidv4 } from "uuid";
import { COUNTRIES, CURRENCIES, shop100Pay } from "@100pay-hq/checkout";
 
const chargeData = {
  ref_id: uuidv4(),            // Unique transaction reference ID
  api_key: "your-public-api-key",
 
  billing: {
    amount: 10000,                    // Amount to charge
    currency: CURRENCIES.USD,         // Payment currency
    description: "Purchase of digital product",
    country: COUNTRIES.US,            // Customer's country
    pricing_type: "fixed",            // "fixed" or "variable"
  },
 
  customer: {
    user_id: "12345",
    name: "John Doe",
    email: "[email protected]",
    phone: "+1234567890",
  },
 
  metadata: {
    order_id: "ORD-001",              // Optional: your internal order ID
    charge_ref: "REF-001",            // Optional: your internal charge reference
  },
 
  call_back_url: "https://yourapp.com/verify-order",
 
  onClose: () => {
    console.log("User closed the payment modal.");
  },
  callback: (reference) => {
    console.log("Transaction successful, reference:", reference);
  },
  onError: (error) => {
    console.error("Payment error:", error);
  },
  onPayment: (reference) => {
    console.log("Payment completed, reference:", reference);
  },
};
 
const displayOptions = {
  maxWidth: "500px",   // Optional: max width of the modal
};
 
// Launch the checkout modal
shop100Pay.setup(chargeData, displayOptions);

Always use your Public API Key here — never your Secret Key. The public key is safe to use in client-side code.

Parameters

chargeData

ParameterTypeRequiredDescription
ref_idstring✅Unique transaction reference ID — use a UUID to generate one
api_keystringâś…Your 100Pay Public API key
billing.amountnumberâś…Amount to charge (in the specified currency)
billing.currencystringâś…Payment currency (e.g. CURRENCIES.USD)
billing.descriptionstringâś…Brief description of the payment
billing.countrystring✅Customer’s country (e.g. COUNTRIES.US)
billing.pricing_typestringâś…"fixed" or "variable"
customer.user_idstring✅Your app’s unique identifier for the customer
customer.namestring✅Customer’s full name
customer.emailstring✅Customer’s email address
customer.phonestring✅Customer’s phone number
metadataobject—Additional key/value metadata (e.g. order_id, charge_ref)
call_back_urlstringâś…URL to redirect the user to after payment completes
onClose() => void—Called when the user closes the payment modal
callback(ref: string) => voidâś…Called when the transaction is successful
onError(err: any) => void—Called if an error occurs during payment
onPayment(ref: string) => void—Called after payment completes with the payment reference

displayOptions

ParameterTypeRequiredDescription
maxWidthstring—Maximum width of the checkout modal (e.g. "500px")
maxHeightstring—Maximum height of the checkout modal

TypeScript Interface

interface ChargeData {
  ref_id: string;
  api_key: string;
  billing: {
    amount: number;
    currency: string;
    description: string;
    country: string;
    pricing_type: "fixed" | "variable";
  };
  customer: {
    user_id: string;
    name: string;
    email: string;
    phone: string;
  };
  metadata?: Record<string, string>;
  call_back_url: string;
  onClose?: () => void;
  callback: (reference: string) => void;
  onError?: (error: any) => void;
  onPayment?: (reference: string) => void;
}
 
interface DisplayOptions {
  maxWidth?: string;
  maxHeight?: string;
}

Verifying Payments

After a successful payment, always verify the transaction on your server using the reference ID returned in the callback. This prevents accepting payments that may not have actually been completed.

// Server-side verification example
const response = await fetch("https://api.100pay.co/api/v1/charge/verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer YOUR_SECRET_KEY`,
  },
  body: JSON.stringify({ ref_id: reference }),
});
 
const data = await response.json();
if (data.status === "completed") {
  // Payment confirmed — fulfill the order
}

Use your Secret API Key for server-side verification requests, never the public key.

Last updated on
OverviewAsset Transfers