Mobile money approval
The customer types their phone number and approves the payment from their phone. The two methods approve it in different ways:
| Method | How the customer approves it | USD | ZiG |
|---|---|---|---|
| EcoCash | Enters their PIN in a prompt on their phone | PZW211 | PZW201 |
| O’mari | Types the code from an SMS into the same field on your page | PZW216 | PZW217 |
The method follows the transaction’s currency.
In the checkout element
Section titled “In the checkout element”There is nothing to code.
- EcoCash. After the customer presses Pay, the element shows “Check your phone” with a countdown and waits for their answer. The customer enters their PIN on their phone, never on your page.
- O’mari. The first press sends an SMS code, and the field asks for it. The customer types the code and presses Pay again.
Either way the element then shows the result and sends finished. An
unknown outcome means no answer came in time: the customer may still
approve, so don’t let them pay again (see
Accept a payment).
With your own method picker
Section titled “With your own method picker”Use the mobile element when you build the method picker yourself. Your code
differs by method:
- EcoCash: confirm once.
confirmMobilePayment()returns atprocessing, and the element waits for the customer’s answer itself. Each step arrives as astatusevent:awaiting_approval, thensucceeded,failed,reversedorunknown. There is no resend: while a prompt is live, EcoCash refuses another. - O’mari: confirm twice. The first confirm sends the SMS and returns
nextAction.type === "enter_otp", and the element’schangeevents reportstep: "otp", your cue to relabel the button. Confirm again with the same reference and element, then wait withwaitForTransaction().
<form id="mobile-form" data-reference-number="REF-1" data-provider="EcoCash"> <div id="phone"></div> <button type="submit">Pay</button> <p id="payment-message"></p></form><script type="module" src="/src/mobile-pay.ts"></script>import { loadPesepay, type MobileProvider } from "@pesepay/js";
const form = document.querySelector<HTMLFormElement>("#mobile-form")!;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!;// "EcoCash" or "Omari": the method the customer picked.const provider = form.dataset.provider as MobileProvider;
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 mobile = pesepay.elements().create("mobile", { provider }); mobile.on("change", (event) => { message.textContent = event.error?.message ?? ""; // O'mari has sent its SMS code, and the field now asks for it. if (event.step === "otp") button.textContent = "Confirm code"; }); // EcoCash: the element shows "Check your phone" and waits for the // customer's answer itself, reporting it here. mobile.on("status", ({ status }) => { if (status !== "awaiting_approval") message.textContent = status; }); mobile.mount("#phone");
form.addEventListener("submit", async (event) => { event.preventDefault();
const result = await pesepay.confirmMobilePayment(referenceNumber, { element: mobile, }); if (result.error) { message.textContent = result.error.message; return; } // O'mari, first submit: the customer types the code and submits again. if (result.transaction.nextAction?.type === "enter_otp") return;
// O'mari, second submit: wait for the result. EcoCash reports through // the status event instead. if (provider === "Omari") { const paid = result.transaction.outcome === "processing" ? await pesepay.waitForTransaction(referenceNumber) : result; message.textContent = paid.error ? paid.error.message : paid.transaction.outcome; } });}
void start();import { useState } from "react";import type { MobileProvider } from "@pesepay/js";import { Elements, MobileElement, useElements, usePesepay } from "@pesepay/react";
interface MobileFormProps { referenceNumber: string; /** "EcoCash" or "Omari": the method the customer picked. */ provider: MobileProvider;}
export function MobileForm(props: MobileFormProps) { return ( <Elements> <PayByMobile {...props} /> </Elements> );}
function PayByMobile({ referenceNumber, provider }: MobileFormProps) { const pesepay = usePesepay(); const elements = useElements(); const [label, setLabel] = useState("Pay"); const [message, setMessage] = useState("");
async function pay(): Promise<void> { const mobile = elements?.getElement("mobile"); if (!pesepay || !mobile) return;
const result = await pesepay.confirmMobilePayment(referenceNumber, { element: mobile, }); if (result.error) { setMessage(result.error.message); return; } // O'mari, first submit: the customer types the code and submits again. if (result.transaction.nextAction?.type === "enter_otp") return;
// O'mari, second submit: wait for the result. EcoCash reports through // onStatus instead. if (provider === "Omari") { const paid = result.transaction.outcome === "processing" ? await pesepay.waitForTransaction(referenceNumber) : result; setMessage(paid.error ? paid.error.message : paid.transaction.outcome); } }
return ( <form onSubmit={(event) => { event.preventDefault(); void pay(); }} > <MobileElement options={{ provider }} onChange={(event) => { setMessage(event.error?.message ?? ""); // O'mari has sent its SMS code, and the field now asks for it. if (event.step === "otp") setLabel("Confirm code"); }} // EcoCash: the element shows "Check your phone" and waits for the // customer's answer itself, reporting it here. onStatus={({ status }) => { if (status !== "awaiting_approval") setMessage(status); }} /> <button type="submit">{label}</button> <p>{message}</p> </form> );}<script setup lang="ts">import { ref } from "vue";import type { ContactChangeEvent, ElementStatusEvent, Elements as PesepayElements, MobileProvider, Pesepay,} from "@pesepay/js";import { Elements, MobileElement } from "@pesepay/vue";
const props = defineProps<{ referenceNumber: string; /** "EcoCash" or "Omari": the method the customer picked. */ provider: MobileProvider;}>();const label = ref("Pay");const message = ref("");
function onChange(event: ContactChangeEvent): void { message.value = event.error?.message ?? ""; // O'mari has sent its SMS code, and the field now asks for it. if (event.step === "otp") label.value = "Confirm code";}
// EcoCash: the element shows "Check your phone" and waits for the customer's// answer itself, reporting it here.function onStatus({ status }: ElementStatusEvent): void { if (status !== "awaiting_approval") message.value = status;}
async function pay( pesepay: Pesepay | null, elements: PesepayElements | null,): Promise<void> { const mobile = elements?.getElement("mobile"); if (!pesepay || !mobile) return;
const result = await pesepay.confirmMobilePayment(props.referenceNumber, { element: mobile, }); if (result.error) { message.value = result.error.message; return; } // O'mari, first submit: the customer types the code and submits again. if (result.transaction.nextAction?.type === "enter_otp") return;
// O'mari, second submit: wait for the result. EcoCash reports through // @status instead. if (props.provider === "Omari") { const paid = result.transaction.outcome === "processing" ? await pesepay.waitForTransaction(props.referenceNumber) : result; message.value = paid.error ? paid.error.message : paid.transaction.outcome; }}</script>
<template> <Elements v-slot="{ pesepay, elements }"> <form @submit.prevent="pay(pesepay, elements)"> <MobileElement :options="{ provider: props.provider }" @change="onChange" @status="onStatus" /> <button type="submit">{{ label }}</button> <p>{{ message }}</p> </form> </Elements></template>import { Component, computed, input, signal } from "@angular/core";import type { ContactChangeEvent, ElementStatusEvent, Elements as PesepayElements, MobileProvider, Pesepay,} from "@pesepay/js";import { Elements, MobileElement } from "@pesepay/angular";
@Component({ selector: "app-mobile-pay", imports: [Elements, MobileElement], template: ` <pesepay-elements #checkout="pesepayElements"> <form (submit)="pay($event, checkout.instance(), checkout.elements())"> <pesepay-mobile-element [options]="options()" (elementChange)="onChange($event)" (status)="onStatus($event)" /> <button type="submit">{{ label() }}</button> <p>{{ message() }}</p> </form> </pesepay-elements> `,})export class MobilePayComponent { readonly referenceNumber = input.required<string>(); /** "EcoCash" or "Omari": the method the customer picked. */ readonly provider = input.required<MobileProvider>(); protected readonly options = computed(() => ({ provider: this.provider() })); readonly label = signal("Pay"); readonly message = signal("");
onChange(event: ContactChangeEvent): void { this.message.set(event.error?.message ?? ""); // O'mari has sent its SMS code, and the field now asks for it. if (event.step === "otp") this.label.set("Confirm code"); }
// EcoCash: the element shows "Check your phone" and waits for the // customer's answer itself, reporting it here. onStatus({ status }: ElementStatusEvent): void { if (status !== "awaiting_approval") this.message.set(status); }
async pay( event: Event, pesepay: Pesepay | null, elements: PesepayElements | null, ): Promise<void> { event.preventDefault(); const mobile = elements?.getElement("mobile"); if (!pesepay || !mobile) return;
const result = await pesepay.confirmMobilePayment(this.referenceNumber(), { element: mobile, }); if (result.error) { this.message.set(result.error.message); return; } // O'mari, first submit: the customer types the code and submits again. if (result.transaction.nextAction?.type === "enter_otp") return;
// O'mari, second submit: wait for the result. EcoCash reports through // (status) instead. if (this.provider() === "Omari") { const paid = result.transaction.outcome === "processing" ? await pesepay.waitForTransaction(this.referenceNumber()) : result; this.message.set(paid.error ? paid.error.message : paid.transaction.outcome); } }}A transaction gets one O’mari SMS. If the page reloads after it went out,
create the element with resumeOtpFor: referenceNumber to start it on the
code step, but only when you know no code has been submitted. To pay again
after a failure, with either method, create a new transaction and a new
element.
What’s next
Section titled “What’s next”- Accept a payment: every outcome, and fulfilling from your server