Checkout

A checkout is a payment your customer completes on a MigraPay payment page. You set the price; your customer picks the currency and how to pay. When the money arrives it is credited to your wallet and a collection.settled webhook fires.

You can show the checkout in two ways:

• Checkout link: send your customer to checkoutUrl. When they finish, they can return to your redirectUrl.
• Checkout widget: add one script to your site and the checkout opens over your page. Your customer never leaves your site.

Both use the same checkout, so you can start with the link and add the widget later. Payment links and payment requests from the dashboard open this same checkout too.

1. Create the checkout on your server

Call POST /checkout with your secret key, the price and your order reference. Send an Idempotency-Key (your order id works) so a retry never creates a second checkout. Keep the returned id: it is how you confirm the payment, and webhooks refer to it as requestId.

If you cannot run server code, start the checkout from the browser with your public key instead.

2a. Send a checkout link

Send your customer to checkoutUrl. It works on any device and needs nothing on your site. After paying, your customer sees a receipt and, if you set redirectUrl, a Return to merchant button that opens:

https://your-site.com/orders/1048?status=successful&reference=MP-9683E7B6532A&checkout=pr_d78890ba7b7a49fb97f3228f8008c3ad

If they close the checkout instead, status is cancelled. Treat these parameters as a hint for what to show; confirm the payment before you fulfil the order.

2b. Or open it on your page

Add the script once, anywhere on the page:

<script src="https://migrapay.com/checkout.js"></script>

Open a checkout you created

Create the checkout on your server, pass its token to the page, and open it:

<button id="pay">Pay NGN 25,000</button>
<script>
  document.getElementById('pay').addEventListener('click', () => {
    MigraPay.checkout({
      token: 'pr_d78890ba7b7a49fb97f3228f8008c3ad',
      onSuccess: (payment) => {
        // { token, reference, amount, currency }: show a thank-you, then confirm on your server
      },
      onClose: (result) => {
        // { status: 'successful' | 'cancelled' }
      },
    });
  });
</script>

Or without any JavaScript of your own:

<button data-migrapay-checkout="pr_d78890ba7b7a49fb97f3228f8008c3ad">Pay now</button>

Drop-in button (no server code)

In the dashboard, open Accept Payments → Checkout widget and create a widget for each website: choose its currencies, the methods for each currency, the button label and colour, and save. The HTML tab gives you code with your public key and the widget's checkout id:

<script src="https://migrapay.com/checkout.js"
        data-key="pk_live_9sK2mQ7xLp4Rt8VwYc3Nb6Hd"
        data-checkout-id="chk_AboFHVCp9PtlB-g5"></script>

<div id="mp-checkout" data-amount="25000" data-currency="NGN"
     data-email="[email protected]" data-reference="ORDER-1048"></div>

The script renders a Pay button in #mp-checkout. Set data-amount and data-currency for each order; data-email, data-name, data-phone, data-reference, data-description and data-label (button text) are optional. The element receives migrapay:success and migrapay:close events:

document.getElementById('mp-checkout').addEventListener('migrapay:success', (event) => {
  console.log(event.detail.reference);
});

The same works from JavaScript:

MigraPay.checkout({
  key: 'pk_live_9sK2mQ7xLp4Rt8VwYc3Nb6Hd',
  checkoutId: 'chk_AboFHVCp9PtlB-g5', // optional
  amount: 25000,
  currency: 'NGN',
  reference: 'ORDER-1048',
  customer: { email: '[email protected]', name: 'Ada Okafor' },
  onSuccess: (payment) => {},
});

Every option, attribute and event is in the checkout.js reference.

Public keys

A checkout can be started from your server with your secret API key (above) or straight from your website or app with your public key. Every business has one live key (pk_live_…) and one test key (pk_test_…); find them in the dashboard under Settings → API & integrations.

A public key is safe in public code. It can do two things only: start a checkout for your business and read which currencies and methods your checkout offers. It cannot read payments, refund, pay out or reach any other part of the API.

• Allowed websites: add your domains (shop.example.com, or *.example.com for every subdomain) and checkouts started from any other site are refused. With no domains set, any site can use the key.
• Rotate the key if it is misused; the old key stops working at once.
• pk_test_ keys start Sandbox checkouts.

From the browser, start a checkout with checkout.js, or call POST /v1/checkout/sessions yourself.

3. Confirm the payment

The checkout confirms the payment for your customer automatically: card payments as soon as the bank approves them, transfers and USSD when the money arrives, Interac when the e-Transfer is received and matched. Then confirm it on your server before you fulfil the order:

• Webhook (recommended): collection.settled with requestId equal to the checkout id, the amounts, and a checkout object with your original price (checkout.base) and your metadata.
• Retrieve: GET /checkout/{id} and fulfil when status is settled.

If the customer pays in a different currency from your price, your wallet in that currency is credited with what they paid.

Test in Sandbox

Checkouts created with a Sandbox key (mpb_test_…) open in test mode: the checkout shows a Test mode badge and sample payment details, and nothing real moves.

• Card: pay with a test card below. A declining card shows its error on the checkout, as a real decline would.
• Bank transfer, USSD, Interac: the checkout shows sample details; press Simulate payment to complete it.

When it completes, your Sandbox wallet is credited (less fees) and collection.settled fires, exactly as on live. See Sandbox. Try it on the public checkout demo.

Test card numbers are in the API reference.