Skip to content

Accept a payment

The Quickstart takes one payment. This page covers what a live checkout needs on top of it: one transaction per order, an answer for every outcome, fulfilment from your server, a fallback when Elements can’t load, and your Content-Security-Policy. The page code stays the Quickstart’s.

Create the transaction when the customer reaches your checkout page, and store its referenceNumber with the order. Every later visit to that page renders the stored reference, not a new one:

  • A reload shows the same transaction. If it is already paid, or still being paid, the checkout element shows its result or waits for it instead of offering the methods again.
  • A return from the bank (Visa with 3-D Secure, Mastercard, Zimswitch) comes back to your returnUrl with ?referenceNumber= added. Render the order’s stored reference and the element shows the result.

A new transaction for every page load would leave the order with several, and a customer who reloads after paying could be offered the methods again.

The checkout element sends finished once, with an outcome. It has already shown the customer the result, so your page only decides what happens next.

OutcomeWhat your page does
succeededMove the customer on, for example to an order page that says the payment is being confirmed. Fulfil from your server (below).
failedOffer to try again. A failed transaction can’t be paid again, so create a new one for the order and render the element with its reference: a new reference replaces the element.
reversedThe money went back to the customer. Treat the order as unpaid, as for failed.
unknownNo answer came in time, and the customer may still pay. Don’t offer to pay again. Tell them you will confirm by email, and wait for your result callback.

Never fulfil on what the browser reports: a page can be edited, and finished only says what the element saw. Pesepay posts the final status to your resultUrl.

  1. Verify the callback is from Pesepay.
  2. Check the payment status once for its referenceNumber, and fulfil only on SUCCESS.
  3. Fulfil each order once. Failed deliveries are never retried, so a reconciliation job checks orders whose callback never came, and it can see the same payment as your handler. Record the reference you fulfilled and ignore repeats.

Two things can stop the checkout element, and both have a way out:

  • loadPesepay() resolves null: the runtime didn’t load, for example behind a content blocker. The Quickstart shows a message. You can also send the customer to the transaction’s Hosted checkout page: keep the redirectUrl your server got when it created the transaction.
  • The element sends loaderror: the methods couldn’t load. When the event carries a fallbackUrl, send the customer there and Pesepay’s Hosted checkout page takes the payment. The Quickstart’s code already does this.

If your checkout page sends a Content-Security-Policy header, add the sources for each method you take:

MethodAdd
Every methodscript-src https://js.pesepay.com and connect-src https://api.pesepay.com
Visaframe-src https://elements.pesepay.com
EcoCash and O’mariNothing more
InnBucksimg-src data:, for the QR code
PayGoimg-src https://api.paygo.co.zw, for the QR code
Mastercard and Zimswitchhttps://eu-prod.oppwa.com in script-src, style-src, img-src, connect-src and form-action, and frame-src https: for 3-D Secure
The checkout elementimg-src https://elements.pesepay.com, for the method logos, plus the sources for each method it offers

A page taking every method can start from this, joined into one header line:

script-src 'self' https://js.pesepay.com https://eu-prod.oppwa.com;
style-src 'self' https://eu-prod.oppwa.com;
img-src 'self' data: https://elements.pesepay.com https://api.paygo.co.zw https://eu-prod.oppwa.com;
connect-src 'self' https://api.pesepay.com https://eu-prod.oppwa.com;
frame-src https:;
form-action 'self' https://eu-prod.oppwa.com

Mastercard and Zimswitch need the widest policy, because their 3-D Secure step runs in a frame from the customer’s bank, which can be any host. Keep your scripts in their own files, as the Quickstart does, so you don’t need 'unsafe-inline'.

Pay a small live amount with each method you will offer, on your production keys: the sandbox simulates outcomes and runs neither 3-D Secure nor the card providers’ forms. Then work through the go-live checklist.