How do I simulate errors and edge cases?
Test declines, authentication challenges, async mobile money, and webhook failures before go-live.
Use this index to exercise failure paths in sandbox. Full test card numbers and MoMo behavior live in Sandbox payments-this page routes you to the right scenario.
Run these scenarios only with test API keys (lomi_sk_test_...). Never use test card numbers in live mode.
Scenario matrix
| Scenario | How to trigger | Expected outcome | Learn more |
|---|---|---|---|
| Card approved | 4242 4242 4242 4242 on hosted checkout | completed, test balance credit | Sandbox payments: cards |
| Card declined | Decline test PANs in sandbox table | failed | Same section |
| 3D Secure / authentication | Auth-required test cards | requires_action or challenge UI | Sandbox payments |
| Wave (test) | Select Wave on sandbox checkout | Often immediate completed | Wave |
| MTN MoMo (test) | POST /charge/mtn with test MSISDN | Immediate completed on test key | MTN MoMo |
Direct MoMo pending (test) | X-Scenario-Key: pending on POST /charge/mtn or /charge/wave | Charge stays PENDING; no auto-complete | Sandbox payments: scenarios |
Direct MoMo failed (test) | X-Scenario-Key: failed on POST /charge/mtn or /charge/wave | 400 error response | Same section |
| MTN MoMo (live) | Real MSISDN, live key | Starts PENDING | Verify payments |
| Pending expiration | Wait beyond session/transaction TTL | expired or failed | Payment state machine |
| Webhook signature failure | POST without valid X-Lomi-Signature | Your endpoint returns 4xx; lomi. retries | Handling webhooks |
| Duplicate webhook | Replay same event id | Your handler dedupes; no double fulfill | Webhook reliability |
| Insufficient balance payout | Test payout rules in sandbox | 400 or failed payout | Payouts in test mode |
| Invalid API key | Omit or wrong X-API-Key | 401 | Authentication |
| Rate limit | Burst requests in test | 429 | Error handling |
Direct charge scenarios (test key only)
On POST /charge/mtn and POST /charge/wave, send X-Scenario-Key to override default test behavior. This applies to direct charges only-hosted checkout and card charges do not read this header yet.
| Header value | Behavior |
|---|---|
| (omit) | Default: test charge auto-completes and credits test balance |
pending | Charge remains PENDING; no auto-complete (poll or webhook) |
failed | Request fails with 400 |
# Keep charge pending (CI / dunning tests)
curl -sS -X POST "https://sandbox.api.lomi.africa/charge/mtn" \
-H "X-API-KEY: $LOMI_TEST_KEY" \
-H "X-Scenario-Key: pending" \
-H "Content-Type: application/json" \
-d '{"amount":1000,"currency":"XOF","customer_phone":"+2250700000000"}'
# Simulate provider failure
curl -sS -X POST "https://sandbox.api.lomi.africa/charge/wave" \
-H "X-API-KEY: $LOMI_TEST_KEY" \
-H "X-Scenario-Key: failed" \
-H "Content-Type: application/json" \
-d '{"amount":1000,"currency":"XOF","customer_phone":"+2250700000000"}'Automation
For CI and integration tests, see Testing guide and use sandbox curl recipes in Sandbox payments.