@pesepay/react
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.
Take a payment
Section titled “Take a payment”Your server creates the transaction and passes its reference number to the component:
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.
<Elements>
Section titled “<Elements>”| Prop | Type | Notes |
|---|---|---|
pesepay | Pesepay | null | Promise<Pesepay | null> | Optional. What loadPesepay() returns. Fixed on first render. |
options | ElementsOptions | theme, fonts, locale for every element inside. Changes are applied. |
children | ReactNode |
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>.
Element components
Section titled “Element components”| Component | Element | options |
|---|---|---|
<CheckoutElement> | checkout | required: { referenceNumber } |
<PaymentElement> | payment | required: { referenceNumber } |
<CardElement> | card | optional |
<MobileElement> | mobile | optional: { provider }, … |
<ScanElement> | scan | optional: { provider } |
<HostedCardElement> | hostedCard | required: { 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>.
Server rendering
Section titled “Server rendering”<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.
What’s next
Section titled “What’s next”- Quickstart: the whole checkout, server included
- Guides: each method, errors and theming, with React code
- Elements SDK reference: every component, prop and hook