Inpay Checkout Module — Developer Documentation

Version: 1.0.0
Last Updated: September 13, 2025

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, 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.

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:

<script src="https://js.inpaycheckout.com/v1/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>;
}

3. Configuration (`CheckoutOptions`)

The checkout method accepts a single configuration object:

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.

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​

2. Getting Started​

2.1 Installation​

2.2 Live Demo​

2.3 Quick Start: Basic Integration​

Example (Vanilla JavaScript)​

Example (React)​

3. Configuration (CheckoutOptions)​

4. Checkout Flow and Responses​

5. Error Handling​

5.1 Initialization Errors​

5.2 API/Runtime Errors (inside modal)​

6. Next Steps​