Skip to main content

Documentation Index

Fetch the complete documentation index at: https://moflay.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Prerequisites

​
Step 1: Store your API key

export MOFLAY_API_KEY="mof_test_your_api_key"

​
Step 2: Start an express payment

Call POST /v1/express with either phoneNumber or customerId. For the first test, use phoneNumber. 
curl https://api.moflay.com/v1/express \
  -X POST \
  -H "Authorization: Bearer $MOFLAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
    "phoneNumber": "254712345678",
    "amount": 100,
    "description": "Order 1001",
    "accountReference": "ORDER1001"
  }'
The API returns 202 Accepted after Moflay sends the payment request to M-Pesa. 
{
  "paymentId": "pay_ABC123DEF456GHI",
  "transactionId": "trxn_ABC123DEF456GHI",
  "customerId": "cus_GqfKXLmg61LURZhB",
  "phoneNumber": "254712345678",
  "amount": 100,
  "currency": "KES",
  "status": "pending",
  "description": "Order 1001",
  "accountReference": "ORDER1001",
  "environment": "sandbox",
  "timestamp": "2024-12-19T10:25:00.000Z",
  "message": "Payment request sent to customer"
}

​
Step 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. 
curl https://api.moflay.com/v1/payments/pay_ABC123DEF456GHI \
  -H "Authorization: Bearer $MOFLAY_API_KEY"

curl https://api.moflay.com/v1/payments/trxn_ABC123DEF456GHI \
  -H "Authorization: Bearer $MOFLAY_API_KEY"
The status can move from pending to a final state such as completed or failed.

​
Request rules

FieldRequirement
phoneNumber or customerIdOne is required
amountWhole number, greater than 0, up to 250000
descriptionRequired, up to 13 characters
accountReferenceOptional, up to 12 alphanumeric characters
Idempotency-KeyOptional, recommended for payment creation retries
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/{paymentId} is useful during development. In production, configure Moflay webhooks so your backend receives signed payment events such as payment.completed and payment.failed.

​
Verify the result

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