M-PESA Payments

M-PESA API

Accept M-PESA payments via STK Push. Customers authorize payments directly on their phone.

Note

M-PESA STK Push works by sending a payment prompt to the customer's phone. The customer enters their M-PESA PIN to authorize the payment.

Payment Flow

1Your server calls the init-payment endpoint
2Customer receives STK Push prompt on their phone
3Customer enters M-PESA PIN to authorize
4Safaricom processes the payment
5Webhook notification sent to your callback URL
6Optionally query status using confirmPayment endpoint

POST/api/v1/init-payment

API Key Required

Initiate STK Push

Send an STK Push prompt to the customer's phone to authorize a payment.

Parameter	Type	Description
`phoneNumber`required	`string`	Customer phone number in format 254XXXXXXXXX Example: `254712345678`
`amount`required	`number`	Amount to charge in KES Example: `100`
`orderId`required	`string`	Your unique order/transaction reference Example: `ORDER-001`
`accountReference`required	`string`	Account reference shown on customer phone Example: `Payment`
`transactionDesc`	`string`	Transaction description Example: `Order payment`
`callbackUrl`	`string`	URL to receive payment notification Example: `https://your-site.com/webhook`

Code Examples

const response = await fetch('https://api.serixpay.com/api/v1/init-payment', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pk_test_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phoneNumber: '254712345678',
    amount: 100,
    orderId: 'ORDER-001',
    accountReference: 'Payment',
    transactionDesc: 'Order payment',
    callbackUrl: 'https://your-site.com/webhook'
  })
});

const data = await response.json();
console.log(data.checkoutRequestId);

POST/api/v1/confirmPayment/:CheckoutRequestID

API Key Required

Query Payment Status

Check the status of an STK Push payment using the checkoutRequestId.

Parameter Type Description

Parameter	Type	Description
`CheckoutRequestID`required	`string`	The checkoutRequestId from the init-payment response Example: `ws_CO_01012024123456789`

CheckoutRequestIDrequired

string

The checkoutRequestId from the init-payment response

Example: ws_CO_01012024123456789

Code Examples

const checkoutRequestId = 'ws_CO_01012024123456789';

const response = await fetch(
  `https://api.serixpay.com/api/v1/confirmPayment/${checkoutRequestId}`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer pk_test_your_api_key',
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();
console.log(data.status); // 'completed', 'pending', or 'failed'

GET/api/v1/transactions

List Transactions

Retrieve a paginated list of M-PESA transactions for your organization.

Query Parameters

Parameter	Type	Description
`page`	`number`	Page number for pagination
`limit`	`number`	Items per page (max 100)
`status`	`string`	Filter by status: completed, pending, failed
`startDate`	`string`	Filter from date (ISO 8601)
`endDate`	`string`	Filter to date (ISO 8601)

Transaction Statuses

initiatedSTK Push sent, waiting for customer

pendingCustomer received prompt, awaiting PIN

completedPayment successful

failedPayment declined or error occurred

cancelledCustomer cancelled the prompt

timeoutCustomer did not respond in time

Webhook Payload

When a payment completes, we send a webhook to your callback URL:

{
  "event": "payment.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "orderId": "ORDER-001",
    "checkoutRequestId": "ws_CO_01012024123456789",
    "amount": 100,
    "currency": "KES",
    "status": "completed",
    "method": "mpesa",
    "mpesaReceiptNumber": "ABC123XYZ",
    "phoneNumber": "254712345678",
    "transactionDate": "2024-01-15T10:30:00Z"
  }
}