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.
One transaction per order
Section titled “One transaction per order”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
returnUrlwith?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.
Answer every outcome
Section titled “Answer every outcome”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.
| Outcome | What your page does |
|---|---|
succeeded | Move the customer on, for example to an order page that says the payment is being confirmed. Fulfil from your server (below). |
failed | Offer 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. |
reversed | The money went back to the customer. Treat the order as unpaid, as for failed. |
unknown | No 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. |
Fulfil from your server
Section titled “Fulfil from your server”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.
- Verify the callback is from Pesepay.
- Check the payment status once for its
referenceNumber, and fulfil only onSUCCESS. - 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.
When Elements can’t load
Section titled “When Elements can’t load”Two things can stop the checkout element, and both have a way out:
loadPesepay()resolvesnull: 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 theredirectUrlyour server got when it created the transaction.- The element sends
loaderror: the methods couldn’t load. When the event carries afallbackUrl, send the customer there and Pesepay’s Hosted checkout page takes the payment. The Quickstart’s code already does this.
Content-Security-Policy
Section titled “Content-Security-Policy”If your checkout page sends a Content-Security-Policy header, add the
sources for each method you take:
| Method | Add |
|---|---|
| Every method | script-src https://js.pesepay.com and connect-src https://api.pesepay.com |
| Visa | frame-src https://elements.pesepay.com |
| EcoCash and O’mari | Nothing more |
| InnBucks | img-src data:, for the QR code |
| PayGo | img-src https://api.paygo.co.zw, for the QR code |
| Mastercard and Zimswitch | https://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 element | img-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.comMastercard 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'.
Before you go live
Section titled “Before you go live”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.
What’s next
Section titled “What’s next”- Cards and 3-D Secure, Mobile money approval and Scan to pay: what each method asks of the customer