Environments
Identify the correct API deployment before sending requests.
Use the dashboard's base URL
The Developers → API keys and Developers → Webhooks pages display the API base URL and the environment reported by that API:
| Label | Meaning |
|---|---|
| Live | The API is configured for production M-Pesa |
| Sandbox | The API is configured for sandbox M-Pesa |
| Environment unavailable | Configuration was not reported; verify it before integrating |
Copy the full base URL, including /api/v1. Do not assume the web dashboard's hostname is also the API hostname.
Keep sandbox and live separate
Use separately provisioned deployments, databases, and credentials for sandbox and live. This API does not provide per-key sandbox isolation: the environment label describes deployment configuration, not a guarantee of separate funding or a simulated transaction. Confirm the deployment with your administrator. There is no request flag or dashboard toggle that turns a live payment into a test payment. A sandbox key must not be copied into a live environment.
Live requests can move money
Confirm the environment and merchant account before running a collection or payout example.
Local preview
The project's local preview runs against a dedicated test database and simulated payment provider. Its base URL is http://127.0.0.1:4319/api/v1. Local HTTP is only for that loopback preview, not a hosted integration.
The local simulator does not contact M-Pesa and does not deliver webhooks to external servers. Delivery records can still appear in the preview. Use an appropriately configured sandbox deployment to test actual webhook delivery.
Production availability
Publishing the web dashboard does not enable the merchant API. If the merchant module has not been activated, its routes may return 404. Contact the DeriPay administrator to confirm onboarding and activation before testing credentials.