MPesa Payment Endpoint
This Mpesa Payment Endpoint Provides you with the ability to receive payments through M-Pesa STK push.
The Payment-Initiate API endpoint allows you to pass details of any payment directly to chpter., along with the transaction details (email, amount, products etc).
To initialize the transaction, you’ll need to pass information such as payment method, phone number, full name, total amount etc. Some of the information is required and you can pass additional information to the particular payment.
Endpoint Parameters
Here is the full list of parameters you can pass:
customer_details: object | required
An object providing customer payment details.
payment_method: string | required
The type of payment method at the time of the transaction.
full_name: string | required
The customer’s full name for displaying to merchant and on the receipt.
location: string | optional
Delivery and shipping address of the customer.
phone_number: string | required
The customer’s phone number to process the M-PESA payment. Country code followed by the 9-digit customer’s Mobile Number phone number in the 2547xxxxxxxx format or 2541xxxxxxxx format. The phone number should start with 7 or 1.
email: string | required
The customer’s email address required to display to merchant and receipt.
products: list | optional
A list providing product details that the customer is paying for. The product items can be as many as the customer is checking out and not limited to a single item.
product_id: integer | optional
Unique identifier for the product.
product_name: string | required
The product name of this item.
quantity: string | required
The quantity of this one item.
unit_price: string | required
The unit price of one item
amount: object | optional
An object providing payment amount details.
delivery_fee: string | required
Amount intended to be charged by this payment as the delivery fee. A positive integer.
discount_fee: string | required
Amount intended to be discounted from the payment. A positive integer.
total: string | required
Total Amount intended to be collected by this payment. A positive integer representing how much to charge.
currency: string | required
The currency which is used to make the payment. (3 character code)
callback_details: object | required
An object providing payment amount details
transaction_reference: string | required
A transaction Id that you will use to update your saved pending transaction to successful in your callback.
callback_url: url | required
Your callback/web hook url to get success or failed responses once payments are complete.
Request Payload
The MPesa API payload example.
{
"customer_details": {
"payment_method": "MPesa",
"full_name": "John Doe",
"location": "Nairobi",
"phone_number": "254700123123",
"email": "johndoe@mail.com"
},
"products": [
{
"product_id": "08",
"product_name": "HoodEez",
"quantity": "1",
"unit_price": "100"
}
],
"amount": {
"delivery_fee": "0",
"discount_fee": "0",
"total": "100",
"currency": "kes"
},
"callback_details": {
"transaction_reference": "123456789123",
"callback_url": "https://chpter.co/callback-webhook/"
}
}Response
The response you get to confirm that the MPesa STK has been initiated.
{
"message": "M-PESA Payment Initiated",
"status": 200
}Successful CallBack Response Payload
The response your callback/webhook gets when the payment is successful.
{
"id": "53781-120700473-1",
"response_status": 200,
"payment_method": "M-PESA",
"message": "M-PESA Payment Success",
"amount": 100,
"amount_captured": 100,
"payment_status": "Payment complete.",
"transaction id": "QW779YUW90909",
"paid": "True",
"timestamp": 1678863029
}Failed CallBack Response Payload
The response your callback/webhook gets when the payment fails.
{
"id": "46355-42434411-1"
"transaction_reference": "123456789123"
"response_status":406
"amount": 100
"paid":"False"
"payment status": "Payment Incomplete."
"message":"insufficient for the transaction",
"timestamp":1678863029
}