Inline Checkout

Embed a payment modal directly on your website. The browser SDK creates the checkout session, renders the modal, collects the payment, and polls for confirmation using your public API key. No server step is required to start a payment.

If you want us to host the whole page instead, use Standard Checkout.

Install

Script tag (recommended)

<script src="https://js.zevpaycheckout.com/v1/inline.js"></script>

npm

npm install @zevpay/inline

Quick start

<button id="pay-btn">Pay ₦5,000</button>

<script src="https://js.zevpaycheckout.com/v1/inline.js"></script>
<script>
  document.getElementById('pay-btn').addEventListener('click', function () {
    var checkout = new ZevPay.ZevPayCheckout();
    checkout.checkout({
      apiKey: 'pk_test_your_public_key',
      email: 'customer@example.com',
      amount: 500000, // ₦5,000 in kobo
      currency: 'NGN',
      reference: 'order_12345', // optional
      firstName: 'John', // optional
      lastName: 'Doe',   // optional
      onSuccess: function (reference) {
        console.log('Payment successful:', reference);
        // Verify the payment on your server before fulfilling the order.
      },
      onClose: function () {
        console.log('Checkout closed');
      },
    });
  });
</script>

Options

Pass these to checkout(options).

Option	Type	Required	Description
apiKey	string	Yes	Your public API key (pk_test_... or pk_live_...). Sent from the browser, so configure allowed domains on the key.
email	string	Yes	Customer's email address.
amount	integer	Yes	Amount in kobo. 500000 is ₦5,000.
currency	string	No	Currency code. Only "NGN" is accepted. Defaults to "NGN".
reference	string	No	Your unique transaction reference. Generated for you if omitted.
firstName	string	No	Combined with lastName and stored as the session's customer name.
lastName	string	No	Combined with firstName.
metadata	object	No	Custom data attached to the transaction. Returned in webhooks and on verify.
paymentMethods	string or string[]	No	Which methods to offer. Defaults to the methods configured for your key. See below.
onInitialize	function	No	Fires once the session is created and the modal is ready.
onSuccess	function	No	Fires when the payment is confirmed. Receives the transaction reference.
onError	function	No	Fires on a validation, network, or API error. Receives an error with code and message.
onFailure	function	No	Fires when a payment fails after a method was selected.
onExpired	function	No	Fires when the session expires.
onClose	function	No	Fires when the customer closes the modal.

Choosing payment methods

Control which methods appear in the modal:

// All methods your key allows (default behaviour)
paymentMethods: 'all'

// A specific set
paymentMethods: ['bank', 'payid']

// A single method. The picker is skipped and the method is auto-selected.
paymentMethods: ['bank']

Value	Method
'bank'	Bank transfer via a virtual account
'payid'	ZevPay ID, paid from the ZevPay app
'card'	Card. Not yet live. Hidden while it is disabled.

Auto-selection

When exactly one method is enabled and it is not payid, the SDK selects it and skips the picker screen.

Metadata

Attach custom data to the transaction. It is returned in webhooks and on the verify endpoint:

checkout.checkout({
  // ...
  metadata: {
    orderId: 'order_12345',
    customerId: 'cust_789',
  },
});

Callbacks

onSuccess(reference)

Fires when the payment is confirmed. reference is our transaction reference.

onSuccess: function (reference) {
  // Verify on your server before fulfilling.
  fetch('/api/verify-payment', {
    method: 'POST',
    body: JSON.stringify({ reference }),
  });
}

Always verify on your server

A client callback is not proof of payment. Confirm the payment from your server using the Verify Session endpoint before you fulfil an order.

onError(error)

Fires on a validation, network, or API error. Read error.code for programmatic handling.

onError: function (error) {
  console.error(error.code, error.message);
}

Common error codes: MISSING_FIELD, INVALID_INPUT, INVALID_CREDENTIALS, FORBIDDEN, EXPIRED_SESSION, SERVICE_UNAVAILABLE, TOO_MANY_REQUESTS.

onFailure(error), onExpired(), onClose(), onInitialize()

onFailure fires when a payment fails after a method was selected. onExpired fires when the session times out. onClose fires when the customer dismisses the modal. onInitialize fires once the modal is ready.

Validation

The SDK checks these before it makes any API call:

Rule	Error code
apiKey is required	MISSING_FIELD
amount is required	MISSING_FIELD
email is required	MISSING_FIELD
currency, if set, must be "NGN"	INVALID_INPUT
amount must be at least 10000 kobo (₦100)	INVALID_INPUT

Card has a higher minimum

The card method is hidden in the picker when the amount is below ₦1,000, even where other methods are shown.

How it works

1. The customer clicks your pay button.
2. The SDK creates a checkout session with your public key. No server step is needed.
3. The modal renders the available payment methods.
4. The customer selects a method and sees the payment details, such as a bank account number.
5. The customer completes the transfer.
6. The SDK polls for confirmation every 5 seconds.
7. On confirmation, onSuccess fires with the transaction reference.
8. The modal closes shortly after.

Domain whitelisting

The SDK sends your public key from the browser. To stop other sites from using your key, set allowed domains on the key in the dashboard.

• Exact match: mystore.com allows only mystore.com.
• Wildcard: *.mystore.com allows shop.mystore.com, mystore.com, and other subdomains.

See Domain Whitelisting for the full rules.

Production

Always set allowed domains on your live public keys.

Related

• Standard Checkout, the hosted redirect alternative
• Payment Methods
• Verify Session
• React SDK, a component wrapper around this SDK
• Webhook Events