Skip to content

Your own method picker

The checkout element lists the methods for you. Build your own picker when the methods have to sit in your own layout, for example beside your other ways to pay:

  1. listPaymentMethods() returns what Pesepay offers in the transaction’s currency. Each method is marked available when the order’s amount is within its limits. Show unavailable methods as disabled rather than hiding them.
  2. When the customer picks one, selectPaymentMethod() returns the total they will pay, fee included. Show it next to the button.
  3. Create the element for that method, and destroy the last one.
  4. Pay with confirmPayment(). It takes any element and calls the right confirm, so one button serves every method.
MethodCodeElement
VisaPZW204card
EcoCashPZW211, PZW201mobile, with provider: "EcoCash"
O’mariPZW216, PZW217mobile, with provider: "Omari"
InnBucksPZW212scan, with provider: "InnBucks"
PayGoPZW210scan, with provider: "PayGo"

The first code of each pair is for USD, the second for ZiG. Mastercard (PZW205) and Zimswitch (PZW215, PZW213) pay in the hostedCard element, which starts from startCardCheckout(): see Cards and 3-D Secure. The examples leave them out, and skip any code they don’t know.

The code is built and type-checked against the published packages.

checkout.html
<form id="picker-form" data-reference-number="REF-1">
<fieldset id="methods">
<legend>Pay with</legend>
</fieldset>
<div id="method-fields"></div>
<p id="total"></p>
<button type="submit" disabled>Pay</button>
<p id="payment-message"></p>
</form>
<script type="module" src="/src/picker-pay.ts"></script>
src/picker-pay.ts
import {
loadPesepay,
type CardElement,
type Elements,
type MobileElement,
type MobileProvider,
type ScanElement,
type ScanProvider,
} from "@pesepay/js";
const form = document.querySelector<HTMLFormElement>("#picker-form")!;
const methods = document.querySelector<HTMLElement>("#methods")!;
const total = document.querySelector<HTMLElement>("#total")!;
const button = form.querySelector<HTMLButtonElement>("button")!;
const message = document.querySelector<HTMLElement>("#payment-message")!;
// Your server created the transaction and wrote its reference number here.
const referenceNumber = form.dataset.referenceNumber!;
// The element for each method this page takes. Mastercard and Zimswitch pay
// in the hostedCard element, which starts from startCardCheckout().
type Choice =
| { type: "card" }
| { type: "mobile"; provider: MobileProvider }
| { type: "scan"; provider: ScanProvider };
const ELEMENT_FOR: Record<string, Choice> = {
PZW204: { type: "card" }, // Visa
PZW211: { type: "mobile", provider: "EcoCash" }, // USD
PZW201: { type: "mobile", provider: "EcoCash" }, // ZiG
PZW216: { type: "mobile", provider: "Omari" }, // USD
PZW217: { type: "mobile", provider: "Omari" }, // ZiG
PZW212: { type: "scan", provider: "InnBucks" }, // USD
PZW210: { type: "scan", provider: "PayGo" }, // ZiG
};
type MethodElement = CardElement | MobileElement | ScanElement;
function create(elements: Elements, choice: Choice): MethodElement {
switch (choice.type) {
case "card":
return elements.create("card");
case "mobile":
return elements.create("mobile", { provider: choice.provider });
case "scan":
return elements.create("scan", { provider: choice.provider });
}
}
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 listed = await pesepay.listPaymentMethods(referenceNumber);
if (listed.error) {
message.textContent = listed.error.message;
return;
}
const elements = pesepay.elements();
let element: MethodElement | null = null;
let paymentMethodCode = "";
const pick = async (code: string): Promise<void> => {
paymentMethodCode = code;
button.disabled = true;
button.textContent = "Pay";
message.textContent = "";
// The total the customer pays with this method, fee included.
const priced = await pesepay.selectPaymentMethod(referenceNumber, code);
if (priced.error) {
message.textContent = priced.error.message;
return;
}
const { currency, total: amount } = priced.amount;
total.textContent = `Total: ${amount.toFixed(2)} ${currency}`;
// One element at a time: destroy the last method's before creating the next.
element?.destroy();
element = create(elements, ELEMENT_FOR[code]!);
element.on("change", (event) => {
message.textContent = event.error?.message ?? "";
// O'mari has sent its SMS code, and the field now asks for it.
if ("step" in event && event.step === "otp") button.textContent = "Confirm code";
});
element.mount("#method-fields");
button.disabled = false;
};
// Unavailable methods are shown disabled: the amount is outside their limits.
for (const method of listed.paymentMethods) {
if (!ELEMENT_FOR[method.code]) continue;
const label = document.createElement("label");
const radio = document.createElement("input");
radio.type = "radio";
radio.name = "method";
radio.value = method.code;
radio.disabled = !method.available;
radio.addEventListener("change", () => void pick(method.code));
label.append(radio, ` ${method.name}`);
methods.append(label);
}
form.addEventListener("submit", async (event) => {
event.preventDefault();
if (!element) return;
// One confirm for every element. If a card needs 3-D Secure, the browser
// leaves for the bank here and comes back to the transaction's returnUrl.
const result = await pesepay.confirmPayment(referenceNumber, {
element,
paymentMethodCode,
});
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();

Pass the picked code as paymentMethodCode, so the payment uses the method you priced. An element typed as a union, such as CardElement | MobileElement | ScanElement, takes only the options every member can use: customer, metadata, paymentMethodCode and signal.

confirmPayment() returns what the element’s own confirm returns:

MethodconfirmPayment() returnsThen
Visathe outcome, or the browser leaves for the bank’s 3-D SecurehandleRedirectResult() on your return page
EcoCashprocessing; the element shows “Check your phone”waitForTransaction() while they approve
O’marinextAction.type === "enter_otp"; the field asks for the codeconfirmPayment() again with the same element
InnBucks or PayGoprocessing, with nextAction.type === "scan_code"waitForTransaction() with a five-minute timeout