@payinto/checkout-sdk

The official Payinto Checkout SDK for web applications. Securely accept payments using the Payinto popup checkout.

Installation

npm

npm install @payinto/checkout-sdk

CDN

<script src="https://checkout.payinto.co/v1/checkout.js"></script>

Quick Start

Modern Web App (npm)

import PayintoCheckout from '@payinto/checkout-sdk';

const handlePayment = () => {
  PayintoCheckout.open({
    mode: 'public_key',
    public_key: 'pk_live_your_public_key',
    amount: 10000, // Amount in minor units (e.g., 10000 = 100.00)
    currency: 'NGN',
    merchant_reference: 'ORDER_123456',
    customer: {
      email: '[email protected]',
      name: 'John Doe'
    },
    settlement_account_id: '01964316-57cb-7284-8651-c53d3fcee694',
    onSuccess: (response) => {
      console.log('Payment successful:', response);
    },
    onClose: () => {
      console.log('Checkout closed');
    },
    onError: (error) => {
      console.error('Payment failed:', error);
    }
  });
};

Script Tag (CDN)

window.PayintoCheckout.open({
  mode: 'public_key',
  public_key: 'pk_live_your_public_key',
  // ...other options
});

Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | mode | string | Yes | Use 'public_key' for merchant integrations. | | public_key | string | Yes | Your Payinto public key. | | amount | number | Yes | The transaction amount in minor units. | | currency | string | No | Currency code (default: 'NGN'). | | customer | object | Yes | Customer details (email is required). | | merchant_reference | string | No | Unique merchant transaction reference. | | metadata | object | No | Additional data for the transaction. | | settlement_account_id | string | No | The ID of the settlement account to receive funds for this checkout. If omitted, your Payinto Main account is used. | | redirect_url| string | No | URL to redirect to after successful payment. | | onSuccess | function| No | Callback on successful payment. | | onClose | function| No | Callback when the checkout is closed. | | onError | function| No | Callback on error. |

Browser Callback Payloads

Success

{
  type: 'checkout.succeeded',
  status: 'success',
  reference?: string,
  merchant_reference?: string,
  token?: string
}

Error

{
  type: 'checkout.error',
  code: string,
  message: string
}

Server payment confirmation and webhooks

The browser success callback uses checkout.succeeded. It is a UI notification, not a signed server webhook. Keep using the onSuccess callback option; its payload type is now checkout.succeeded. The SDK accepts legacy checkout.success messages from older checkout frames and normalizes them to the new payload. Update any code that compares payload.type, and deploy the updated SDK and checkout app together. Do not fulfill orders solely from browser messages or redirects.

Subscribe your backend to checkout.payment.succeeded. Verified bank-transfer and card checkout payments use the same event, distinguished by data.payment_method (bank_transfer or card). Future methods such as USSD will use the event once their verified confirmation flow is integrated; this SDK change does not enable them.

| Server event | Trigger | | --- | --- | | checkout.payment.succeeded | Verified checkout payment succeeds; use for checkout fulfillment. | | virtual_account.transfer.received | A virtual-account deposit is credited, including checkout bank transfers. | | transaction.credit.succeeded | An account credit is recorded. | | transaction.debit.succeeded | An account debit is recorded; external payment completion is not implied. |

A checkout bank transfer can emit the first three events. Fulfill from the checkout event only and deduplicate by data.id or data.reference. Checkout pending, failed, expired, and refunded webhook events are not currently emitted.

Every webhook has event, id, created_at, api_version, and data. All four include nullable data.merchant_reference. Checkout success also includes payment_method, currency, payment_status: "successful", paid_at, customer, metadata, and the amount breakdown:

{
  "event": "checkout.payment.succeeded",
  "id": "webhook_001",
  "created_at": "2026-10-22T12:00:00.000000Z",
  "api_version": "2026-05-27",
  "data": {
    "id": "payment_inflow_001",
    "reference": "PIF-1",
    "merchant_reference": "ORDER-1",
    "payment_method": "bank_transfer",
    "currency": "NGN",
    "base_amount": 150000,
    "customer_charge_amount": 2000,
    "customer_fee_amount": 2000,
    "amount": 152000,
    "charges_applied": true,
    "fee": 2000,
    "vat": 0,
    "stamp_duty": 0,
    "total_fee": 2000,
    "settled_amount": 150000,
    "payment_status": "successful",
    "paid_at": "2026-10-22T12:00:00.000000Z",
    "customer": null,
    "metadata": null
  }
}

Amounts are minor currency units. base_amount is the order amount; amount includes customer-paid charges; settled_amount is after fees. Match the merchant reference, currency, and expected amount server-side before fulfilling once.

Verify X-Payinto-Signature using the webhook secret and HMAC-SHA256 over {timestamp}.{raw_request_body}. The header format is t={timestamp},v1={digest}. Use the Node or PHP server SDK to verify the exact raw body, enforce timestamp freshness, and acknowledge only after durable processing or queuing. Keep webhook secrets and API secret keys on your server.

For authenticated status checks, call GET /api/v1/checkout/tsq/{reference} from your backend with its secret key. This returns data.merchant_reference from the payment inflow or cached checkout, and data.payment_status (pending, successful, failed, cancelled, or expired). The exported CheckoutTransactionStatusData type describes this data; the browser SDK does not make secret-key TSQ requests.

Account transaction TSQ (GET /api/v1/business/transactions/tsq/{reference}) uses data.status and currently reads merchant references only from transaction metadata. Transaction webhooks have additional linked-source fallbacks, so their merchant reference can be populated while transaction TSQ returns null.

Security

• The SDK validates message origins against an internal allowlist.
• It uses a secure iframe to isolate the payment process.
• Never expose your Secret Keys in client-side code.

License

MIT