Test your integration
Verify authentication, retries, payment outcomes, and webhook handling before live use.
Prepare a test environment
Confirm the API base URL, environment, credentials, and permitted phone numbers with your DeriPay administrator. These docs do not provision a hosted sandbox or provide universal M-Pesa test numbers. Never assume the sample phone number selects a success scenario.
The local preview simulates provider responses and uses a test database. It does not send real STK prompts, payouts, or external webhooks. Tests there verify your request handling, not live provider connectivity. See environments.
API checks
| Check | Expected result |
|---|---|
| Balance request with a valid scoped key | 200 and the balance envelope |
| Request without a key | 401 |
| Request with a key missing the endpoint scope | 403 |
| Collection with a fractional-shilling amount | 400 |
| First valid payment request | 202, payment ID, replayed: false |
| Same body and idempotency key again | 200, same ID, replayed: true |
| Same key with changed amount | 409 |
| Retrieve a collection through the payout endpoint | 404 |
| Retrieve a different test merchant's payment | 404 |
| Payout without enough payout availability | 409 |
Run negative cases in an isolated test environment. Keep the original key when simulating transport timeouts. Verify the application stores the ID and does not fulfil orders at queued or submitted.
Webhook receiver checks
Test the verification helper independently with a test signing secret and exact raw bytes:
- A valid signature and current timestamp pass.
- Changing one body byte or the timestamp without re-signing fails.
- A malformed signature, wrong secret, or stale timestamp fails.
- Repeating a valid signed event produces only one business action.
- A header event ID differing from the signed body ID is rejected.
- A temporary storage failure produces a non-
2xxresponse so delivery can retry. - Rotation accepts queued events signed with the previous secret while accepting new events with the replacement.
Receiver unit tests do not prove network delivery. Use a configured hosted test deployment to check HTTPS reachability, successful delivery history, and retry behavior. The portal currently has no send-test-event button or merchant replay control.
Before live use
Confirm live fees and limits, use fresh live credentials, set the correct public webhook URL, and verify that the receiver stores events durably before acknowledging them. Keep keys and signing secrets out of logs.
Make an authorized low-value live collection and payout, then verify the final payment states and merchant balances. Confirm your support process for unresolved payments and exhausted webhook deliveries. Do not automate replacement payouts for uncertain outcomes.