checkout.js
Every option, callback, attribute and event of the MigraPay checkout script.
checkout.js opens the MigraPay checkout in a full-screen frame over your page. It never redirects the page. Load it once:
<script src="https://migrapay.com/checkout.js"></script>It defines window.MigraPay with two functions, checkout(options) and close(). For when to use each mode, see the Checkout guide.
Confirm on your server
onSuccess runs in the browser, where anyone can call it. Fulfil an order only after your server has confirmed the payment, with GET /checkout/{id} or the collection.settled webhook.
MigraPay.checkout(options)
Opens the checkout. Pass either a token from a checkout your server created, or your public key with the payment details. If a checkout is already open, the call does nothing.
Open a checkout your server created
Prop
Type
MigraPay.checkout({
token: 'pr_9Fh2kLm7Qx3Vb8Ns',
onSuccess: (payment) => showThankYou(payment.reference),
onClose: (result) => console.log(result.status),
});Start a checkout from the browser with a public key
Prop
Type
MigraPay.checkout({
key: 'pk_live_…',
amount: 25000,
currency: 'NGN',
reference: 'ORDER-1048',
customer: { email: '[email protected]', name: 'Ada Obi' },
metadata: { orderId: '1048' },
onSuccess: (payment) => confirmOnServer(payment.reference),
});A public key can only start checkouts for your business. Restrict it to your own websites under Settings → API & integrations → Public keys; checkouts opened from any other site are refused.
Calling checkout() with neither a token nor a key throws MigraPay.checkout needs your public key (key: "pk_…") or a checkout token.
onSuccess
Called once, as soon as the payment succeeds, with:
Prop
Type
onClose
Called when the frame closes, with { status }:
status | Meaning |
|---|---|
successful | The payer paid, then closed the checkout. |
cancelled | The payer closed it without paying, or you called MigraPay.close(). |
MigraPay.close()
Closes an open checkout. onClose runs with { status: 'cancelled' }.
HTML attributes
Pay button for a server-created checkout
Any element with data-migrapay-checkout opens that checkout when clicked:
<button data-migrapay-checkout="pr_9Fh2kLm7Qx3Vb8Ns">Pay now</button>Drop-in button (no JavaScript)
Put your public key, and optionally a widget id, on the script tag. Each <div id="mp-checkout"> (or any element with data-migrapay-widget) gets a Pay button styled from your widget settings.
<script
src="https://migrapay.com/checkout.js"
data-key="pk_live_…"
data-checkout-id="chk_…"
></script>
<div id="mp-checkout" data-amount="25000" data-currency="NGN" data-reference="ORDER-1048"></div>| Attribute | On | Meaning |
|---|---|---|
data-key | <script> | Your public key. Required for the drop-in button. |
data-checkout-id | <script> | A saved checkout widget: its button label, colour, currencies and methods. |
data-amount | button container | Amount to charge. |
data-currency | button container | Currency of the amount. |
data-reference | button container | Your order reference. |
data-description | button container | What the payment is for. |
data-email, data-name, data-phone | button container | Payer details to prefill. |
data-label | button container | Button text. Defaults to the widget's label, else Pay now. |
DOM events
The container element dispatches bubbling events:
| Event | event.detail |
|---|---|
migrapay:success | The same object as onSuccess. |
migrapay:close | { status: 'successful' | 'cancelled' } |
document.getElementById('mp-checkout').addEventListener('migrapay:success', (e) => {
confirmOnServer(e.detail.reference);
});