M-PESA Payments

Initiate M-PESA Payment

Postman Collection

For more header and response codes descriptions expand the link below.

Initiate M-PESA Payment.

POST https://api.chpter.co/v1/initiate/mpesa-payment

Send an STK push to an MPesa phone number.

Headers

Name	Type	Description
Api-Key*	String	Your chpter Public Key
Content-Type	String	application/json

Request Body

Name	Type	Description
customer_details*	Object	Customer Details
full_name*	String	Customer Name
products*	List / Array	Product Details
location*	String	Customer Location
email*	String	Customer Email
phone_number*	String	Customer PhoneNumber
unit_price*	Float	Product Price
quantity*	Integer	Product Quantity
product_name*	String	Product Name
digital_link	String	Product Digital Link
amount*	Object	Object with Amount Details
discount_fee*	Float	Discount Fee
delivery_fee*	Float	Delivery Fee
currency*	String	Currency code (KES)
total*	Float	Total Amount to be paid
callback_details*	Object	Callback Object
transaction_reference*	String	Unique reference
callback_url*	String	Your callback URL
notify_customer	Boolean	Defaults to true. (The customer will receive a payment receipt from chpter.)

200 Payment Initiated Successfully

{
    "message": "Payment initiated",
    "success": true,
    "status": 200,
    "transaction_reference": "1234",
    "chpter_transaction_ref": "20004-4834176-2"
}

401 Unauthorized

{
    "message": "unauthorized",
    "success": false,
    "status": 401
}

500: Internal Server Error Failed request

{
    "message": "processing transaction error. please contact [e-mail]",
    "success": false,
    "status": 500
}

400: Bad Request Bad request payload

{
    "message": "payload validation error. ",
    "success": false,
    "status": 400
}

Good to know: This API uses webhooks to notify you of the payment status through the callback url.

Quick view

Sample body and the respective response code.

Body

{
  "customer_details": {
   "full_name": "Albert Chela",
    "location": "Nairobi",
    "phone_number": "254700123123",
    "email": "[e-mail]"
  },
  "products": [
    {
      "product_name": "HoodEez",
      "quantity": 1,
      "unit_price": 1,
      "digital_link": "https://example.com/link"

    }
  ],
  "amount": {
    "currency": "KES",
    "delivery_fee": 0.00,
    "discount_fee": 0.00,
    "total": 1.00
  },
  "callback_details": {
    "notify_customer": true,
    "transaction_reference": "1234",
    "callback_url": "https://eozdpom307nca3.m.pipedream.net"
  }
}

200 Response

{
    "message": "Payment initiated",
    "success": true,
    "status": 200,
    "transaction_reference": "1234",
    "chpter_transaction_ref": "20004-4834176-2"
}

400 Response

{
    "message": "payload validation error. ",
    "success": false,
    "status": 400
}

401 Response

{
    "message": "unauthorized",
    "success": false,
    "status": 401
}

500 Response

{
    "message": "processing transaction error. please contact [e-mail]",
    "success": false,
    "status": 500
}

Webhook / Callback Responses

Good to know: Use the Success key value on the response to check if the payment is successful or not.

Here are sample webhook/callback responses.

Successful Response

{
    "Message":"Successful",
    "Success": true,
    "Status": 200,
    "Amount": 100,
    "transaction_code": "QWERTY1234",
    "transaction_reference": "12345678901345644",
    
}

Failed Response

{
    "Message":"Request cancelled by user",
    "Success": false,
    "Status": 200,
    "transaction_reference":"12345678901345644"
}