@pesepay/js
The loader for Pesepay Elements, with TypeScript types. The React, Vue and Angular packages build on it.
npm install @pesepay/js @pesepay/js is a small loader. It adds the Elements runtime from
js.pesepay.com to your page and returns a typed handle to it, so a fix
reaches your checkout in one Pesepay deploy, without an npm update. It has
no dependencies.
You can skip npm and load the same runtime with a script tag:
<script src="https://js.pesepay.com/v1/pesepay.js"></script>The script sets window.Pesepay, and Pesepay.create() returns the same
instance loadPesepay() resolves. Which path to load, and how to pin a
version, is in CDN, pinning and integrity.
Take a payment
Section titled “Take a payment”Your server creates the transaction and puts its reference number on the page. The checkout element pays it with its own button:
import { loadPesepay } from "@pesepay/js";
const container = document.querySelector<HTMLElement>("#checkout")!;const message = document.querySelector<HTMLElement>("#payment-message")!;// Your server created the transaction and wrote its reference number here.const referenceNumber = container.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 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);}
void start();The Quickstart builds the whole page, server included.
Load Pesepay
Section titled “Load Pesepay”loadPesepay() resolves the Pesepay instance, or null when there is no
browser or the runtime can’t load, such as during server-side rendering or
behind a content blocker. It is safe to call in a component that also renders
on the server.
import { loadPesepay } from '@pesepay/js';
const pesepay = await loadPesepay();if (!pesepay) return showUnavailable();Call it once per page. Its options, such as apiBaseUrl, are in the
reference.
Create and mount elements
Section titled “Create and mount elements”pesepay.elements() creates an elements group. Its options (theme,
fonts, locale) apply to every element in it; see
Appearance and theming.
elements.create(type, options) creates an element but does not mount it.
Attach your listeners first, then call mount() with a selector or an
element.
| Type | What it is | Guide |
|---|---|---|
checkout | Every method, the total and fee, and a Pay button | Quickstart |
payment | Every method, without a button: you pay with confirmPayment() | Custom payment flow |
card | Visa card fields | Cards and 3-D Secure |
hostedCard | Mastercard and Zimswitch, in the card provider’s form | Cards and 3-D Secure |
mobile | EcoCash and O’mari | Mobile money approval |
scan | InnBucks and PayGo codes | Scan to pay |
If the methods can’t be listed or a method’s fields fail to load, the
loaderror event carries fallbackUrl: Pesepay’s Hosted checkout page for the same
transaction.
Results and errors
Section titled “Results and errors”The checkout element reports once, with the finished event. Everywhere
else, every confirm resolves { transaction } or { error }. Branch on
transaction.outcome, not on status:
if (result.error?.code === 'outcome_unknown') return showChecking();if (result.error) return showError(result.error.message);
switch (result.transaction.outcome) { case 'succeeded': return showPaid(); // then confirm on your server case 'failed': return showError(result.transaction.message); case 'processing': case 'unknown': return showChecking(); case 'reversed': return showRefunded();}unknown and outcome_unknown both mean the customer may have paid. Check
the transaction before letting them pay again.
Anything a customer, card or network causes is returned as { error },
with a code from a closed list (PESEPAY_ERROR_CODES). Only programmer
errors throw, such as a selector that matches nothing, so a try/catch
around a confirm catches your bugs, not declines. Every code is in
Errors and fallbacks.
Cancel a payment
Section titled “Cancel a payment”pesepay.cancelTransaction(referenceNumber) cancels a payment nothing can
have been taken for: one not yet sent, or an O’mari payment waiting for its
code. Anything a provider may still complete returns cancel_not_allowed,
including an EcoCash prompt and Mastercard or Zimswitch once selected.
Confirm on your server
Section titled “Confirm on your server”A result in the browser is for your page. Don’t fulfil an order on it,
because anyone who controls the browser can forge it. Pesepay posts the
outcome to your server’s resultUrl; check the transaction from your server
and fulfil only on SUCCESS. See
The result callback and
Accept a payment.
TypeScript and modules
Section titled “TypeScript and modules”The types ship with the package, and your editor shows the same documentation
inline. The package is ESM only: from CommonJS, use a dynamic import().
What’s next
Section titled “What’s next”- React, Vue and Angular: the same elements as components
- Accept a payment: taking Embedded checkout to production
- Elements SDK reference: every option, event and error code