Checkout

Accept payments online on your website or app with ease.

Using the Checkout SDK

The Checkout SDK is a JavaScript library that allows developers to securely accept both one-time purchases and subscription payments on their website or app.

You can add it to your project using a package manager like npm, pnpm, or yarn. You can also use it directly by including the script tag in your HTML file.

Install 100Pay SDK

npm
pnpm
yarn
HTML
npm install @100pay-hq/checkout

Import the Library

JavaScript
TypeScript
import { shop100Pay } from "@100pay-hq/checkout";

// or import using require
const shop100Pay = require("@100pay-hq/checkout")

Or use the global variable shop100Pay if you included the script tag in your HTML file.

Using shop100Pay

The shop100Pay function is the main entry point for integrating 100Pay's checkout process into your application. Here's how you can use it:

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-api-key", // Replace with your 100Pay API key
  billing: {
    amount: 10000, // Amount to be charged
    currency: CURRENCIES.USD, // Currency in which the payment will be made
    description: "Purchase of digital product", // Description of the payment
    country: COUNTRIES.US, // Country of the customer
    pricing_type: "fixed", // Pricing type (fixed or variable)
  },
  customer: {
    user_id: "12345", // Unique ID of the customer
    name: "John Doe", // Name of the customer
    email: "[email protected]", // Email address of the customer
    phone: "+1234567890", // Phone number of the customer
  },
  metadata: {
    is_approved: "yes",
    order_id: "OR2", // Optional order ID
    charge_ref: "REF", // Optional charge reference
  },
  call_back_url: "http://localhost:8000/verifyorder/", // URL to which the user will be redirected after payment
  onClose: () => {
    console.log("User closed the payment modal.");
  },
  callback: (reference) => {
    console.log(`Transaction successful with reference: ${reference}`);
  },
  onError: (error) => {
    console.error("An error occurred:", error);
  },
  onPayment(reference: string) {
    console.log("Payment completed with reference:", reference);
  },
};

const displayOptions = {
  maxWidth: "500px", // Optional: specify the max width of the payment modal
};

const payWith100Pay = async () => {
  shop100Pay.setup(
    chargeData,
    displayOptions
  );
};

export default payWith100Pay;

shop100Pay Function Parameters

The shop100Pay function takes two parameters: chargeData and displayOptions.

chargeData Object

  • ref_id: A unique identifier for the transaction, typically generated using a UUID.
  • api_key: Your 100Pay API key required to authenticate the transaction.
  • billing: An object containing billing information:
    • amount: The amount to be charged.
    • currency: The currency in which the payment will be made (e.g., USD).
    • description: A brief description of the payment.
    • country: The country of the customer (e.g., US).
    • pricing_type: The type of pricing, either fixed or variable.
  • customer: An object containing customer information:
    • user_id: A unique identifier for the customer.
    • name: The customer's name.
    • email: The customer's email address.
    • phone: The customer's phone number.
  • metadata: An object for additional metadata (e.g., order_id, charge_ref, etc.).
  • call_back_url: A URL to which the user will be redirected after the payment is completed.
  • onClose: A callback function that is triggered when the user closes the payment modal.
  • callback: A callback function that is triggered when the transaction is successful.
  • onError: A callback function that is triggered if there is an error during the payment process.
  • onPayment: A callback function that is triggered after the payment is completed, with the payment reference as its argument.

displayOptions Object

  • maxWidth: An optional parameter to specify the maximum width of the payment modal.
  • maxHeight: An optional parameter to specify the maximum height of the payment modal.

shop100Pay Function Signature

function shop100Pay(chargeData: ChargeData, displayOptions?: DisplayOptions): void;

ChargeData Interface

interface ChargeData {
  ref_id: string;
  api_key: string;
  billing: {
    amount: number;
    currency: string;
    description: string;
    country: string;
    pricing_type: string;
  };
  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;
}
ref_idrequiredstring
Unique transaction reference ID.
api_keyrequiredstring
Your 100Pay API key for authenticating transactions.
billingrequiredobject
Billing information object with the following fields:
  • amount: The amount to be charged.
  • currency: The currency for the payment.
  • description: A brief description of the payment.
  • country: The customer's country.
  • pricing_type: The type of pricing (fixed or variable).
customerrequiredobject
Customer information object with the following fields:
  • user_id: A unique identifier for the customer.
  • name: The customer's name.
  • email: The customer's email address.
  • phone: The customer's phone number.
metadataobject
Additional metadata for the transaction (e.g., order_id, charge_ref, etc.).
call_back_urlrequiredstring
The URL to which the user will be redirected after payment.
onClosefunction
Callback function triggered when the payment modal is closed by the user.
callbackrequiredfunction
Callback function triggered when the transaction is successful.
onErrorfunction
Callback function triggered if there is an error during the payment process.
onPaymentfunction
Callback function triggered after payment is completed with the payment reference.

DisplayOptions Interface

interface DisplayOptions {
  maxWidth?: string;
  maxHeight?: string;
}
maxWidthstring
The maximum width of the payment modal.
maxHeightstring
The maximum height of the payment modal.
Invoices
Wallets
Learn how to create and manage wallets for your users.