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.
Why move
Section titled “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”- 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
transactionStatusisSUCCESS.
What changes
Section titled “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”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 approvespesepay.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 pagepayment = 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 approvespesepay.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$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$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 pagePayment payment = pesepay.createPayment("USD", "PZW211", email);Map<String, String> requiredFields = new HashMap<>();requiredFields.put("customerPhoneNumber", phone);
Response response = pesepay.makeSeamlessPayment(payment, "Order #1042", 10.0, requiredFields);// then poll response.getPollUrl() while the customer approvespesepay.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 pageThe 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.
On your page
Section titled “On your page”Your method picker, phone-number field and waiting screen are replaced by the checkout element:
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.
Where each field goes
Section titled “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”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.