Errors and fallbacks
Anything a customer, a card or a network causes is returned, never
thrown. Every confirm and wait resolves to { transaction } or { error },
and the error’s code comes from a closed list. Only programmer errors
throw: a selector that matches nothing, an element used after destroy(), a
missing argument. So a try/catch around a confirm catches your bugs, not
declines.
The checkout element handles all of this itself and sends one finished
event: see Answer every outcome.
This page is for the Custom payment flow
and your own method picker, where
your code reads each result.
Branch on the outcome
Section titled “Branch on the outcome”transaction.outcome says what a result means for your checkout. Branch on
it, not on status, which is Pesepay’s own vocabulary. This function is
built and type-checked against the published packages:
import type { ConfirmResult } from "@pesepay/js";
const CHECKING = "We're checking your payment. Please don't pay again.";
// What to tell the customer after any confirm or wait. Fulfil the order on// your server, never on this.export function describeResult(result: ConfirmResult): string { // The payment was sent, but its answer was lost: the customer may have paid. if (result.error?.code === "outcome_unknown") return CHECKING; if (result.error) return result.error.message;
switch (result.transaction.outcome) { case "succeeded": return "Paid. Thank you!"; case "failed": return result.transaction.message ?? "The payment didn't go through."; case "processing": case "unknown": return CHECKING; case "reversed": return "The payment was reversed, and the money returned."; }}“Checking”, not “failed”
Section titled ““Checking”, not “failed””Two results mean the customer may have paid:
outcome: "unknown": Pesepay has no final answer from the provider.error.code === "outcome_unknown": the payment request was sent, but its answer was lost to a timeout, a dropped connection or a server error.
Show “checking” for both, and don’t let the customer pay again. Wait for your result callback, or check the transaction from your server first. Never call the confirm again for that payment: it may start a second one.
A timeout error from a read or a wait means the same: the transaction may
still complete.
Showing an error
Section titled “Showing an error”error.message is readable text you can show. error.type says how to
react:
| Type | What happened | What to do |
|---|---|---|
validation_error | Checked in the browser; nothing was sent | Show the message; the customer can fix it |
card_error | The issuer or processor refused | Show the message; offer another card or method |
invalid_request_error | Your integration is wrong | Fix the code; show a generic message |
authentication_error | The transaction credential was rejected | Fix the server setup |
api_error | Pesepay failed | Retry a read; never retry a confirm blindly |
network_error | No response arrived | Retry a read; see outcome_unknown above |
rate_limit_error | Too many requests | Slow down |
Pesepay sends no 429 today, so rate_limit_error doesn’t occur yet. Handle
it anyway: it keeps your code correct if limits are added.
Branch on error.code, never on the message. These codes ask for something
specific:
| Code | What to do |
|---|---|
use_mastercard_option | A Mastercard number in the Visa card fields. Offer your Mastercard option. |
card_brand_not_supported | Amex, JCB or another brand. Ask for another card. |
wrong_network_phone | A number EcoCash doesn’t serve, such as NetOne. Ask for an EcoCash number. |
incomplete_otp / invalid_otp | O’mari’s code is missing digits or isn’t six digits. The customer retypes it. |
scan_code_unavailable | No code came back to scan. Create a new transaction. |
no_redirect_result | handleRedirectResult() on an ordinary page load. Not a failure. |
frame_load_error / frame_timeout | The card fields didn’t load. Usually a missing frame-src in your CSP. |
The full list is PESEPAY_ERROR_CODES, exported for an exhaustive switch.
To narrow a caught value, use isPesepayError(value) rather than
instanceof: the loader and the runtime are bundled separately.
When the elements can’t load
Section titled “When the elements can’t load”- The runtime didn’t load, for example behind a content blocker.
loadPesepay()resolvesnull. Show a message, or send the customer to the transaction’s Hosted checkout page: keep theredirectUrlyour server got when it created the transaction. - The payment element couldn’t list the methods, or a method’s fields
failed. It sends
loaderrorwithfallbackUrl, Pesepay’s Hosted checkout page for the same transaction. Send the customer there, as the Custom payment flow does. - A single-method element couldn’t load, such as the card fields
(
frame_load_error). Itsloaderrorhas nofallbackUrl. Offer another method, and check your page’s Content-Security-Policy.
With your own picker, listPaymentMethods() returns { error } when the
methods can’t be listed; show the message, or send the customer to the Hosted
checkout page at the transaction’s redirectUrl, as when the runtime doesn’t load.
What’s next
Section titled “What’s next”- Accept a payment: fulfilling from your server