Mpesa API

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.

🌐
POST https://chpter.co/api/payment/payment-initiate-callback/

Endpoint Parameters

Here is the full list of parameters you can pass:

customer_details: objectrequired

An object providing customer payment details.

payment_method: stringrequired

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: stringoptional

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: listoptional

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: integeroptional

Unique identifier for the product.

product_name: string | required

The product name of this item.

quantity: stringrequired

The quantity of this one item.

unit_price: string | required

The unit price of one item

amount: objectoptional

An object providing payment amount details.

delivery_fee: stringrequired

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: stringrequired

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: objectrequired

An object providing payment amount details

transaction_reference: stringrequired

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
}