Skip to content

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.

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:

show-result.ts
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.";
}
}

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.

error.message is readable text you can show. error.type says how to react:

TypeWhat happenedWhat to do
validation_errorChecked in the browser; nothing was sentShow the message; the customer can fix it
card_errorThe issuer or processor refusedShow the message; offer another card or method
invalid_request_errorYour integration is wrongFix the code; show a generic message
authentication_errorThe transaction credential was rejectedFix the server setup
api_errorPesepay failedRetry a read; never retry a confirm blindly
network_errorNo response arrivedRetry a read; see outcome_unknown above
rate_limit_errorToo many requestsSlow 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:

CodeWhat to do
use_mastercard_optionA Mastercard number in the Visa card fields. Offer your Mastercard option.
card_brand_not_supportedAmex, JCB or another brand. Ask for another card.
wrong_network_phoneA number EcoCash doesn’t serve, such as NetOne. Ask for an EcoCash number.
incomplete_otp / invalid_otpO’mari’s code is missing digits or isn’t six digits. The customer retypes it.
scan_code_unavailableNo code came back to scan. Create a new transaction.
no_redirect_resulthandleRedirectResult() on an ordinary page load. Not a failure.
frame_load_error / frame_timeoutThe 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.

  1. The runtime didn’t load, for example behind a content blocker. loadPesepay() resolves null. Show a message, or send the customer to the transaction’s Hosted checkout page: keep the redirectUrl your server got when it created the transaction.
  2. The payment element couldn’t list the methods, or a method’s fields failed. It sends loaderror with fallbackUrl, Pesepay’s Hosted checkout page for the same transaction. Send the customer there, as the Custom payment flow does.
  3. A single-method element couldn’t load, such as the card fields (frame_load_error). Its loaderror has no fallbackUrl. 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.