Skip to content

Custom payment flow

The Quickstart uses the checkout element, which pays with its own button and runs every step itself. Use the payment element instead when you want your own Pay button and each step in your code. Your code then handles three things the checkout element does for you:

  1. O’mari’s SMS code. The first confirmPayment() returns nextAction.type === "enter_otp" and the element asks for the code. Confirm again once the customer has typed it.
  2. The wait. EcoCash and scan codes return outcome === "processing" while the customer finishes on their phone. Wait with waitForTransaction().
  3. The return page. A Visa card that needs 3-D Secure, and Mastercard or Zimswitch, leave for the bank and come back to the transaction’s returnUrl. Read the result there with handleRedirectResult().

Create the payment on your server and install Elements as in the Quickstart: Create the payment on your server and Install Elements.

Your server writes the reference number into the form:

checkout.html
<form id="payment-form" data-reference-number="REF-1">
<div id="payment"></div>
<button type="submit">Pay</button>
<p id="payment-message"></p>
</form>
<script type="module" src="/src/custom-pay.ts"></script>
src/custom-pay.ts
import { loadPesepay } from "@pesepay/js";
const form = document.querySelector<HTMLFormElement>("#payment-form")!;
const message = document.querySelector<HTMLElement>("#payment-message")!;
// Your server created the transaction and wrote its reference number here.
const referenceNumber = form.dataset.referenceNumber!;
async function start(): Promise<void> {
// Null if the runtime could not load, for example behind a content blocker.
const pesepay = await loadPesepay();
if (!pesepay) {
message.textContent = "Payments are unavailable. Please try again later.";
return;
}
const payment = pesepay.elements().create("payment", { referenceNumber });
payment.on("change", (event) => {
message.textContent = event.error?.message ?? "";
});
// The methods could not load: Pesepay's hosted checkout takes the payment.
payment.on("loaderror", (event) => {
if (event.fallbackUrl) window.location.assign(event.fallbackUrl);
});
payment.mount("#payment");
form.addEventListener("submit", async (event) => {
event.preventDefault();
// If a card needs 3-D Secure, the browser leaves for the bank here.
const result = await pesepay.confirmPayment(referenceNumber, { element: payment });
if (result.error) {
message.textContent = result.error.message;
return;
}
// O'mari: the element now asks for the code from the SMS. Pay again once
// it is typed.
if (result.transaction.nextAction?.type === "enter_otp") return;
// EcoCash or a scan code: wait while the customer finishes on their phone.
const paid =
result.transaction.outcome === "processing"
? await pesepay.waitForTransaction(referenceNumber, { timeoutMs: 300_000 })
: result;
message.textContent = paid.error ? paid.error.message : paid.transaction.outcome;
});
}
void start();

A card that leaves for its bank comes back to the returnUrl you set when you created the payment, with ?referenceNumber= added. On that page, load Elements the same way and read the result:

return page
const result = await pesepay.handleRedirectResult();
if (result.error?.code === 'no_redirect_result') {
// An ordinary page load, not a return from the bank.
} else if (result.error) {
showMessage(result.error.message);
} else {
showMessage(result.transaction.outcome); // for example "succeeded"
}

Don’t fulfil the order on what the browser reports. Confirm it on your server as in the Quickstart’s Confirm the payment on your server.