Skip to content

Migrate from the Direct API

This page is for a merchant who already runs the 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.

  • 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.
  • 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 is SUCCESS.

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.

Before: Direct API
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
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

The new call is the one Hosted checkout uses (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.

Your method picker, phone-number field and waiting screen are replaced by the checkout element:

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

The quickstart has the same code for a script tag, React, Vue and Angular. Want your own Pay button? See Custom payment flow.

Direct API (make-payment)Embedded checkout
amountDetails, reasonForPayment, resultUrl, merchantReference, paymentMetadataThe server’s create call, unchanged
returnUrlThe server’s create call, where it is required. Set it to your checkout page
paymentMethodCodeThe 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
customerNot sent by the checkout element. With your own Pay button, pass it to confirmPayment() as customer
The encrypted make-payment callGone: the customer confirms in the element
Polling pollUrlThe element waits for the outcome. Your server still confirms through the result callback and a status check

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.