. export function Checkout({ referenceNumber }: { referenceNumber: string }) { const router = useRouter(); return (
{ if (event.outcome === "succeeded") router.push("/order-complete"); }} // The methods could not load: Pesepay's hosted checkout takes the payment. onLoadError={(event) => { if (event.fallbackUrl) window.location.assign(event.fallbackUrl); }} /> ); } ``` ## What’s next [Section titled “What’s next”](#whats-next) * [Accept a payment](/embedded-checkout/guides/accept-a-payment/): one transaction per order, and fulfilling from your server
# Appearance and theming
> Match Embedded checkout to your site with a theme of colours, fonts, spacing and labels, and load a web font into the card fields.
Every element takes a theme: colours, fonts, spacing, labels and states, from a fixed list of tokens. Set it once for a group of elements, and every element in the group uses it. The elements are isolated from your page’s CSS. The in-page elements render inside a shadow root and the card fields inside a frame on a Pesepay origin, so a rule in your stylesheet doesn’t reach them, and theirs don’t reach your page. The theme is how you style them. ## A theme [Section titled “A theme”](#a-theme) appearance.ts ```ts import type { ElementsOptions } from "@pesepay/js"; // One look for every element in the group. Only these token names are // accepted: the theme is a fixed vocabulary, not a stylesheet. export const appearance: ElementsOptions = { // The card fields are in their own frame, so they need the font passed here. fonts: [{ cssSrc: "https://fonts.googleapis.com/css2?family=Inter:wght@400;600" }], theme: { preset: "flat", labels: "floating", colors: { primary: "#0f766e", borderFocus: "#0f766e", error: "#b91c1c" }, fonts: { family: "Inter, system-ui, sans-serif", size: "15px" }, spacing: { borderRadius: "8px", padding: "12px", gap: "16px" }, }, }; ``` * `preset` starts from a ready-made look: `"night"` (dark fields) or `"flat"` (no visible border, on a light grey fill). Any token you set overrides the preset’s value. A preset sets colours, border radius and the focus ring only. * `labels` is `"above"`, `"floating"` (inside the field, moving up once it has focus or a value) or `"hidden"`. A hidden label is still read by screen readers. * `colors.primary` colours the picked method and the checkout element’s Pay button; `colors.primaryText` is the button’s text. Every token, with its default, is on the [PesepayTheme](/embedded-checkout/reference/js/pesepay-theme/) reference page. ## Pass it to the elements [Section titled “Pass it to the elements”](#pass-it-to-the-elements) Pass the theme and fonts where the group is created: `elements()` in JavaScript, the `options` of `
` in the components. A change to them is applied to every element in the group. The code is built and type-checked against the published packages. * JavaScript src/themed-checkout.ts ```ts import { loadPesepay } from "@pesepay/js"; import { appearance } from "./appearance.js"; const container = document.querySelector("#checkout")!; const message = document.querySelector("#payment-message")!; // Your server created the transaction and wrote its reference number here. const referenceNumber = container.dataset.referenceNumber!; async function start(): Promise { // 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; } // Every element created from this group takes the theme and the font. const elements = pesepay.elements(appearance); const checkout = elements.create("checkout", { referenceNumber }); checkout.on("finished", (event) => { if (event.outcome === "succeeded") window.location.assign("/order-complete"); }); checkout.on("loaderror", (event) => { if (event.fallbackUrl) window.location.assign(event.fallbackUrl); }); checkout.mount(container); } void start(); ``` * React ThemedCheckout.tsx ```tsx import type { CheckoutOutcome } from "@pesepay/js"; import { CheckoutElement, Elements } from "@pesepay/react"; import { appearance } from "./appearance.js"; export function ThemedCheckout({ referenceNumber, onFinished, }: { referenceNumber: string; onFinished: (outcome: CheckoutOutcome) => void; }) { return ( // Every element inside takes the theme and the font. onFinished(event.outcome)} onLoadError={(event) => { if (event.fallbackUrl) window.location.assign(event.fallbackUrl); }} /> ); } ``` * Vue ThemedCheckout.vue ```vue emit('finished', event.outcome)" @load-error="(event) => leave(event.fallbackUrl)" /> ``` * Angular themed-checkout.component.ts ```ts import { Component, computed, input, output } from "@angular/core"; import type { CheckoutOutcome } from "@pesepay/js"; import { CheckoutElement, Elements } from "@pesepay/angular"; import { appearance } from "./appearance"; @Component({ selector: "app-themed-checkout", imports: [Elements, CheckoutElement], template: ` `, }) export class ThemedCheckoutComponent { readonly referenceNumber = input.required(); readonly finished = output(); protected readonly appearance = appearance; protected readonly options = computed(() => ({ referenceNumber: this.referenceNumber(), })); leave(fallbackUrl: string | undefined): void { if (fallbackUrl) window.location.assign(fallbackUrl); } } ``` A theme can also be set on the instance, with `loadPesepay({ theme })`, and on one element, with its `theme` option. The three are merged in that order, section by section, so an element that overrides `colors` keeps the group’s `fonts`. ## Web fonts [Section titled “Web fonts”](#web-fonts) The card fields are in their own frame, so a font your page loads does not reach them. Pass it in `fonts` and name it in `theme.fonts.family`, as above. * `cssSrc` must be a Google Fonts `css2` URL. Any other URL throws, and so do more than 8 fonts. A stylesheet you write yourself is not accepted, because a font can be built so that each digit typed fetches its own file. * Your page’s Content-Security-Policy needs nothing more: the fonts load inside the frame. * The mobile and scan elements render in your page, so they use the fonts your page already loads. The Mastercard and Zimswitch form is the card provider’s own; it uses `theme.fonts.family` only if the customer has the font installed. ## What a theme can’t do [Section titled “What a theme can’t do”](#what-a-theme-cant-do) Only known token names are accepted, and a value is dropped (the default is used) if it is longer than 200 characters or contains `;`, `{`, `}`, `<`, `>`, `\` or `/*`. Arbitrary CSS is left out on purpose: in card fields it would let a stylesheet read what the customer types, for example through `background-image: url(...)` rules. ## What’s next [Section titled “What’s next”](#whats-next) * [Your own method picker](/embedded-checkout/guides/method-picker/): one element per method, all sharing one theme
# @pesepay/js
> The Pesepay Elements loader for any page or framework: loading the runtime, creating elements, and handling results and errors.
 `@pesepay/js` [npm](https://www.npmjs.com/package/@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: ```html ``` 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](/embedded-checkout/guides/cdn-and-pinning/). ## Take a payment [Section titled “Take a payment”](#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: src/pay.ts ```ts import { loadPesepay } from "@pesepay/js"; const container = document.querySelector("#checkout")!; const message = document.querySelector("#payment-message")!; // Your server created the transaction and wrote its reference number here. const referenceNumber = container.dataset.referenceNumber!; async function start(): Promise { // 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](/embedded-checkout/quickstart/) builds the whole page, server included. ## Load Pesepay [Section titled “Load Pesepay”](#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. ```ts 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](/embedded-checkout/reference/js/load-pesepay/). ## Create and mount elements [Section titled “Create and mount elements”](#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](/embedded-checkout/guides/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](/embedded-checkout/quickstart/) | | `payment` | Every method, without a button: you pay with `confirmPayment()` | [Custom payment flow](/embedded-checkout/custom-payment-flow/) | | `card` | Visa card fields | [Cards and 3-D Secure](/embedded-checkout/guides/cards/) | | `hostedCard` | Mastercard and Zimswitch, in the card provider’s form | [Cards and 3-D Secure](/embedded-checkout/guides/cards/) | | `mobile` | EcoCash and O’mari | [Mobile money approval](/embedded-checkout/guides/mobile-money/) | | `scan` | InnBucks and PayGo codes | [Scan to pay](/embedded-checkout/guides/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”](#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`: ```ts 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](/embedded-checkout/guides/errors/). ## Cancel a payment [Section titled “Cancel a payment”](#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”](#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](/webhooks/result-callback/) and [Accept a payment](/embedded-checkout/guides/accept-a-payment/). ## TypeScript and modules [Section titled “TypeScript and modules”](#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”](#whats-next) * [React](/embedded-checkout/react/), [Vue](/embedded-checkout/vue/) and [Angular](/embedded-checkout/angular/): the same elements as components * [Accept a payment](/embedded-checkout/guides/accept-a-payment/): taking Embedded checkout to production * [Elements SDK reference](/embedded-checkout/reference/js/): every option, event and error code
# Migrate from the Direct API
> Move a Direct API (formerly Seamless) integration to Embedded checkout, with what stays, what changes and where each request field goes.
This page is for a merchant who already runs the [Direct API](/payments/direct-api/) (formerly Seamless) on a web checkout and wants more payment methods. It shows what changes, side by side, rather than starting from scratch. ## Why move [Section titled “Why move”](#why-move) * **Cards with 3-D Secure.** Visa, Mastercard and Zimswitch work in the element. The Direct API takes no cards. * **Every method in one component.** The checkout element lists each method the transaction can be paid with, priced per method. * **No card data on your servers.** Card fields run in a frame on a Pesepay origin, so your page cannot read them. * **The waiting is handled.** The element asks for the O’mari code, waits for the EcoCash approval or the scanned code, and shows the result. ## What stays [Section titled “What stays”](#what-stays) * Your integration key and encryption key. * Your result callback handler at `resultUrl`. * Your server-side status check before you fulfil an order. A payment is paid only when its [`transactionStatus`](/resources/transaction-statuses/) is `SUCCESS`. ## What changes [Section titled “What changes”](#what-changes) The single encrypted charge call splits in two. Your server **creates** the payment, and the customer **pays** in the element on your page. Your own phone-number form and waiting screen go away. ### On your server [Section titled “On your server”](#on-your-server) * Node.js Before: Direct API ```js const payment = pesepay.createPayment('USD', 'PZW211', email, phone, name); const requiredFields = { customerPhoneNumber: phone }; const response = await pesepay.makeSeamlessPayment(payment, 'Order #1042', 10.0, requiredFields); // then poll response.pollUrl while the customer approves ``` After: Embedded checkout ```js pesepay.resultUrl = 'https://example.com/payments/result'; pesepay.returnUrl = 'https://example.com/checkout'; const transaction = pesepay.createTransaction(10.0, 'USD', 'Order #1042'); const response = await pesepay.initiateTransaction(transaction); const referenceNumber = response.referenceNumber; // send this to your page ``` * Python Before: Direct API ```python payment = pesepay.create_payment("USD", "PZW211", email, phone, name) required_fields = {"customerPhoneNumber": phone} response = pesepay.make_seamless_payment(payment, "Order #1042", 10.0, required_fields) # then poll response.poll_url while the customer approves ``` After: Embedded checkout ```python pesepay.result_url = "https://example.com/payments/result" pesepay.return_url = "https://example.com/checkout" transaction = pesepay.create_transaction(10.0, "USD", "Order #1042") response = pesepay.initiate_transaction(transaction) reference_number = response.reference_number # send this to your page ``` * PHP Before: Direct API ```php $payment = $pesepay->createPayment('USD', 'PZW211', $email, $phone, $name); $requiredFields = ['customerPhoneNumber' => $phone]; $response = $pesepay->makeSeamlessPayment($payment, 'Order #1042', 10.0, $requiredFields); // then poll $response->pollUrl() while the customer approves ``` After: Embedded checkout ```php $pesepay->resultUrl = 'https://example.com/payments/result'; $pesepay->returnUrl = 'https://example.com/checkout'; $transaction = $pesepay->createTransaction(10.0, 'USD', 'Order #1042'); $response = $pesepay->initiateTransaction($transaction); $referenceNumber = $response->referenceNumber(); // send this to your page ``` * Java Before: Direct API ```java Payment payment = pesepay.createPayment("USD", "PZW211", email); Map requiredFields = new HashMap<>(); requiredFields.put("customerPhoneNumber", phone); Response response = pesepay.makeSeamlessPayment(payment, "Order #1042", 10.0, requiredFields); // then poll response.getPollUrl() while the customer approves ``` After: Embedded checkout ```java pesepay.setResultUrl("https://example.com/payments/result"); pesepay.setReturnUrl("https://example.com/checkout"); Transaction transaction = pesepay.createTransaction(10.0, "USD", "Order #1042"); Response response = pesepay.initiateTransaction(transaction); String referenceNumber = response.getReferenceNumber(); // send this to your page ``` The new call is the one Hosted checkout uses ([Initiate Transaction](/api/initiate-transaction/)). You keep the `referenceNumber` instead of redirecting to `redirectUrl`, and `returnUrl` points at your checkout page, where a card payment comes back after 3-D Secure. ### On your page [Section titled “On your page”](#on-your-page) Your method picker, phone-number field and waiting screen are replaced by the checkout element: src/pay.ts ```ts import { loadPesepay } from "@pesepay/js"; const container = document.querySelector("#checkout")!; const message = document.querySelector("#payment-message")!; // Your server created the transaction and wrote its reference number here. const referenceNumber = container.dataset.referenceNumber!; async function start(): Promise { // 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](/embedded-checkout/quickstart/) has the same code for a script tag, React, Vue and Angular. Want your own Pay button? See [Custom payment flow](/embedded-checkout/custom-payment-flow/). ## Where each field goes [Section titled “Where each field goes”](#where-each-field-goes) | Direct API (`make-payment`) | Embedded checkout | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `amountDetails`, `reasonForPayment`, `resultUrl`, `merchantReference`, `paymentMetadata` | The server’s create call, unchanged | | `returnUrl` | The server’s create call, where it is required. Set it to your checkout page | | `paymentMethodCode` | The element: the customer picks the method. On the create call it only preselects one | | `paymentMethodRequiredFields` (phone number, O’mari code) | The element asks for them | | `customer` | Not sent by the checkout element. With your own Pay button, pass it to `confirmPayment()` as `customer` | | The encrypted `make-payment` call | Gone: the customer confirms in the element | | Polling `pollUrl` | The element waits for the outcome. Your server still confirms through the result callback and a status check | ## Running both [Section titled “Running both”](#running-both) You don’t have to switch every checkout at once. Offer Embedded checkout to a share of your customers and keep the Direct API for the rest. Both paths report to the same result URL, so your callback handler and status checks work unchanged for each.
# Quickstart: Embedded checkout
> Take your first payment on your own page with Pesepay Elements, in plain HTML, JavaScript, React, Vue or Angular.
This page takes a real payment: by the end of it you will have paid a small amount, with your own card or EcoCash number and production keys, on your own checkout page, and your server will know about it. Pick your framework once in any tab and every tab on the page follows. ### Prerequisites [Section titled “Prerequisites”](#prerequisites) * A [Pesepay account](/getting-started/onboarding/) with a production **integration key** and **encryption key** * A server that can create a payment, as in the [Hosted checkout quickstart](/getting-started/quickstart/) * A web page you can edit, served over `http://localhost` or HTTPS 1. ### Create the payment on your server [Section titled “Create the payment on your server”](#create-the-payment-on-your-server) Create and initiate a transaction exactly as for Hosted checkout, but keep the `referenceNumber` instead of redirecting to `redirectUrl`. Set `returnUrl` to your checkout page itself: a card that goes to its bank comes back there (see [Coming back from the bank](#coming-back-from-the-bank)). * Node.js ```js pesepay.resultUrl = 'https://example.com/payments/result'; pesepay.returnUrl = 'https://example.com/checkout'; const transaction = pesepay.createTransaction(10.0, 'USD', 'Order #1042'); const response = await pesepay.initiateTransaction(transaction); const referenceNumber = response.referenceNumber; // send this to your page ``` * Python ```python pesepay.result_url = "https://example.com/payments/result" pesepay.return_url = "https://example.com/checkout" transaction = pesepay.create_transaction(10.0, "USD", "Order #1042") response = pesepay.initiate_transaction(transaction) reference_number = response.reference_number # send this to your page ``` * PHP ```php $pesepay->resultUrl = 'https://example.com/payments/result'; $pesepay->returnUrl = 'https://example.com/checkout'; $transaction = $pesepay->createTransaction(10.0, 'USD', 'Order #1042'); $response = $pesepay->initiateTransaction($transaction); $referenceNumber = $response->referenceNumber(); // send this to your page ``` * Java ```java pesepay.setResultUrl("https://example.com/payments/result"); pesepay.setReturnUrl("https://example.com/checkout"); Transaction transaction = pesepay.createTransaction(10.0, "USD", "Order #1042"); Response response = pesepay.initiateTransaction(transaction); String referenceNumber = response.getReferenceNumber(); // send this to your page ``` Pass the reference number to your checkout page however your app renders it: in the HTML, as a prop, or from an API call. 2. ### Install Elements [Section titled “Install Elements”](#install-elements) * Script tag Nothing to install. The page in the next step loads `https://js.pesepay.com/v1/pesepay.js`. * JavaScript ```bash npm i @pesepay/js ``` * React ```bash npm i @pesepay/js @pesepay/react ``` * Vue ```bash npm i @pesepay/js @pesepay/vue ``` * Angular ```bash npm i @pesepay/js @pesepay/angular ``` 3. ### Add the checkout element [Section titled “Add the checkout element”](#add-the-checkout-element) The checkout element lists every method the transaction can be paid with, shows the total and fee for the one the customer picks, shows that method’s fields, and pays with its own button. Your code listens for one event, `finished`. * Script tag Your server writes the reference number into the page: checkout.html ```html Checkout ``` Keep the script in its own file, so a `Content-Security-Policy` without `'unsafe-inline'` allows it: checkout.js ```js const container = document.getElementById("checkout"); const message = document.getElementById("payment-message"); const referenceNumber = container.dataset.referenceNumber; // Unset if the script tag was blocked, for example by a content blocker. const pesepay = window.Pesepay?.create({}); if (pesepay) { 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); } else { message.textContent = "Payments are unavailable. Please try again later."; } ``` Don’t add an `integrity` hash to `/v1/pesepay.js`: it is patched in place so security fixes reach you without a redeploy, and a patched file no longer matches the hash. * JavaScript Your server writes the reference number into the page: checkout.html ```html ``` src/pay.ts ```ts import { loadPesepay } from "@pesepay/js"; const container = document.querySelector("#checkout")!; const message = document.querySelector("#payment-message")!; // Your server created the transaction and wrote its reference number here. const referenceNumber = container.dataset.referenceNumber!; async function start(): Promise { // 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(); ``` `loadPesepay()` resolves `null` on the server, so it is safe to import during server-side rendering. * React CheckoutForm.tsx ```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 ( 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); }} /> ); } ``` Render it with the reference number, and say what happens next: ```tsx { if (outcome === 'succeeded') navigate('/order-complete'); }} /> ``` Using Next.js? Add `"use client"` at the top of the file; Elements renders nothing on the server. * Vue Checkout.vue ```vue emit('finished', event.outcome)" @load-error="(event) => leave(event.fallbackUrl)" /> ``` Render it with the reference number, and say what happens next: ```vue outcome === 'succeeded' && router.push('/order-complete')" /> ``` It is safe with server-side rendering, including Nuxt. * Angular checkout.component.ts ```ts import { Component, computed, input, output } from "@angular/core"; import type { CheckoutOutcome } from "@pesepay/js"; import { CheckoutElement, Elements } from "@pesepay/angular"; @Component({ selector: "app-checkout", imports: [Elements, CheckoutElement], template: ` `, }) export class CheckoutComponent { readonly referenceNumber = input.required(); /** * The payment has ended and the element shows the result. Fulfil the order * on your server, which Pesepay notifies too. */ readonly finished = output(); protected readonly options = computed(() => ({ referenceNumber: this.referenceNumber(), })); // The methods could not load: Pesepay's hosted checkout takes the payment. leave(fallbackUrl: string | undefined): void { if (fallbackUrl) window.location.assign(fallbackUrl); } } ``` Render it with the reference number, and say what happens next: ```html ``` It is safe with server-side rendering. For O’mari, the element’s button then asks for the code from the SMS. For EcoCash and scan codes, the element waits while the customer finishes on their phone. `finished` is sent once, with an `outcome`: | Outcome | What it means | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `succeeded` | The customer paid. | | `failed` | The customer did not pay: declined, cancelled or closed. A declined transaction can’t be paid again: create a new one to let the customer retry. | | `reversed` | The customer paid, then the money was returned. | | `unknown` | No answer came in time. The customer may still pay, so don’t let them pay again until your server has the result. | Want your own Pay button, with each step in your code? See [Custom payment flow](/embedded-checkout/custom-payment-flow/). 4. ### Coming back from the bank [Section titled “Coming back from the bank”](#coming-back-from-the-bank) A Visa card that needs 3-D Secure, and Mastercard or Zimswitch, take the customer to their bank. They come back to the `returnUrl` you set when you [created the payment](#create-the-payment-on-your-server), your checkout page, with `?referenceNumber=` added. Render the page with the same reference number, reusing the order’s transaction rather than creating a new one. The element shows the result in place of the methods and sends `finished`. A transaction that is already paid, or still being paid, is never offered the methods again: the element shows its result, or waits for it. 5. ### Make a small live payment [Section titled “Make a small live payment”](#make-a-small-live-payment) Open your checkout page with the order’s reference number and pay a small amount, such as USD 1, with your own card or EcoCash number. A Visa card shows its bank’s 3-D Secure check and comes back to your checkout page ([Coming back from the bank](#coming-back-from-the-bank)); EcoCash sends a prompt to your phone while the element waits. 6. ### Confirm the payment on your server [Section titled “Confirm the payment on your server”](#confirm-the-payment-on-your-server) Don’t fulfil the order on what the browser reports. Pesepay posts the outcome to your `resultUrl` ([The result callback](/webhooks/result-callback/)); treat the post as a prompt, then [check the payment status](/api/check-payment-status/) from your server and fulfil only on `SUCCESS`. ## What’s next [Section titled “What’s next”](#whats-next) * [Accept a payment](/embedded-checkout/guides/accept-a-payment/): what a live checkout needs on top of this page * [Embedded checkout overview](/embedded-checkout/): how the pieces fit and where card details go * [Custom payment flow](/embedded-checkout/custom-payment-flow/): your own Pay button, with each step in your code * [Go-live checklist](/getting-started/go-live-checklist/): what to check before you take real orders
# @pesepay/react
> React components for Pesepay Elements, with hooks, Strict Mode and server rendering.
 `@pesepay/react` [npm](https://www.npmjs.com/package/@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`](/embedded-checkout/javascript/) for you, including under Strict Mode and server rendering. ## Take a payment [Section titled “Take a payment”](#take-a-payment) Your server creates the transaction and passes its reference number to the component: src/CheckoutForm.tsx ```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 ( 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); }} /> ); } ``` `` 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](/embedded-checkout/custom-payment-flow/). ## `` [Section titled “\”](#elements) | Prop | Type | Notes | | ---------- | --------------------------------------------- | ------------------------------------------------------------------------- | | `pesepay` | `Pesepay \| null \| Promise` | 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. `` 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 ``. ## Element components [Section titled “Element components”](#element-components) | Component | Element | `options` | | --------------------- | ------------ | ------------------------------- | | `` | `checkout` | required: `{ referenceNumber }` | | `` | `payment` | required: `{ referenceNumber }` | | `` | `card` | optional | | `` | `mobile` | optional: `{ provider }`, … | | `` | `scan` | optional: `{ provider }` | | `` | `hostedCard` | required: `{ cardCheckout }` | Each renders a ``, 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 `
` holds one element of each type; for two card fields, use two ``. ## Server rendering [Section titled “Server rendering”](#server-rendering) `` loads nothing on the server, and `loadPesepay()` resolves `null` there, so `` renders its children and each element component renders an empty ``. The components are marked `"use client"`, so the Next.js App Router can import them from a server component. See [Server-side rendering](/embedded-checkout/guides/server-rendering/) for a Next.js checkout page. ## What’s next [Section titled “What’s next”](#whats-next) * [Quickstart](/embedded-checkout/quickstart/): the whole checkout, server included * [Guides](/embedded-checkout/guides/accept-a-payment/): each method, errors and theming, with React code * [Elements SDK reference](/embedded-checkout/reference/react/): every component, prop and hook
# @pesepay/vue
> Vue components for Pesepay Elements, with composables and server rendering, including Nuxt.
 `@pesepay/vue` [npm](https://www.npmjs.com/package/@pesepay/vue) Vue components for Pesepay Elements. Vue 3.5 or later. `npm install @pesepay/js @pesepay/vue` The components create, mount and destroy the elements from [`@pesepay/js`](/embedded-checkout/javascript/) for you, including under server rendering. ## Take a payment [Section titled “Take a payment”](#take-a-payment) Your server creates the transaction and passes its reference number to the component: src/Checkout.vue ```vue
emit('finished', event.outcome)" @load-error="(event) => leave(event.fallbackUrl)" /> ``` `
` 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 emits `finished` once with `outcome`: `succeeded`, `failed`, `reversed` or `unknown`. For your own Pay button, see [Custom payment flow](/embedded-checkout/custom-payment-flow/). ## `` [Section titled “\”](#elements) | Prop | Type | Notes | | --------- | --------------------------------------------- | ------------------------------------------------------------------------- | | `pesepay` | `Pesepay \| null \| Promise` | Optional. What `loadPesepay()` returns. Fixed on first render. | | `options` | `ElementsOptions` | `theme`, `fonts`, `locale` for every element inside. Changes are applied. | 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. `` creates one elements group once it is mounted and Pesepay has loaded, and destroys it, and every element in it, when it unmounts. Group-wide options that change, including a reactive object changed in place, are passed to `elements.update()`. Its default slot receives `{ pesepay, elements }`, so the component that renders `` can pay. In a child component, `usePesepay()` and `useElements()` return the same two as shallow refs. All of them are `null` while Pesepay loads and during server rendering. The composables throw outside ``. ## Element components [Section titled “Element components”](#element-components) | Component | Element | `options` | | --------------------- | ------------ | ------------------------------- | | `` | `checkout` | required: `{ referenceNumber }` | | `` | `payment` | required: `{ referenceNumber }` | | `` | `card` | optional | | `` | `mobile` | optional: `{ provider }`, … | | `` | `scan` | optional: `{ provider }` | | `` | `hostedCard` | required: `{ cardCheckout }` | Each renders a ``, with your `id` and `class`, and mounts its element into it. Events are typed for the element: `@ready`, `@change`, `@focus`, `@blur`, `@escape` and `@load-error`, plus `@status` on the mobile and payment elements and `@finished` on the checkout element. 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 `
` holds one element of each type; for two card fields, use two ``. ## Server rendering [Section titled “Server rendering”](#server-rendering) `` loads nothing before it is mounted, and `loadPesepay()` resolves `null` on the server. On the server, and in Nuxt, each element component renders an empty ``. See [Server-side rendering](/embedded-checkout/guides/server-rendering/). ## What’s next [Section titled “What’s next”](#whats-next) * [Quickstart](/embedded-checkout/quickstart/): the whole checkout, server included * [Guides](/embedded-checkout/guides/accept-a-payment/): each method, errors and theming, with Vue code * [Elements SDK reference](/embedded-checkout/reference/vue/): every component, prop and composable