Skip to main content
Use the REST API when your backend is not running Node.js or when you want direct control over HTTP requests.

​
Prerequisites

​
Sandbox test values

For the default sandbox path, you do not need to set up Daraja credentials before your first payment. Moflay uses default sandbox test credentials unless you add your own sandbox credentials. Use these values for the first test: Sandbox payments do not move real money. The first response commonly returns pending; check the final status by polling during development or by using webhooks in production.

​
Send your first payment

1

Store your API key

2

Start an express payment

Call POST /v1/express with either phoneNumber or customerId. For the first test, use phoneNumber.
The API returns 202 Accepted after Moflay sends the payment request to M-Pesa.
3

Check the payment status

Use the paymentId returned by POST /v1/express to read the latest payment status. You can also use the related transactionId if that is the identifier you stored.
The status can move from pending to a final state such as completed, failed, or canceled. See Payment statuses & outcomes for the full status reference.

​
Request rules

If you use customerId, do not send extra customer fields such as customerName or customerDescription in the same request.

​
Production status handling

Polling GET /v1/payments/{id} is useful during development. In production, configure Moflay webhooks so your backend receives signed payment events such as payment.completed, payment.failed, and payment.canceled.

​
Verify the result

Your HTTP integration is working when:
  • POST /v1/express returns 202
  • The response includes a paymentId
  • GET /v1/payments/{id} returns the same payment in the sandbox environment

​
Troubleshooting

  • Payment creation returns invalid_access: Add the express.pay permission to the key or create a new sandbox key with that permission.
  • Status polling returns invalid_access: Add the transactions.read permission to the key or create a new sandbox key with that permission.
  • The payment does not appear in the dashboard: Confirm you are viewing the sandbox environment.