Guides

Popup checkout

Add one script. One call opens the payment window on your page.

This is the basic setup. The script opens a modal on your page. The customer sees the account number, copies it, and pays from their bank app. When Payjar sees the transfer, the modal shows a success screen and closes.

Add the script#

Put this before your own code:

HTML

<script src="https://app.supa.cash/js/payjar.js"></script>

Browser

<script src="https://app.supa.cash/js/payjar.js"></script>
<button id="pay">Pay ₦5,000</button>
<script>
  document.getElementById('pay').onclick = function () {
    Payjar.checkout({
      key: 'pk_test_your_public_key',
      email: '[email protected]',
      amount: 500000,
      reference: 'order_1001',
      name: 'Ada Lovelace',
      phone: '08031234567',
      metadata: { order_id: '1001' },
      onSuccess: function (payment) {
        console.log('Paid', payment.reference, payment.status);
      },
      onClose: function () {
        console.log('Modal closed');
      },
      onError: function (error) {
        console.log(error.message);
      }
    });
  };
</script>

amount: 500000 is ₦5,000. key is your public key. email is the customer.

That call is enough to show the modal.

key comes from your Payjar account. Register if you do not have a pk_test_ key yet, or follow Get started.

What the customer sees#

A window opens over your page.
It shows the bank, the account name, the account number, and the amount.
The customer transfers that exact amount from their bank app.
The window says it is waiting, then "Payment successful".
The window closes about 2 seconds later.

In test mode the window also has a Simulate successful transfer button. That button marks the test payment as paid. It does not move money.

The button labelled I have sent the payment only changes the screen to a waiting state. The payment becomes success when the transfer arrives.

Options#

Option	Required	Description
`key`	Yes, unless you pass `access_code`	Your public key, `pk_test_...` or `pk_live_...`.
`email`	Yes	Customer email. Payjar sends the receipt here.
`amount`	Yes	Price in kobo.
`reference`	No	Your order id. Use a new one per order.
`currency`	No	`NGN`. Payments are collected in naira.
`name`	No	Customer name.
`phone`	No	Customer phone.
`metadata`	No	A plain object. Payjar stores it and sends it back.
`callback_url`	No	A URL on your site. Payjar stores it. The modal does not redirect the customer there.
`access_code`	No	Open an existing session instead of creating one.
`onSuccess`	No	Called with the payment object when the transfer is confirmed.
`onClose`	No	Called when the window closes.
`onError`	No	Called with an `Error` if the modal cannot start.

onSuccess runs first when a payment is confirmed. onClose runs after that, when the window closes. onClose also runs if the customer closes the window, or if the payment expires. A closed window can still be paid a moment later. Deliver the order from your server, after verify or a webhook.

Payjar.close() closes the window.

Supapay.checkout is the same function as Payjar.checkout.

Success payload#

onSuccess receives the payment object:

JSON

{
  "id": 1042,
  "reference": "order_1001",
  "access_code": "a1b2c3d4e5f6789012345678abcdef01",
  "amount": 500000,
  "fee": 5000,
  "charged_amount": 500000,
  "settled_amount": 495000,
  "fee_paid_by": "merchant",
  "currency": "NGN",
  "status": "success",
  "environment": "test",
  "customer_email": "[email protected]",
  "customer_name": "Ada Lovelace",
  "customer_phone": "08031234567",
  "metadata": { "order_id": "1001" },
  "bank": {
    "bank_name": "9JAPAY MFB",
    "account_name": "SUPAPAY CHECKOUT",
    "account_number": "0123456789",
    "amount": 500000,
    "currency": "NGN"
  },
  "paid_at": "2026-11-03T16:41:12+01:00",
  "expires_at": "2026-11-03T17:07:00+01:00",
  "created_at": "2026-11-03T16:37:00+01:00",
  "checkout_url": "https://app.supa.cash/supapay/v1/checkout/frame/a1b2c3d4e5f6789012345678abcdef01",
  "script_url": "https://app.supa.cash/js/payjar.js"
}

Check payment.status === "success" before you update the page. Then ask your server to verify the same reference.

Open a payment you already created#

If your server already created the payment, pass the access_code and skip key, email, and amount.

Browser

<script src="https://app.supa.cash/js/payjar.js"></script>
<script>
  Payjar.checkout({
    access_code: 'a1b2c3d4e5f6789012345678abcdef01',
    onSuccess: function (payment) {
      console.log(payment.reference);
    }
  });
</script>

React#

Load https://app.supa.cash/js/payjar.js from your HTML. Then:

React

export function PayButton() {
  function pay() {
    window.Payjar.checkout({
      key: 'pk_test_your_public_key',
      email: '[email protected]',
      amount: 500000,
      reference: 'order_1001',
      onSuccess: function (payment) {
        console.log(payment.status);
      }
    });
  }

  return <button onClick={pay}>Pay ₦5,000</button>;
}