Request M-Pesa STK push payment

Request

🔒 Private label — contact sales. Requires a private-label entitlement on your API client.

Security

oauth2ClientCredentials(Required scopes: payments:write)

org_wallet_refstring

Organization wallet reference, defaults to "1" if not provided

business_idstringrequired

Business identifier for the request

Bodyapplication/jsonrequired

phoneNumberstringrequired

M-Pesa phone number

Example:"254712345678"

amountnumberrequired

Payment amount

Example:100

accountNumberstringrequired

Account reference number

Example:"INV001"

notestringrequired

Payment note/description

Example:"Payment for invoice"

curl -i -X POST \
  https://developer.boyahq.com/_mock/v2/openapi/payments/request-mpesa-payment \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'business_id: string' \
  -H 'org_wallet_ref: string' \
  -d '{
    "phoneNumber": "254712345678",
    "amount": 100,
    "accountNumber": "INV001",
    "note": "Payment for invoice"
  }'

Responses

M-Pesa payment request initiated successfully

Bodyapplication/json

MerchantRequestIDstringrequired

Merchant request ID

Example:"9a7a-428c-9f96-2533a83f54c22766019"

CheckoutRequestIDstringrequired

Checkout request ID

Example:"ws_CO_15012026123947186710702289"

ResponseCodestringrequired

Response code (0 = success)

Example:"0"

ResponseDescriptionstringrequired

Response description

Example:"Success. Request accepted for processing"

CustomerMessagestringrequired

Customer message

Example:"Success. Request accepted for processing"

statusnumberrequired

Status (1 = success)

Example:1

Response

{
  "MerchantRequestID": "9a7a-428c-9f96-2533a83f54c22766019",
  "CheckoutRequestID": "ws_CO_15012026123947186710702289",
  "ResponseCode": "0",
  "ResponseDescription": "Success. Request accepted for processing",
  "CustomerMessage": "Success. Request accepted for processing",
  "status": 1
}