Failed transactions and reporting issues
See why transactions fail and report suspected system issues to Deripay.
Most failed transactions are not system faults. A customer cancels the M-Pesa prompt, doesn't enter their PIN in time, or doesn't have enough balance. In each of these cases no money moves and the customer can try again. The partner portal shows the cause of every failed transaction, so you can tell these apart from the few failures that need Deripay.
Where to see failure causes
- Transactions: each failed transaction shows its cause under the status. Failures that may be a Deripay issue carry a red badge.
- Transaction page: the cause, what happened, and who can resolve it.
- Overview and Analytics: Why transactions failed splits the period's failed transactions into customer side, payment provider and possible Deripay issue, with each cause's count and share.
Each cause has one of three sources:
| Source | Meaning |
|---|---|
| Customer side | The customer's action, phone, balance or account stopped the payment. Deripay worked correctly. |
| Payment provider | M-Pesa or Deriv declined or could not complete the request. |
| Possible Deripay issue | The failure happened inside Deripay or its provider integration. Report it. |
Causes
| Cause | Source | What happened and what to do |
|---|---|---|
| Cancelled by customer | Customer side | The customer cancelled or declined the payment prompt. No money moved. |
| No response from customer | Customer side | The prompt reached the phone but the PIN wasn't entered in time. The customer can try again. |
| Phone unreachable | Customer side | The phone was off, out of coverage or the SIM was inactive. Retry once the phone is reachable. |
| Incorrect or unregistered number | Customer side | The number isn't registered for mobile money or was entered incorrectly. Ask the customer to check it. |
| Insufficient balance | Customer side | The M-Pesa or Deriv balance was too low for the amount. |
| Wrong PIN | Customer side | The customer entered an incorrect PIN on the prompt. |
| Another payment in progress | Customer side | Another mobile money session was open on the phone. Retry once it closes. |
| Verification code not accepted | Customer side | The withdrawal code was wrong, expired or badly formatted. No funds left the Deriv account. |
| Customer account limit | Customer side | A Deriv account limit or restriction stopped the withdrawal, such as a daily limit, disabled withdrawals or an unsupported country. |
| Mobile money account restricted | Customer side | Safaricom declined the payment because of a limit or restriction on the customer's M-Pesa account. |
| Checkout expired | Customer side | The customer didn't pay before the crypto checkout expired. |
| Not completed by customer | Customer side | The customer never finished the request, for example the withdrawal code was never entered. It shows as Expired and no money moved. |
| Declined by Deriv | Payment provider | Deriv declined the withdrawal, so no funds left the Deriv account. Deriv doesn't give a reason; Deripay is reviewing these declines with Deriv. |
| Mobile money provider error | Payment provider | The mobile money provider had a temporary error. No money moved; the customer can try again. Report it if many customers are affected. |
| Never confirmed by M-Pesa | Payment provider | M-Pesa never confirmed the payment, usually because the customer didn't respond. No payment was recorded. |
| Paid but not credited | Possible Deripay issue | The customer paid but the Deriv account wasn't credited. Deripay reviews these; report it so we can prioritise the customer. |
| Possible Deripay issue | Possible Deripay issue | The failure happened inside Deripay or a provider integration, not because of the customer. |
| Unexplained failure | Possible Deripay issue | Deripay couldn't match the failure to a known cause. |
Not completed requests still count as pending in analytics, statistics and CSV exports.
Report an issue
Report failures flagged as a possible Deripay issue, and anything unusual you notice, such as a sudden rise in one cause. You don't need to wait for a customer to contact you.
- Select Report an issue on the overview, the analytics page, a transaction page or Help and support. Flagged failures have their own report button, with the transactions already attached.
- Choose what the issue is about and describe what happened, for example what the customer saw, when it started and how many customers are affected.
- Add up to 20 transaction IDs from the workspace. Deripay attaches each transaction's status, amount and failure cause.
The report goes straight to the Deripay support team at support@deripay.app. Track it under Help and support, where we post the outcome when we resolve it. We also email the outcome to whoever sent the report; reply to that email if the problem is still there. A transaction you already reported shows the report's status on its page. Each workspace can send up to 20 reports per hour.
In the API
Failure causes are shown in the partner portal. API responses keep their documented failure object, and GET /api/deriv/statistics and its CSV export don't include causes. See transaction status and errors for handling failures in your integration.
Contact support
For anything else, such as account, integration or settlement questions, email support@deripay.app or open Help and support in the partner portal. Include your workspace name and any transaction IDs.