Skip to content

@pesepay/react

@pesepay/react npm

React components for Pesepay Elements. React 18 or 19.

npm install @pesepay/js @pesepay/react

The components create, mount and destroy the elements from @pesepay/js for you, including under Strict Mode and server rendering.

Your server creates the transaction and passes its reference number to the component:

src/CheckoutForm.tsx
import type { CheckoutOutcome } from "@pesepay/js";
import { CheckoutElement, Elements } from "@pesepay/react";
export function CheckoutForm({
referenceNumber,
onFinished,
}: {
referenceNumber: string;
onFinished: (outcome: CheckoutOutcome) => void;
}) {
return (
<Elements>
<CheckoutElement
options={{ referenceNumber }}
// The payment has ended and the element shows the result. Fulfil the
// order on your server, which Pesepay notifies too.
onFinished={(event) => onFinished(event.outcome)}
// The methods could not load: Pesepay's hosted checkout takes the payment.
onLoadError={(event) => {
if (event.fallbackUrl) window.location.assign(event.fallbackUrl);
}}
/>
</Elements>
);
}

<CheckoutElement> lists the methods and pays with its own button. It runs every step itself, including the result when the customer comes back from 3-D Secure, and calls onFinished once with outcome: succeeded, failed, reversed or unknown. For your own Pay button, see Custom payment flow.

PropTypeNotes
pesepayPesepay | null | Promise<Pesepay | null>Optional. What loadPesepay() returns. Fixed on first render.
optionsElementsOptionstheme, fonts, locale for every element inside. Changes are applied.
childrenReactNode

Left out, pesepay defaults to loading Pesepay with the default options in the browser. To set options, such as apiBaseUrl, call loadPesepay({ apiBaseUrl }) once, outside the component, and pass the promise.

<Elements> creates one elements group and destroys it, and every element in it, when it unmounts. Group-wide options that change are passed to elements.update().

usePesepay() and useElements() return the instance and the group, or null while Pesepay loads and during server rendering. Both throw outside <Elements>.

ComponentElementoptions
<CheckoutElement>checkoutrequired: { referenceNumber }
<PaymentElement>paymentrequired: { referenceNumber }
<CardElement>cardoptional
<MobileElement>mobileoptional: { provider }, …
<ScanElement>scanoptional: { provider }
<HostedCardElement>hostedCardrequired: { cardCheckout }

Each renders a <div>, with your id and className, and mounts its element into it. Event props are typed for the element: onReady, onChange, onFocus, onBlur, onEscape and onLoadError, plus onStatus on the mobile and payment elements and onFinished on the checkout element. A new handler on each render is fine; it does not subscribe again.

Changed options are passed to the element’s update(). A payment or checkout element given a new referenceNumber is replaced, since one element pays one transaction.

Outside the checkout element, to pay, read the element off the group with elements.getElement(type) and pass it to confirmPayment(). One <Elements> holds one element of each type; for two card fields, use two <Elements>.

<Elements> loads nothing on the server, and loadPesepay() resolves null there, so <Elements> renders its children and each element component renders an empty <div>. The components are marked "use client", so the Next.js App Router can import them from a server component. See Server-side rendering for a Next.js checkout page.