Skip to content

Quickstart: Embedded checkout

This page takes a real payment: by the end of it you will have paid a small amount, with your own card or EcoCash number and production keys, on your own checkout page, and your server will know about it. Pick your framework once in any tab and every tab on the page follows.

  • A Pesepay account with a production integration key and encryption key
  • A server that can create a payment, as in the Hosted checkout quickstart
  • A web page you can edit, served over http://localhost or HTTPS
  1. Create and initiate a transaction exactly as for Hosted checkout, but keep the referenceNumber instead of redirecting to redirectUrl. Set returnUrl to your checkout page itself: a card that goes to its bank comes back there (see Coming back from the bank).

    pesepay.resultUrl = 'https://example.com/payments/result';
    pesepay.returnUrl = 'https://example.com/checkout';
    const transaction = pesepay.createTransaction(10.0, 'USD', 'Order #1042');
    const response = await pesepay.initiateTransaction(transaction);
    const referenceNumber = response.referenceNumber; // send this to your page

    Pass the reference number to your checkout page however your app renders it: in the HTML, as a prop, or from an API call.

  2. Nothing to install. The page in the next step loads https://js.pesepay.com/v1/pesepay.js.

  3. The checkout element lists every method the transaction can be paid with, shows the total and fee for the one the customer picks, shows that method’s fields, and pays with its own button. Your code listens for one event, finished.

    Your server writes the reference number into the page:

    checkout.html
    <!doctype html>
    <html lang="en">
    <head>
    <meta charset="UTF-8" />
    <title>Checkout</title>
    </head>
    <body>
    <!-- Your server created the transaction and wrote its reference number here. -->
    <div id="checkout" data-reference-number="REF-1"></div>
    <p id="payment-message"></p>
    <script src="https://js.pesepay.com/v1/pesepay.js"></script>
    <script src="checkout.js"></script>
    </body>
    </html>

    Keep the script in its own file, so a Content-Security-Policy without 'unsafe-inline' allows it:

    checkout.js
    const container = document.getElementById("checkout");
    const message = document.getElementById("payment-message");
    const referenceNumber = container.dataset.referenceNumber;
    // Unset if the script tag was blocked, for example by a content blocker.
    const pesepay = window.Pesepay?.create({});
    if (pesepay) {
    const checkout = pesepay.elements().create("checkout", { referenceNumber });
    // The payment has ended and the element shows the result. Fulfil the order
    // on your server, which Pesepay notifies too; this only moves the customer on.
    checkout.on("finished", (event) => {
    if (event.outcome === "succeeded") window.location.assign("/order-complete");
    });
    // The methods could not load: Pesepay's hosted checkout takes the payment.
    checkout.on("loaderror", (event) => {
    if (event.fallbackUrl) window.location.assign(event.fallbackUrl);
    });
    checkout.mount(container);
    } else {
    message.textContent = "Payments are unavailable. Please try again later.";
    }

    Don’t add an integrity hash to /v1/pesepay.js: it is patched in place so security fixes reach you without a redeploy, and a patched file no longer matches the hash.

    For O’mari, the element’s button then asks for the code from the SMS. For EcoCash and scan codes, the element waits while the customer finishes on their phone. finished is sent once, with an outcome:

    OutcomeWhat it means
    succeededThe customer paid.
    failedThe customer did not pay: declined, cancelled or closed. A declined transaction can’t be paid again: create a new one to let the customer retry.
    reversedThe customer paid, then the money was returned.
    unknownNo answer came in time. The customer may still pay, so don’t let them pay again until your server has the result.

    Want your own Pay button, with each step in your code? See Custom payment flow.

  4. A Visa card that needs 3-D Secure, and Mastercard or Zimswitch, take the customer to their bank. They come back to the returnUrl you set when you created the payment, your checkout page, with ?referenceNumber= added. Render the page with the same reference number, reusing the order’s transaction rather than creating a new one. The element shows the result in place of the methods and sends finished.

    A transaction that is already paid, or still being paid, is never offered the methods again: the element shows its result, or waits for it.

  5. Open your checkout page with the order’s reference number and pay a small amount, such as USD 1, with your own card or EcoCash number. A Visa card shows its bank’s 3-D Secure check and comes back to your checkout page (Coming back from the bank); EcoCash sends a prompt to your phone while the element waits.

  6. Don’t fulfil the order on what the browser reports. Pesepay posts the outcome to your resultUrl (The result callback); treat the post as a prompt, then check the payment status from your server and fulfil only on SUCCESS.