Skip to Content
👋 Welcome to 100Pay Developers
DocsDeveloper ToolsPay Checkout

Pay Checkout

The 100Pay Checkout SDK (@100pay-hq/checkout) is a drop-in JavaScript library for accepting crypto payments directly in the browser. It renders a secure, hosted payment modal — no backend required for the checkout itself.

  • Supports 90+ fiat currencies with automatic crypto conversion
  • Works with React, Vue, vanilla JS, and any web framework
  • Zero blockchain knowledge required

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

Installation

npm install @100pay-hq/checkout

Import

// ES module
import { shop100Pay } from "@100pay-hq/checkout";
 
// CommonJS
const { shop100Pay } = require("@100pay-hq/checkout");

Quick Start

import { shop100Pay } from "@100pay-hq/checkout";
 
shop100Pay.setup({
  ref_id: "TXN_" + Date.now(),
  api_key: "your_public_api_key",    // Public key — safe to use in browser
  customer: {
    name: "Jane Doe",
    email: "[email protected]",
    phone: "+1234567890",
  },
  billing: {
    amount: 49.99,
    currency: "USD",
    description: "Monthly subscription",
    country: "US",
    pricing_type: "fixed_price",
  },
  metadata: {
    order_id: "ORD_001",
  },
  call_back_url: "https://yourapp.com/payment/success",
  onPayment: (reference) => {
    // Send reference to your backend for server-side verification
    verifyOnBackend(reference);
  },
  onClose: () => console.log("Modal closed"),
  onError: (error) => console.error("Payment error:", error),
});

Use your Public API Key — never your Secret Key — in client-side code. The onPayment callback is client-side only. Always verify payments on your server before fulfilling orders.

Framework Examples

import { shop100Pay } from "@100pay-hq/checkout";
 
function CheckoutButton({ amount, user }) {
  const handlePayment = () => {
    shop100Pay.setup({
      ref_id: "REF_" + Date.now(),
      api_key: process.env.REACT_APP_100PAY_API_KEY,
      customer: {
        name: user.name,
        email: user.email,
        phone: user.phone,
      },
      billing: {
        amount,
        currency: "USD",
        description: "Product purchase",
        country: "US",
        pricing_type: "fixed_price",
      },
      metadata: { source: "react-app" },
      call_back_url: `${window.location.origin}/payment/success`,
      onPayment: async (reference) => {
        const res = await fetch("/api/verify-payment", {
          method: "POST",
          body: JSON.stringify({ reference }),
          headers: { "Content-Type": "application/json" },
        });
        if ((await res.json()).success) {
          window.location.href = "/payment/success";
        }
      },
      onClose: () => console.log("Closed"),
      onError: (err) => alert("Payment failed: " + err),
    }, { maxWidth: "500px" });
  };
 
  return <button onClick={handlePayment}>Pay ${amount}</button>;
}

Parameters

CHARGE_DATA

FieldTypeRequiredDescription
api_keystring✅Your 100Pay Public API key
ref_idstring✅Unique transaction reference — use a UUID or timestamp
customer.namestring✅Customer’s full name
customer.emailstring✅Customer’s email address
customer.phonestring✅Customer’s phone number
customer.user_idstring—Your internal user ID
billing.amountnumber✅Payment amount
billing.currencyCURRENCIES✅Currency code (e.g. "USD", "NGN", "GHS")
billing.countryCOUNTRIES✅ISO country code (e.g. "US", "NG")
billing.descriptionstring✅Short payment description
billing.pricing_type"fixed_price" | "partial"✅"fixed_price" for exact amount, "partial" allows underpayment
billing.vatnumber—VAT/tax percentage to add
metadataobject✅Custom key/value data attached to the transaction
call_back_urlstring✅Redirect URL after payment completes
onPayment(ref: string) => void✅Called when payment is detected — send ref to backend to verify
onClose() => void✅Called when the user closes the modal
onError(err: string | Error) => void✅Called on checkout error

DISPLAY_OPTIONS

FieldTypeDefaultDescription
maxWidthstring"400px"Maximum width of the modal
maxHeightstring"unset"Maximum height of the modal

Supported Currencies

90+ fiat currencies are supported, including:

USD EUR GBP NGN GHS KES ZAR CAD AUD JPY INR BRL CNY MXN EGP MAD TZS UGX and many more.

TypeScript Types

import { shop100Pay, CHARGE_DATA, DISPLAY_OPTIONS, CURRENCIES, COUNTRIES } from "@100pay-hq/checkout";
 
const charge: CHARGE_DATA = {
  api_key: "your_key",
  ref_id: "TXN_001",
  customer: { name: "Jane", email: "[email protected]", phone: "+1234567890" },
  billing: {
    amount: 100,
    currency: "USD",
    country: "US",
    description: "Test",
    pricing_type: "fixed_price",
  },
  metadata: {},
  call_back_url: "https://yourapp.com/success",
  onPayment: (ref) => console.log(ref),
  onClose: () => {},
  onError: (err) => console.error(err),
};
 
shop100Pay.setup(charge, { maxWidth: "500px" });

Next Steps

  • Verify Payments — confirm transactions on your server before fulfilling orders
  • Webhooks — receive real-time payment events on your backend
  • 100pay.js SDK — server-side SDK for transfers, subaccounts, and more
Last updated on
100pay.jsFlutter SDK