> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudpay.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment failures

> Why an accepted payment ends failed or in review.

A payment can be accepted with `202` and still fail later at the provider. When that happens, `status` becomes `failed` and `failure_reason` explains why. Any money that was held is released straight away.

```json theme={null}
{
  "id": "0b6c1c0e-…",
  "status": "failed",
  "failure_reason": "Request cancelled by user",
  "amount": 150000
}
```

`failure_reason` is the provider's own explanation, passed through, so **show it to your staff, but don't branch on its exact wording**. The usual causes:

| Kind of reason | What happened | What to do |
| - | - | - |
| Cancelled by the user | The customer dismissed the prompt | Ask them to try again; use a new idempotency key |
| Timeout, or no response from the user | The prompt expired after about a minute, or the phone was off or out of signal | Try again when the customer is ready |
| Insufficient balance | The customer's M-Pesa balance was too low | Ask them to top up, or pay less |
| Wrong PIN | The customer entered a wrong M-Pesa PIN too many times | Try again later |
| Invalid account or recipient | The bank account, till or paybill doesn't exist | Correct the payee |
| `live_credentials_outside_production` | Live provider keys were used outside production | Use the provider's sandbox keys in development |
| `sandbox_credentials_in_production` | Sandbox provider keys were used in production | Use your live provider keys |

The last two come from Cloudpay itself, not the provider. They're refused on purpose, so that a test setup can never move real money and a live setup can never use test keys.

## Review

When Cloudpay can't be sure of the outcome, a payment moves to `review` instead of guessing. Examples:

* The provider confirmed a different amount from the one requested.
* A receipt was already used to settle another payout.
* The provider didn't answer clearly.

The money stays held while Cloudpay operations check the payment with the provider. The payment then ends `completed` or `failed`. **Don't retry a payment in review.** If you do, you may pay twice.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.