MyPay API

MyPay lets you collect M-Pesa payments straight into your till, paybill or bank account with a single API call. You don't need your own Daraja app. We send the STK push, Safaricom tells us the result, and we forward it to your callback URL.

Base URL

https://mypay.co.ke/api/v1

Format

JSON request bodies (Content-Type: application/json) or form data. JSON responses.

Method

All endpoints use POST.

How a payment works

1. Your system calls STK Push with the amount, phone number and reference.
2. The customer gets an M-Pesa prompt on their phone and enters their PIN.
3. Money goes directly to your till, paybill or bank account.
4. MyPay POSTs the result to the account's callback URL. You can also poll the status.

Account types

One MyPay login can link many accounts. Each account has its own API key, signin key, callback URL, payment pages and subscription.

Whatever the account type, the reference you send is stored and returned to you as TransactionReference in callbacks and status responses, so you can match payments to orders.

Activation & billing

Every linked account costs KES 350 per month. New accounts are inactive. While an account is inactive or expired:

• STK Push requests are rejected with MP402 (never paid) or MP403 (expired).
• Its payment pages show "not accepting payments".

To activate, open the account in your dashboard and click Pay & activate. You'll get an M-Pesa prompt to pay paybill 4322685 (account MYPAY<account id>). The account activates automatically when payment is confirmed. You can pay for 1, 3, 6 or 12 months at once, and renewing early adds the time on top of your current expiry date.

Authentication

Each request includes the account's api_key and signin_key in the request body. You'll find them on the account page in your dashboard.

STK Push

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

Request

Example: cURL

curl -X POST https://mypay.co.ke/api/v1/stkpush \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "mp_live_xxxxxxxxxxxxxxxx",
    "signin_key": "mpsk_xxxxxxxxxxxxxxxxxxxxxxxx",
    "amount": "100",
    "msisdn": "0712345678",
    "reference": "ORDER-001"
  }'

Example: PHP

$payload = [
    'api_key'    => 'mp_live_xxxxxxxxxxxxxxxx',
    'signin_key' => 'mpsk_xxxxxxxxxxxxxxxxxxxxxxxx',
    'amount'     => '100',
    'msisdn'     => '0712345678',
    'reference'  => 'ORDER-001',
    // 'account_number' => 'INV-2045', // paybill accounts only
];

$ch = curl_init('https://mypay.co.ke/api/v1/stkpush');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($response['success']) {
    // Save this to match the callback later
    $transactionRequestId = $response['transaction_request_id'];
} else {
    echo $response['error_code'] . ': ' . $response['message'];
}

Example: JavaScript (Node.js)

const res = await fetch('https://mypay.co.ke/api/v1/stkpush', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_key: process.env.MYPAY_API_KEY,
    signin_key: process.env.MYPAY_SIGNIN_KEY,
    amount: '100',
    msisdn: '0712345678',
    reference: 'ORDER-001',
  }),
});
const data = await res.json();

Example: Python

import requests

r = requests.post("https://mypay.co.ke/api/v1/stkpush", json={
    "api_key": "mp_live_xxxxxxxxxxxxxxxx",
    "signin_key": "mpsk_xxxxxxxxxxxxxxxxxxxxxxxx",
    "amount": "100",
    "msisdn": "0712345678",
    "reference": "ORDER-001",
})
print(r.json())

Success response HTTP 200

{
  "success": true,
  "ResponseCode": 0,
  "message": "STK push sent. Customer should enter their M-Pesa PIN.",
  "transaction_request_id": "MPY20261010153045123456",
  "MerchantRequestID": "29115-34620561-1",
  "CheckoutRequestID": "ws_CO_123456789",
  "amount": 100,
  "msisdn": "254712345678",
  "reference": "ORDER-001"
}

A success response only means the prompt was sent. Wait for the callback or check the status to know whether the customer paid. Save transaction_request_id, because the callback includes it as TransactionID.

Error response HTTP 4xx / 5xx

{
  "success": false,
  "error_code": "MP402",
  "message": "Account is inactive. Pay the KES 350 monthly subscription to activate it."
}

See all error codes.

Transaction status

Gets the current status of a payment. If a payment is still pending after 30 seconds, MyPay checks with Safaricom directly before it responds.

Request

curl -X POST https://mypay.co.ke/api/v1/status \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "mp_live_xxxxxxxxxxxxxxxx",
    "signin_key": "mpsk_xxxxxxxxxxxxxxxxxxxxxxxx",
    "transaction_request_id": "MPY20261010153045123456"
  }'

Response

{
  "success": true,
  "status": "success",
  "ResponseCode": 0,
  "ResponseDescription": "Success",
  "MerchantRequestID": "29115-34620561-1",
  "CheckoutRequestID": "ws_CO_123456789",
  "TransactionID": "MPY20261010153045123456",
  "TransactionAmount": 100,
  "TransactionReceipt": "SHJ7ABCDEF",
  "TransactionDate": "20261010153045",
  "TransactionReference": "ORDER-001",
  "Msisdn": "254712345678"
}

status is one of pending, success or failed. While a payment is pending, ResponseCode is null.

Callbacks (webhooks)

Add a callback URL to each account in your dashboard. Each account must use its own, unique callback URL. When a payment succeeds or fails, MyPay sends a POST with a JSON body to that URL.

Successful payment

{
  "ResponseCode": 0,
  "ResponseDescription": "Success",
  "MerchantRequestID": "29115-34620561-1",
  "CheckoutRequestID": "ws_CO_123456789",
  "TransactionID": "MPY20261010153045123456",
  "TransactionAmount": 100,
  "TransactionReceipt": "SHJ7ABCDEF",
  "TransactionDate": "20261010153045",
  "TransactionReference": "ORDER-001",
  "Msisdn": "254712345678"
}

Failed or cancelled payment

{
  "ResponseCode": 1032,
  "ResponseDescription": "Request cancelled by user",
  "MerchantRequestID": "29115-34620561-1",
  "CheckoutRequestID": "ws_CO_123456789",
  "TransactionID": "MPY20261010153045123456",
  "TransactionAmount": 100,
  "TransactionReceipt": null,
  "TransactionDate": null,
  "TransactionReference": "ORDER-001",
  "Msisdn": "254712345678"
}

ResponseCode 0 means paid. Any other value is an M-Pesa result code explaining why the payment failed.

Headers

Delivery & retries

• Respond with any 2xx status within 15 seconds to acknowledge.
• If your endpoint fails, MyPay retries up to 6 times, waiting longer before each retry (1, 2, 4, 8 and 16 minutes).
• You can resend any callback from the dashboard. Use Send test callback to try out your handler.
• The same payment can arrive more than once, so check TransactionID and skip payments you've already processed.

Webhook handler sample

<?php
// webhook.php - Handle MyPay webhook notifications

$json = file_get_contents('php://input');

// Optional but recommended: verify the signature
$secret = 'whsec_xxxxxxxxxxxxxxxx'; // account webhook secret from the dashboard
$expected = hash_hmac('sha256', $json, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_MYPAY_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($json, true);

// Validate webhook data
if (!$data || !isset($data['TransactionID'])) {
    http_response_code(400);
    echo "Invalid webhook data";
    exit;
}

$responseCode  = $data['ResponseCode'];
$transactionId = $data['TransactionID'];
$amount        = $data['TransactionAmount'];
$receipt       = $data['TransactionReceipt'];
$phone         = $data['Msisdn'];
$reference     = $data['TransactionReference'];

if ($responseCode == 0) {
    // Payment successful - update your database
    processSuccessfulPayment($transactionId, $amount, $receipt, $phone, $reference);
    http_response_code(200);
    echo json_encode(['status' => 'success']);
} else {
    // Payment failed
    processFailedPayment($transactionId, $responseCode);
    http_response_code(200);
    echo json_encode(['status' => 'received']);
}

Payment pages

Don't have a website? Create a payment page for any account in the dashboard and share its link, such as https://mypay.co.ke/pay/mama-mboga. Customers don't need to log in. They enter their phone number (and the amount, if it isn't fixed) and get an M-Pesa prompt.

• Fixed amount: every customer pays the same amount, e.g. a KES 500 ticket.
• Customer enters amount: you can set a minimum amount.
• Till and paybill pages can let the customer type their own reference or account number, e.g. a house number.
• Bank pages always pay to your linked bank account number.
• Page payments are sent to the account's callback URL like any API payment.

MyPay error codes

M-Pesa result codes

These come from Safaricom and are passed through as ResponseCode in callbacks and status responses.