API reference

Base URL: https://nixpay.supreonix.com/api/v1

Initiate an STK Push

POST /api/v1/payments/stk-push

Sends an M-PESA payment prompt to the customer's phone.

Body parameters

Field	Type	Required	Description
`amount`	number	Yes	Amount in the merchant currency (KES).
`phone`	string	Yes	Customer MSISDN. `07…`, `01…` or `2547…`.
`account_reference`	string	No	Your own reference, e.g. an invoice number.
`description`	string	No	Short description shown to the customer.
`idempotency_key`	string	No	Repeating a request with the same key returns the original transaction.

Example request

curl -X POST https://nixpay.supreonix.com/api/v1/payments/stk-push \\
  -H "Authorization: Bearer \$NIXPAY_SECRET_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "amount": 500,
    "phone": "254712345678",
    "account_reference": "INV-1042",
    "description": "Order payment"
  }'

Example response

{
  "ok": true,
  "data": {
    "reference": "NP-10021",
    "status": "pending",
    "environment": "sandbox",
    "amount": 500,
    "currency": "KES",
    "customer_phone": "2547••••••78",
    "account_reference": "INV-1042",
    "payment_method": "mpesa_stk",
    "mpesa_receipt": null,
    "result_code": "0",
    "result_desc": "Success. Request accepted for processing",
    "created_at": "2026-01-14 09:12:44",
    "completed_at": null
  }
}

Retrieve a transaction

GET /api/v1/payments/{reference}

Returns the current state of a transaction. Poll this, or wait for a webhook.

curl https://nixpay.supreonix.com/api/v1/payments/NP-10021 \\
  -H "Authorization: Bearer \$NIXPAY_SECRET_KEY"

Health check

GET /api/v1/health

Unauthenticated liveness probe.

NixPay documentation · A Supreonix product Back to introduction