Pesapal (API 3.0) · Error reference

Pesapal API 3.0 Errors and Payment Statuses Explained

Pesapal API 3.0 reports a payment as one of four statuses (COMPLETED, FAILED, REVERSED or INVALID) from GetTransactionStatus, and reports rejected requests with an error object of type, code and message.

Have a response you don't understand? Paste it into the Payment Error Code Lookup and it finds every known code inside.

How Pesapal reports errors

• Rejected requests come back as JSON with an error object: {"type": "...", "code": "...", "message": "..."}. Pesapal's docs don't publish a list of the codes, so log the whole object.
• The payment outcome comes only from GET /api/Transactions/GetTransactionStatus: payment_status_description and status_code (0 INVALID, 1 COMPLETED, 2 FAILED, 3 REVERSED).
• The callback redirect (OrderNotificationType CALLBACKURL) and the IPN (IPNCHANGE) never carry the status. They only tell you which order to look up.

How sure is this?

Each code below is labelled by how well it is documented. All 10 codes on this page come from Pesapal's own documentation, linked under each one. Log the full response anyway: messages change.

Payment outcomes

The status values that tell you whether the customer paid.

Failure reasons

Why a payment did not go through.

Request errors

Returned straight away when the API rejects your request.

Handle every code in your code

Map each outcome code to one of four actions. Unknown codes fall back to "check the status", so a new or misspelled code never fulfils or cancels an order by accident.

// What to do with each Pesapal (API 3.0) outcome code.
// Unknown codes fall back to "check_status": never fulfil or fail an order on a code you don't recognise.
const ACTIONS = {
  "COMPLETED": "fulfil", // Paid (status_code 1)
  "FAILED": "mark_failed", // Payment failed (status_code 2)
  "INVALID": "wait", // Not paid (status_code 0)
  "REVERSED": "mark_failed", // Payment reversed (status_code 3)
  "IPNCHANGE": "check_status", // IPN: a status changed
  "CALLBACKURL": "check_status", // Customer redirected back
};

export function pesapalNextStep(code) {
  const key = String(code ?? "").trim().toUpperCase().replace(/[\s-]+/g, "_");
  return ACTIONS[key] ?? "check_status";
}

// Example:
// switch (pesapalNextStep(status.payment_status_description)) {
//   case "fulfil":       // verify amount, then mark the order paid (idempotently)
//   case "mark_failed":  // mark unpaid, show a retry button
//   case "wait":         // do nothing yet; a callback or your poller will follow
//   case "check_status": // ask the status endpoint before deciding
// }

Frequently asked questions

What does Pesapal status INVALID mean?

INVALID (Not paid (status_code 0)): status_code 0. Pesapal's docs list INVALID as one of the four statuses without defining it. It is not COMPLETED, so the order is not paid. Don't fulfil. Check again after the IPN or from a scheduled job, and expire the order if it never completes.

What does Pesapal status IPNCHANGE mean?

IPNCHANGE (IPN: a status changed): OrderNotificationType on an IPN call. Pesapal calls your registered IPN URL (GET or POST, as you registered it) with OrderTrackingId and OrderMerchantReference when a payment status changes. It does not include the status. Call GetTransactionStatus with the OrderTrackingId and settle from that. Never mark an order paid from the IPN itself.

What does Pesapal status REVERSED mean?

REVERSED (Payment reversed (status_code 3)): status_code 3: a payment was reversed. If you had marked the order paid, mark it reversed and stop or recover the goods or service. Look at the payment in your Pesapal dashboard.

What does Pesapal error error object mean?

error object (Request rejected (type, code, message)): When a call fails, Pesapal answers with a JSON error object of type, code and message. The docs don't list the codes. Log the whole object. Check the token (it lasts at most 5 minutes), the notification_id (register the IPN in the same environment), and that your order id uses only letters, numbers and - _ . : (max 50).

What does Pesapal error RefundRequest 500 mean?

RefundRequest 500 (Refund rejected): RefundRequest answered 500: the refund was rejected. The message says why. Only COMPLETED payments can be refunded, once, in the same currency, up to the amount paid. Mobile money payments can only be refunded in full; cards in full or in part. Use the confirmation_code from GetTransactionStatus.

Integration guides

Full Pesapal integrations that handle these codes: Pesapal API 3.0 in Node.js, Laravel, Django, Next.js, Pesapal Request Builder.

Checked November 2026. Error codes change. If you see one that's missing or wrong, please let me know.