Skip to content

@pesepay/js

@pesepay/js npm

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.

Your server creates the transaction and puts its reference number on the page. The checkout element pays it with its own button:

src/pay.ts
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.

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.

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.

TypeWhat it isGuide
checkoutEvery method, the total and fee, and a Pay buttonQuickstart
paymentEvery method, without a button: you pay with confirmPayment()Custom payment flow
cardVisa card fieldsCards and 3-D Secure
hostedCardMastercard and Zimswitch, in the card provider’s formCards and 3-D Secure
mobileEcoCash and O’mariMobile money approval
scanInnBucks and PayGo codesScan 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.

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.

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.

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.

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().