Cards and 3-D Secure
Card details never reach your page. Visa is typed into Pesepay’s card fields, and Mastercard and Zimswitch into the card provider’s own form, both inside your checkout. When the bank asks for 3-D Secure, the customer goes to the bank and comes back to your page.
| Card | Where the customer types it | Element |
|---|---|---|
| Visa | Pesepay’s card fields | card |
| Mastercard and Zimswitch | The card provider’s form | hostedCard |
In the checkout element
Section titled “In the checkout element”There is nothing to code. The customer picks a card method, types the card and presses the element’s Pay button.
- 3-D Secure. If the bank asks for it, the browser leaves for the bank. Mastercard and Zimswitch always go to the bank.
- The return. The customer comes back to the
returnUrlyour server set on the transaction, with?referenceNumber=added. Point it at your checkout page. - The result. Render the page with the order’s reference, and the
element shows the result and sends
finished.
Accept a payment covers reusing the order’s transaction on that return.
With your own method picker
Section titled “With your own method picker”Use the card elements when you build the method picker yourself. Each one takes one kind of card, and you pay from your own button.
The card fields render in a frame on elements.pesepay.com. You pass the
element to confirmCardPayment() and the frame pays. A Mastercard number
returns use_mastercard_option, so you can send the customer to your
Mastercard option.
<form id="card-form" data-reference-number="REF-1"> <div id="card"></div> <button type="submit">Pay</button> <p id="payment-message"></p></form><script type="module" src="/src/card-pay.ts"></script>import { loadPesepay } from "@pesepay/js";
const form = document.querySelector<HTMLFormElement>("#card-form")!;const message = document.querySelector<HTMLElement>("#payment-message")!;// Your server created the transaction and wrote its reference number here.const referenceNumber = form.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; }
// The card fields render in a Pesepay frame: your page never sees the card. const card = pesepay.elements().create("card"); card.on("change", (event) => { message.textContent = event.error?.message ?? ""; }); card.mount("#card");
form.addEventListener("submit", async (event) => { event.preventDefault();
// If the bank asks for 3-D Secure, the browser leaves for it here and // comes back to the transaction's returnUrl. const result = await pesepay.confirmCardPayment(referenceNumber, { element: card }); if (result.error) { // A Mastercard number returns use_mastercard_option: offer your // Mastercard option instead. message.textContent = result.error.message; return; } message.textContent = result.transaction.outcome; });}
void start();import { useState } from "react";import { CardElement, Elements, useElements, usePesepay } from "@pesepay/react";
export function CardForm({ referenceNumber }: { referenceNumber: string }) { return ( <Elements> <PayByCard referenceNumber={referenceNumber} /> </Elements> );}
function PayByCard({ referenceNumber }: { referenceNumber: string }) { const pesepay = usePesepay(); const elements = useElements(); const [message, setMessage] = useState("");
async function pay(): Promise<void> { const card = elements?.getElement("card"); if (!pesepay || !card) return;
// If the bank asks for 3-D Secure, the browser leaves for it here and // comes back to the transaction's returnUrl. const result = await pesepay.confirmCardPayment(referenceNumber, { element: card }); // A Mastercard number returns use_mastercard_option: offer your // Mastercard option instead. setMessage(result.error ? result.error.message : result.transaction.outcome); }
return ( <form onSubmit={(event) => { event.preventDefault(); void pay(); }} > {/* The card fields render in a Pesepay frame: your page never sees the card. */} <CardElement onChange={(event) => setMessage(event.error?.message ?? "")} /> <button type="submit">Pay</button> <p>{message}</p> </form> );}<script setup lang="ts">import { ref } from "vue";import type { Elements as PesepayElements, Pesepay } from "@pesepay/js";import { CardElement, Elements } from "@pesepay/vue";
const props = defineProps<{ referenceNumber: string }>();const message = ref("");
async function pay( pesepay: Pesepay | null, elements: PesepayElements | null,): Promise<void> { const card = elements?.getElement("card"); if (!pesepay || !card) return;
// If the bank asks for 3-D Secure, the browser leaves for it here and // comes back to the transaction's returnUrl. const result = await pesepay.confirmCardPayment(props.referenceNumber, { element: card, }); // A Mastercard number returns use_mastercard_option: offer your Mastercard // option instead. message.value = result.error ? result.error.message : result.transaction.outcome;}</script>
<template> <Elements v-slot="{ pesepay, elements }"> <form @submit.prevent="pay(pesepay, elements)"> <!-- The card fields render in a Pesepay frame: your page never sees the card. --> <CardElement @change="(event) => (message = event.error?.message ?? '')" /> <button type="submit">Pay</button> <p>{{ message }}</p> </form> </Elements></template>import { Component, input, signal } from "@angular/core";import type { Elements as PesepayElements, Pesepay } from "@pesepay/js";import { CardElement, Elements } from "@pesepay/angular";
@Component({ selector: "app-card-pay", imports: [Elements, CardElement], template: ` <pesepay-elements #checkout="pesepayElements"> <form (submit)="pay($event, checkout.instance(), checkout.elements())"> <!-- The card fields render in a Pesepay frame: your page never sees the card. --> <pesepay-card-element (elementChange)="message.set($event.error?.message ?? '')" /> <button type="submit">Pay</button> <p>{{ message() }}</p> </form> </pesepay-elements> `,})export class CardPayComponent { readonly referenceNumber = input.required<string>(); readonly message = signal("");
async pay( event: Event, pesepay: Pesepay | null, elements: PesepayElements | null, ): Promise<void> { event.preventDefault(); const card = elements?.getElement("card"); if (!pesepay || !card) return;
// If the bank asks for 3-D Secure, the browser leaves for it here and // comes back to the transaction's returnUrl. const result = await pesepay.confirmCardPayment(this.referenceNumber(), { element: card, }); // A Mastercard number returns use_mastercard_option: offer your // Mastercard option instead. this.message.set(result.error ? result.error.message : result.transaction.outcome); }}The return from the bank
Section titled “The return from the bank”On the page your returnUrl points at, load Pesepay and call
handleRedirectResult(). It reads the reference from the URL and waits for
the bank’s answer. It finishes Mastercard and Zimswitch payments too, so one
return page serves every card, in any framework.
import { loadPesepay } from "@pesepay/js";
const message = document.querySelector<HTMLElement>("#payment-message")!;
async function finish(): Promise<void> { const pesepay = await loadPesepay(); if (!pesepay) return;
// Reads ?referenceNumber= from the URL and waits for the bank's answer. const result = await pesepay.handleRedirectResult(); if (result.error?.code === "no_redirect_result") { return; // An ordinary page load, not a return from the bank. } message.textContent = result.error ? result.error.message : result.transaction.outcome;}
void finish();Mastercard and Zimswitch
Section titled “Mastercard and Zimswitch”These are paid in the card provider’s own form, which the hostedCard
element shows in your page. startCardCheckout() opens a checkout for the
method: PZW205 for Mastercard, PZW215 or PZW213 for Zimswitch. Create
the element from it and pay from your own button.
Start one checkout per payment. Each call makes a new one and only the newest
is tracked, so the examples keep it in sessionStorage for a reload. If the
form refuses the card, confirmHostedCardPayment() returns
incomplete_details and the form shows the customer what to fix.
<form id="card-form" data-reference-number="REF-1"> <div id="card"></div> <button type="submit">Pay</button> <p id="payment-message"></p></form><script type="module" src="/src/hosted-card-pay.ts"></script>import { loadPesepay, type CardCheckout, type Pesepay } from "@pesepay/js";
const form = document.querySelector<HTMLFormElement>("#card-form")!;const message = document.querySelector<HTMLElement>("#payment-message")!;// Your server created the transaction and wrote its reference number here.const referenceNumber = form.dataset.referenceNumber!;// Mastercard. Zimswitch is PZW215 or PZW213.const paymentMethodCode = "PZW205";
// One checkout per payment: each start makes a new one and only the newest// is tracked, so a reload reuses the checkout it already has.async function cardCheckoutFor(pesepay: Pesepay): Promise<CardCheckout | string> { const key = `pesepay-card-checkout:${referenceNumber}`; const kept = sessionStorage.getItem(key); if (kept) return JSON.parse(kept) as CardCheckout;
const result = await pesepay.startCardCheckout(referenceNumber, paymentMethodCode); if (result.error) return result.error.message; const next = result.transaction.nextAction; if (next?.type !== "card_checkout") return "This card can't be paid here."; sessionStorage.setItem(key, JSON.stringify(next.cardCheckout)); return next.cardCheckout;}
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 cardCheckout = await cardCheckoutFor(pesepay); if (typeof cardCheckout === "string") { message.textContent = cardCheckout; return; }
// The card provider's own form, shown in your page. const hostedCard = pesepay.elements().create("hostedCard", { cardCheckout }); hostedCard.mount("#card");
form.addEventListener("submit", async (event) => { event.preventDefault();
// The form checks the card, then the browser leaves for the bank and // comes back to the transaction's returnUrl. const result = await pesepay.confirmHostedCardPayment(referenceNumber, { element: hostedCard, }); if (result.error) message.textContent = result.error.message; });}
void start();import { useEffect, useState } from "react";import type { CardCheckout, Pesepay } from "@pesepay/js";import { Elements, HostedCardElement, useElements, usePesepay } from "@pesepay/react";
// Mastercard. Zimswitch is PZW215 or PZW213.const paymentMethodCode = "PZW205";
export function HostedCardForm({ referenceNumber }: { referenceNumber: string }) { return ( <Elements> <PayByHostedCard referenceNumber={referenceNumber} /> </Elements> );}
// One checkout per payment: each start makes a new one and only the newest// is tracked, so a reload reuses the checkout it already has.async function cardCheckoutFor( pesepay: Pesepay, referenceNumber: string,): Promise<CardCheckout | string> { const key = `pesepay-card-checkout:${referenceNumber}`; const kept = sessionStorage.getItem(key); if (kept) return JSON.parse(kept) as CardCheckout;
const result = await pesepay.startCardCheckout(referenceNumber, paymentMethodCode); if (result.error) return result.error.message; const next = result.transaction.nextAction; if (next?.type !== "card_checkout") return "This card can't be paid here."; sessionStorage.setItem(key, JSON.stringify(next.cardCheckout)); return next.cardCheckout;}
function PayByHostedCard({ referenceNumber }: { referenceNumber: string }) { const pesepay = usePesepay(); const elements = useElements(); const [cardCheckout, setCardCheckout] = useState<CardCheckout | null>(null); const [message, setMessage] = useState("");
useEffect(() => { if (!pesepay) return; void cardCheckoutFor(pesepay, referenceNumber).then((found) => { if (typeof found === "string") setMessage(found); else setCardCheckout(found); }); }, [pesepay, referenceNumber]);
async function pay(): Promise<void> { const hostedCard = elements?.getElement("hostedCard"); if (!pesepay || !hostedCard) return;
// The form checks the card, then the browser leaves for the bank and // comes back to the transaction's returnUrl. const result = await pesepay.confirmHostedCardPayment(referenceNumber, { element: hostedCard, }); if (result.error) setMessage(result.error.message); }
return ( <form onSubmit={(event) => { event.preventDefault(); void pay(); }} > {/* The card provider's own form, shown in your page. */} {cardCheckout && <HostedCardElement options={{ cardCheckout }} />} <button type="submit" disabled={!cardCheckout}> Pay </button> <p>{message}</p> </form> );}<script setup lang="ts">import { ref, shallowRef } from "vue";import { loadPesepay, type CardCheckout, type Elements as PesepayElements, type Pesepay,} from "@pesepay/js";import { Elements, HostedCardElement } from "@pesepay/vue";
const props = defineProps<{ referenceNumber: string }>();// Mastercard. Zimswitch is PZW215 or PZW213.const paymentMethodCode = "PZW205";
const message = ref("");const cardCheckout = shallowRef<CardCheckout | null>(null);
// One checkout per payment: each start makes a new one and only the newest// is tracked, so a reload reuses the checkout it already has.async function cardCheckoutFor(pesepay: Pesepay): Promise<CardCheckout | string> { const key = `pesepay-card-checkout:${props.referenceNumber}`; const kept = sessionStorage.getItem(key); if (kept) return JSON.parse(kept) as CardCheckout;
const result = await pesepay.startCardCheckout( props.referenceNumber, paymentMethodCode, ); if (result.error) return result.error.message; const next = result.transaction.nextAction; if (next?.type !== "card_checkout") return "This card can't be paid here."; sessionStorage.setItem(key, JSON.stringify(next.cardCheckout)); return next.cardCheckout;}
// Loaded once, and shared with <Elements>.const loading = loadPesepay();void loading.then(async (pesepay) => { if (!pesepay) return; // On the server, or the runtime could not load. const found = await cardCheckoutFor(pesepay); if (typeof found === "string") message.value = found; else cardCheckout.value = found;});
async function pay( pesepay: Pesepay | null, elements: PesepayElements | null,): Promise<void> { const hostedCard = elements?.getElement("hostedCard"); if (!pesepay || !hostedCard) return;
// The form checks the card, then the browser leaves for the bank and // comes back to the transaction's returnUrl. const result = await pesepay.confirmHostedCardPayment(props.referenceNumber, { element: hostedCard, }); if (result.error) message.value = result.error.message;}</script>
<template> <Elements :pesepay="loading" v-slot="{ pesepay, elements }"> <form @submit.prevent="pay(pesepay, elements)"> <!-- The card provider's own form, shown in your page. --> <HostedCardElement v-if="cardCheckout" :options="{ cardCheckout }" /> <button type="submit" :disabled="!cardCheckout">Pay</button> <p>{{ message }}</p> </form> </Elements></template>import { Component, input, signal, type OnInit } from "@angular/core";import { loadPesepay, type CardCheckout, type Elements as PesepayElements, type Pesepay,} from "@pesepay/js";import { Elements, HostedCardElement } from "@pesepay/angular";
// Mastercard. Zimswitch is PZW215 or PZW213.const paymentMethodCode = "PZW205";
@Component({ selector: "app-hosted-card-pay", imports: [Elements, HostedCardElement], template: ` <pesepay-elements [pesepay]="loading" #checkout="pesepayElements"> <form (submit)="pay($event, checkout.instance(), checkout.elements())"> <!-- The card provider's own form, shown in your page. --> @if (cardCheckout(); as cardCheckout) { <pesepay-hosted-card-element [options]="{ cardCheckout }" /> } <button type="submit" [disabled]="!cardCheckout()">Pay</button> <p>{{ message() }}</p> </form> </pesepay-elements> `,})export class HostedCardPayComponent implements OnInit { readonly referenceNumber = input.required<string>(); readonly message = signal(""); readonly cardCheckout = signal<CardCheckout | null>(null); // Loaded once, and shared with <pesepay-elements>. protected readonly loading = loadPesepay();
ngOnInit(): void { void this.loading.then(async (pesepay) => { if (!pesepay) return; // On the server, or the runtime could not load. const found = await this.cardCheckoutFor(pesepay); if (typeof found === "string") this.message.set(found); else this.cardCheckout.set(found); }); }
// One checkout per payment: each start makes a new one and only the newest // is tracked, so a reload reuses the checkout it already has. private async cardCheckoutFor(pesepay: Pesepay): Promise<CardCheckout | string> { const key = `pesepay-card-checkout:${this.referenceNumber()}`; const kept = sessionStorage.getItem(key); if (kept) return JSON.parse(kept) as CardCheckout;
const result = await pesepay.startCardCheckout( this.referenceNumber(), paymentMethodCode, ); if (result.error) return result.error.message; const next = result.transaction.nextAction; if (next?.type !== "card_checkout") return "This card can't be paid here."; sessionStorage.setItem(key, JSON.stringify(next.cardCheckout)); return next.cardCheckout; }
async pay( event: Event, pesepay: Pesepay | null, elements: PesepayElements | null, ): Promise<void> { event.preventDefault(); const hostedCard = elements?.getElement("hostedCard"); if (!pesepay || !hostedCard) return;
// The form checks the card, then the browser leaves for the bank and // comes back to the transaction's returnUrl. const result = await pesepay.confirmHostedCardPayment(this.referenceNumber(), { element: hostedCard, }); if (result.error) this.message.set(result.error.message); }}The provider’s form needs the widest Content-Security-Policy of any method; see Accept a payment.
What’s next
Section titled “What’s next”- Accept a payment: every outcome, and fulfilling from your server