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:
- O’mari’s SMS code. The first
confirmPayment()returnsnextAction.type === "enter_otp"and the element asks for the code. Confirm again once the customer has typed it. - The wait. EcoCash and scan codes return
outcome === "processing"while the customer finishes on their phone. Wait withwaitForTransaction(). - 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 withhandleRedirectResult().
Create the payment on your server and install Elements as in the Quickstart: Create the payment on your server and Install Elements.
Pay with your own button
Section titled “Pay with your own button”Your server writes the reference number into the form:
<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>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();import { useState } from "react";import { Elements, PaymentElement, useElements, usePesepay } from "@pesepay/react";
export function CheckoutForm({ referenceNumber }: { referenceNumber: string }) { return ( <Elements> <PayForm referenceNumber={referenceNumber} /> </Elements> );}
function PayForm({ referenceNumber }: { referenceNumber: string }) { const pesepay = usePesepay(); const elements = useElements(); const [message, setMessage] = useState("");
async function pay(): Promise<void> { const payment = elements?.getElement("payment"); if (!pesepay || !payment) return;
// 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) { setMessage(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; setMessage(paid.error ? paid.error.message : paid.transaction.outcome); }
return ( <form onSubmit={(event) => { event.preventDefault(); void pay(); }} > <PaymentElement options={{ referenceNumber }} onChange={(event) => setMessage(event.error?.message ?? "")} // The methods could not load: Pesepay's hosted checkout takes the payment. onLoadError={(event) => { if (event.fallbackUrl) window.location.assign(event.fallbackUrl); }} /> <button type="submit">Pay</button> <p>{message}</p> </form> );}usePesepay() and useElements() return null until Pesepay has
loaded, which is why pay() checks both.
<script setup lang="ts">import { ref } from "vue";import type { Elements as PesepayElements, Pesepay } from "@pesepay/js";import { Elements, PaymentElement } from "@pesepay/vue";
const props = defineProps<{ referenceNumber: string }>();const message = ref("");
// The methods could not load: Pesepay's hosted checkout takes the payment.function leave(fallbackUrl: string | undefined): void { if (fallbackUrl) window.location.assign(fallbackUrl);}
async function pay( pesepay: Pesepay | null, elements: PesepayElements | null,): Promise<void> { const payment = elements?.getElement("payment"); if (!pesepay || !payment) return;
// If a card needs 3-D Secure, the browser leaves for the bank here. const result = await pesepay.confirmPayment(props.referenceNumber, { element: payment, }); if (result.error) { message.value = 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(props.referenceNumber, { timeoutMs: 300_000 }) : result; message.value = paid.error ? paid.error.message : paid.transaction.outcome;}</script>
<template> <Elements v-slot="{ pesepay, elements }"> <form @submit.prevent="pay(pesepay, elements)"> <PaymentElement :options="{ referenceNumber: props.referenceNumber }" @change="(event) => (message = event.error?.message ?? '')" @load-error="(event) => leave(event.fallbackUrl)" /> <button type="submit">Pay</button> <p>{{ message }}</p> </form> </Elements></template><Elements> hands its default slot the Pesepay instance and the elements
group, so the component that renders it can pay. A child component can
read the same two with usePesepay() and useElements().
import { Component, computed, input, signal } from "@angular/core";import type { Elements as PesepayElements, Pesepay } from "@pesepay/js";import { Elements, PaymentElement } from "@pesepay/angular";
@Component({ selector: "app-custom-checkout", imports: [Elements, PaymentElement], template: ` <pesepay-elements #checkout="pesepayElements"> <form (submit)="pay($event, checkout.instance(), checkout.elements())"> <pesepay-payment-element [options]="options()" (elementChange)="message.set($event.error?.message ?? '')" (loadError)="leave($event.fallbackUrl)" /> <button type="submit">Pay</button> <p>{{ message() }}</p> </form> </pesepay-elements> `,})export class CustomCheckoutComponent { readonly referenceNumber = input.required<string>(); protected readonly options = computed(() => ({ referenceNumber: this.referenceNumber(), })); readonly message = signal("");
// The methods could not load: Pesepay's hosted checkout takes the payment. leave(fallbackUrl: string | undefined): void { if (fallbackUrl) window.location.assign(fallbackUrl); }
async pay( event: Event, pesepay: Pesepay | null, elements: PesepayElements | null, ): Promise<void> { event.preventDefault(); const payment = elements?.getElement("payment"); if (!pesepay || !payment) return;
// If a card needs 3-D Secure, the browser leaves for the bank here. const result = await pesepay.confirmPayment(this.referenceNumber(), { element: payment, }); if (result.error) { this.message.set(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(this.referenceNumber(), { timeoutMs: 300_000, }) : result; this.message.set(paid.error ? paid.error.message : paid.transaction.outcome); }}#checkout="pesepayElements" gives the template the Pesepay instance and
the elements group. A component inside it can read the same two with
injectPesepay() and injectElements(). The payment element’s change
event is the (elementChange) output: Angular would also deliver the DOM
change events that bubble out of the card provider’s form to an output
named change.
Handle the return from the bank
Section titled “Handle the return from the bank”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:
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"}Confirm the payment on your server
Section titled “Confirm the payment on your server”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.
What’s next
Section titled “What’s next”- Your own method picker: list the methods yourself, with one element per method
- Errors and fallbacks: what to show for each result