Skip to content

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.

CardWhere the customer types itElement
VisaPesepay’s card fieldscard
Mastercard and ZimswitchThe card provider’s formhostedCard

There is nothing to code. The customer picks a card method, types the card and presses the element’s Pay button.

  1. 3-D Secure. If the bank asks for it, the browser leaves for the bank. Mastercard and Zimswitch always go to the bank.
  2. The return. The customer comes back to the returnUrl your server set on the transaction, with ?referenceNumber= added. Point it at your checkout page.
  3. 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.

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.

checkout.html
<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>
src/card-pay.ts
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();

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.

return page
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();

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.

checkout.html
<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>
src/hosted-card-pay.ts
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();

The provider’s form needs the widest Content-Security-Policy of any method; see Accept a payment.