Inpay Checkout Module — Developer Documentation

Last Updated: January 2, 2026

1. Overview

Welcome to the Inpay Checkout developer documentation. This guide shows how to integrate our lightweight, secure, and user‑friendly checkout modal into your web application.

Inpay Checkout is a client‑side JavaScript module that renders a modal overlay on your site. It handles the full payment flow, from method selection (Bank Transfer, QR Code, Card, etc.) to real‑time payment status polling, so your users never leave your site.

Note: This guide focuses on the inline checkout modal. Additional server‑side or hosted options will be added later.

Available Versions

Version	URL	Features
V1 (Stable)	`https://js.inpaycheckout.com/v1/inline.js`	Bank Transfer, PayID, QR Code
V2 (New)	`https://js.inpaycheckout.com/v2/inline.js`	All V1 features + Card Payments + Payment Method Control

Choosing a Version

V1: Recommended for existing integrations. Shows all payment methods automatically.
V2: Recommended for new integrations. Includes card payments and lets you control which payment methods to display.

Both versions work in parallel. V1 will continue to be supported.

2. Getting Started

2.1 Installation

The SDK is designed for simplicity. No package manager is required. Add this script in the <head> of your page:

<!-- V1 (Stable) -->
<script src="https://js.inpaycheckout.com/v1/inline.js"></script>

<!-- V2 (New Features) -->
<script src="https://js.inpaycheckout.com/v2/inline.js"></script>

This loads asynchronously and makes iNPAY.InpayCheckout available globally on window once ready.

2.2 Live Demo

Live Demo

This is a live demo of the iNPAY Checkout modal. Transactions completed through this demo will be counted as a giveaway to help you simulate our checkout experience in real-time.

Try the checkout modal below. Enter your name and email, then click "Pay Now" to see the modal in action:

2.3 Quick Start: Basic Integration

Add a "Pay Now" button in your page.
Add a click handler.
Instantiate InpayCheckout and call checkout(options).

Example (Vanilla JavaScript)

<!DOCTYPE html>
<html>
  <head>
    <title>Inpay Checkout Demo</title>
    <script src="https://js.inpaycheckout.com/v1/inline.js"></script>
  </head>
  <body>
    <button id="payButton">Pay Now</button>

    <script>
      document.getElementById("payButton").addEventListener("click", () => {
        try {
          const inpay = new window.iNPAY.InpayCheckout();
          inpay.checkout({
            apiKey: "pk_sandbox_your_public_api_key", // Replace with your public key
            amount: 500000, // Amount in kobo (e.g., ₦5,000.00 NGN)
            email: "customer@example.com",
            firstName: "John",
            lastName: "Doe",
            onClose: () => {
              console.log("Checkout modal was closed.");
            },
            onInitialize: () => {
              console.log("Checkout modal initialized");
            },
            onError: (error) => {
              console.log(error);
            },
            onSuccess: (reference) => {
              console.log(reference);
            },
            onFailure: (error) => {
              console.log(error);
            },
            onExpired: () => {
              console.log("Payment session has expired");
            },
            metadata: {
              order_id: "ORD-12345",
              customer_id: "CUST-001",
            },
          });
        } catch (error) {
          console.error("Checkout Error:", error?.message || error);
        }
      });
    </script>
  </body>
</html>

Example (React)

Add the script to public/index.html, then call from a component.

public/index.html
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>My React App</title>
    <script src="https://js.inpaycheckout.com/v1/inline.js"></script>
  </head>
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <div id="root"></div>
  </body>
</html>

MyComponent.tsx
import React from "react";

// Tip (TypeScript): declare globally to avoid type errors
// declare global { interface Window { iNPAY: { InpayCheckout: any } } }

export default function MyComponent() {
  const handlePayment = () => {
    try {
      const inpay = new (window as any).iNPAY.InpayCheckout();
      inpay.checkout({
        apiKey: "pk_sandbox_your_public_api_key",
        amount: 500000,
        email: "customer@example.com",
        firstName: "Jane",
        lastName: "Doe",
        metadata: { cart_id: "cart-xyz-789" },
        onClose: () => console.log("Modal closed"),
        onInitialize: () => {
          console.log("Checkout modal initialized");
        },
        onError: (error) => {
          console.log(error);
        },
        onSuccess: (reference) => {
          console.log(reference);
        },
        onFailure: (error) => {
          console.log(error);
        },
        onExpired: () => {
          console.log("Payment session has expired");
        },
      });
    } catch (error: any) {
      if (error?.name?.startsWith("CheckoutError")) {
        console.error(`Error Code: ${error.name}, Message: ${error.message}`);
      } else {
        console.error("An unexpected error occurred:", error);
      }
    }
  };

  return <button onClick={handlePayment}>Pay ₦5,000.00</button>;
}

V2 Examples — Payment Method Control

V2 introduces the paymentMethods option to control which payment options appear in the modal.

Show Only Card Payment

<!DOCTYPE html>
<html>
  <head>
    <title>Card Payment Only</title>
    <!-- Note: Using V2 script -->
    <script src="https://js.inpaycheckout.com/v2/inline.js"></script>
  </head>
  <body>
    <button id="payButton">Pay with Card</button>

    <script>
      document.getElementById("payButton").addEventListener("click", () => {
        const inpay = new window.iNPAY.InpayCheckout();
        inpay.checkout({
          apiKey: "pk_sandbox_your_public_api_key",
          amount: 500000,
          email: "customer@example.com",
          // V2: Show only card payment option
          paymentMethods: ["card"],
          onSuccess: (reference) => {
            console.log("Payment successful:", reference);
          },
        });
      });
    </script>
  </body>
</html>

Show Bank Transfer and Card Only (No PayID/QR)

const inpay = new window.iNPAY.InpayCheckout();
inpay.checkout({
  apiKey: "pk_sandbox_your_public_api_key",
  amount: 500000,
  email: "customer@example.com",
  // V2: Show bank transfer and card only
  paymentMethods: ["bank", "card"],
  onSuccess: (reference) => {
    console.log("Payment successful:", reference);
  },
});

Show Only Bank Transfer

const inpay = new window.iNPAY.InpayCheckout();
inpay.checkout({
  apiKey: "pk_sandbox_your_public_api_key",
  amount: 500000,
  email: "customer@example.com",
  // V2: Show only bank transfer
  paymentMethods: ["bank"],
  onSuccess: (reference) => {
    console.log("Payment successful:", reference);
  },
});

Show PayID/QR and Card (No Bank Transfer)

const inpay = new window.iNPAY.InpayCheckout();
inpay.checkout({
  apiKey: "pk_sandbox_your_public_api_key",
  amount: 500000,
  email: "customer@example.com",
  // V2: PayID (includes QR) and Card
  paymentMethods: ["payid", "card"],
  onSuccess: (reference) => {
    console.log("Payment successful:", reference);
  },
});

Use Dashboard Settings (Recommended)

const inpay = new window.iNPAY.InpayCheckout();
inpay.checkout({
  apiKey: "pk_sandbox_your_public_api_key",
  amount: 500000,
  email: "customer@example.com",
  // paymentMethods not provided - will use your dashboard settings
  onSuccess: (reference) => {
    console.log("Payment successful:", reference);
  },
});

Explicitly Show All Payment Methods

const inpay = new window.iNPAY.InpayCheckout();
inpay.checkout({
  apiKey: "pk_sandbox_your_public_api_key",
  amount: 500000,
  email: "customer@example.com",
  // V2: Explicitly show all methods (overrides dashboard settings)
  paymentMethods: "all",
  // Or: paymentMethods: ["bank", "payid", "card"],
  onSuccess: (reference) => {
    console.log("Payment successful:", reference);
  },
});

3. Configuration (`CheckoutOptions`)

The checkout method accepts a single configuration object:

Common Options (V1 & V2)

Property	Type	Required?	Description
`apiKey`	`string`	Yes	Public key from your dashboard.
`amount`	`number`	Yes	Amount in the lowest denomination (kobo for NGN, cents for USD). For ₦1,500.50, use `150050`.
`email`	`string`	Yes	Customer email for receipts and identification.
`currency`	`string`	No	ISO code, defaults to `NGN`.
`firstName`	`string`	No	Customer first name.
`lastName`	`string`	No	Customer last name.
`onClose`	`() => void`	No	Called when the modal closes.
`onInitialize`	`() => void`	No	Called when the payment session is initialized.
`onError`	`(error: Error) => void`	No	Called on network or initialization errors.
`onSuccess`	`(reference: string) => void`	No	Called when the payment completes.
`onFailure`	`(error?: Error) => void`	No	Called when the payment fails.
`onExpired`	`() => void`	No	Called when the payment session expires.
`metadata`	`Record<string, unknown>`	No	Custom data (e.g., `order_id`, `customer_id`) visible in dashboard and via webhooks.

V2-Only Options

Property	Type	Required?	Description
`paymentMethods`	`"all"` or `["bank", "payid", "card"]` or `undefined`	No	Control which payment methods to display. If not provided, uses your dashboard settings. If provided, overrides dashboard settings.

Payment Methods Options

Value	Payment Methods Displayed
`"all"` or `undefined`	Bank Transfer, PayID, QR Code, Card (all methods)
`["bank"]`	Bank Transfer only
`["payid"]`	PayID + QR Code only (both appear together)
`["card"]`	Card Payment only
`["bank", "payid"]`	Bank Transfer + PayID + QR Code
`["bank", "card"]`	Bank Transfer + Card
`["payid", "card"]`	PayID + QR Code + Card
`["bank", "payid", "card"]`	All methods

PayID includes QR

When you enable "payid", both the PayID option and QR Code option will appear. They use the same underlying payment method.

4. Checkout Flow and Responses

Initialization (initializing) — checkout() starts a secure session with Inpay.
Method Selection (idle) — The user chooses a payment method.
Details Fetching (fetching) — The SDK fetches method details (e.g., unique bank account).
Pending (polling) — The SDK polls for confirmation and shows instructions.
Terminal states
- Success (success) — Confirmation received; a success message shows. The modal auto‑closes after a few seconds and triggers onClose.
- Failed (failed) — Payment failed; the user can close the modal.
- Expired (expired) — Session expired before confirmation.

Final Payment Verification

Do not grant value based on client‑side success alone. Treat the modal as UX; your server is the source of truth.

Verify each transaction on your backend by either:

Using webhooks (recommended): configure a webhook URL in the dashboard; we send server‑to‑server events with final status.
Calling the API from your server: after onClose, verify the transaction by reference.

5. Error Handling

checkout() can throw a synchronous CheckoutError for invalid options. Wrap the call in try…catch.

CheckoutError has:

name — error type (e.g., "MISSING_FIELD")
statusCode — internal numeric code
message — human‑readable description

5.1 Initialization Errors

name	statusCode	message	Cause & Action
`MISSING_FIELD`	10	Missing public key	Provide `apiKey`.
`MISSING_FIELD`	11	Amount is required	Provide numeric `amount`.
`MISSING_FIELD`	12	Customer email is required	Provide `email`.
`INVALID_INPUT`	13	Currency not supported	Use a supported `currency`.
`INVALID_INPUT`	14	Amount is too low	Increase `amount` above minimum.

Error	Description	Response
`ServiceUnavailable`	Temporary outage	Modal shows service unavailable; try later.
`InvalidCredentials`	Invalid/inactive `apiKey`	Session fails; verify key in dashboard.
`InvalidInput`	Invalid arguments to `checkout`	Modal shows an error; validate your inputs.
`BadRequest`	Malformed request (e.g., invalid `metadata`)	Modal shows generic error; check console and inputs.
`MissingSession` / `InvalidSession`	Session lost/invalid	SDK attempts recovery; if it fails, show error.
`TooManyRequests`	Excessive requests	Back off; avoid loops calling `checkout()`.

6. Next Steps

Set up Webhooks → /docs/guides/webhooks
Resources → /docs/resources
API Reference (v1.0) → /docs/api/v1

Production reminder: Use your Live public key in production and never expose your Secret key in client‑side code.

1. Overview​

Available Versions​

2. Getting Started​

2.1 Installation​

2.2 Live Demo​

2.3 Quick Start: Basic Integration​

Example (Vanilla JavaScript)​

Example (React)​

V2 Examples — Payment Method Control​

Show Only Card Payment​

Show Bank Transfer and Card Only (No PayID/QR)​

Show Only Bank Transfer​

Show PayID/QR and Card (No Bank Transfer)​

Use Dashboard Settings (Recommended)​

Explicitly Show All Payment Methods​

3. Configuration (CheckoutOptions)​

Common Options (V1 & V2)​

V2-Only Options​

Payment Methods Options​

4. Checkout Flow and Responses​

5. Error Handling​

5.1 Initialization Errors​

5.2 API/Runtime Errors (inside modal)​

6. Next Steps​