Quickstart: Embedded checkout
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”- A Pesepay account with a production integration key and encryption key
- A server that can create a payment, as in the Hosted checkout quickstart
- A web page you can edit, served over
http://localhostor HTTPS
-
Create the payment on your server
Section titled “Create the payment on your server”Create and initiate a transaction exactly as for Hosted checkout, but keep the
referenceNumberinstead of redirecting toredirectUrl. SetreturnUrlto your checkout page itself: a card that goes to its bank comes back there (see Coming back from the bank).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 pagepesepay.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$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 pagepesepay.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 pagePass the reference number to your checkout page however your app renders it: in the HTML, as a prop, or from an API call.
-
Install Elements
Section titled “Install Elements”Nothing to install. The page in the next step loads
https://js.pesepay.com/v1/pesepay.js.Terminal window npm i @pesepay/jsTerminal window npm i @pesepay/js @pesepay/reactTerminal window npm i @pesepay/js @pesepay/vueTerminal window npm i @pesepay/js @pesepay/angular -
Add the checkout element
Section titled “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.Your server writes the reference number into the page:
checkout.html <!doctype html><html lang="en"><head><meta charset="UTF-8" /><title>Checkout</title></head><body><!-- Your server created the transaction and wrote its reference number here. --><div id="checkout" data-reference-number="REF-1"></div><p id="payment-message"></p><script src="https://js.pesepay.com/v1/pesepay.js"></script><script src="checkout.js"></script></body></html>Keep the script in its own file, so a
Content-Security-Policywithout'unsafe-inline'allows it:checkout.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
integrityhash 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.Your server writes the reference number into the page:
checkout.html <div id="checkout" data-reference-number="REF-1"></div><p id="payment-message"></p><script type="module" src="/src/pay.ts"></script>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();loadPesepay()resolvesnullon the server, so it is safe to import during server-side rendering.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><CheckoutElementoptions={{ 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>);}Render it with the reference number, and say what happens next:
<CheckoutFormreferenceNumber={reference}onFinished={(outcome) => {if (outcome === 'succeeded') navigate('/order-complete');}}/>Using Next.js? Add
"use client"at the top of the file; Elements renders nothing on the server.Checkout.vue <script setup lang="ts">import type { CheckoutOutcome } from "@pesepay/js";import { CheckoutElement, Elements } from "@pesepay/vue";const props = defineProps<{ referenceNumber: string }>();// The payment has ended and the element shows the result. Fulfil the order on// your server, which Pesepay notifies too.const emit = defineEmits<{ finished: [outcome: CheckoutOutcome] }>();// The methods could not load: Pesepay's hosted checkout takes the payment.function leave(fallbackUrl: string | undefined): void {if (fallbackUrl) window.location.assign(fallbackUrl);}</script><template><Elements><CheckoutElement:options="{ referenceNumber: props.referenceNumber }"@finished="(event) => emit('finished', event.outcome)"@load-error="(event) => leave(event.fallbackUrl)"/></Elements></template>Render it with the reference number, and say what happens next:
<Checkout:reference-number="reference"@finished="(outcome) => outcome === 'succeeded' && router.push('/order-complete')"/>It is safe with server-side rendering, including Nuxt.
checkout.component.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: `<pesepay-elements><pesepay-checkout-element[options]="options()"(finished)="finished.emit($event.outcome)"(loadError)="leave($event.fallbackUrl)"/></pesepay-elements>`,})export class CheckoutComponent {readonly referenceNumber = input.required<string>();/*** The payment has ended and the element shows the result. Fulfil the order* on your server, which Pesepay notifies too.*/readonly finished = output<CheckoutOutcome>();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:
<app-checkout [referenceNumber]="reference" (finished)="onFinished($event)" />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.
finishedis sent once, with anoutcome:Outcome What it means succeededThe customer paid. failedThe 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. reversedThe customer paid, then the money was returned. unknownNo 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.
-
Coming back from the bank
Section titled “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
returnUrlyou set when you created the payment, 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 sendsfinished.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.
-
Make a small live payment
Section titled “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); EcoCash sends a prompt to your phone while the element waits.
-
Confirm the payment on your server
Section titled “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); treat the post as a prompt, then check the payment status from your server and fulfil only onSUCCESS.
What’s next
Section titled “What’s next”- Accept a payment: what a live checkout needs on top of this page
- Embedded checkout overview: how the pieces fit and where card details go
- Custom payment flow: your own Pay button, with each step in your code
- Go-live checklist: what to check before you take real orders