Payment Redirect API
The Payment Redirect API generates a checkout link, that redirects your users to the link to complete payment. After payment is made, the users are returned to your website at the callback_url.
To initialize the transaction, you'll need to pass information such as email, full name, amount, transaction reference, etc. Email and amount are required.
Here's how it works:
- From your server, send the request payload to the endpoint with the payment details.
- We'll return a link to a payment page. Redirect your customer to this link to make the payment.
- When the transaction is completed, we'll redirect the customer back to you.
Endpoint Parameters
Here is the full list of parameters you can pass:
customer_details: object | required
An object providing customer payment details.
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.
amount: object | optional
An object providing payment amount details.
order_id: integer | required
A order Id that you will use to update your saved pending transaction to successful in your callback.
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)
redirect_urls: object | required
An object providing your urls.
success_url: string | required
The url you would like the user redirected to if the payment is a success. (should start with http or https)
failed_url: url | required
The url you would like the user redirected to if the payment fails. (should start with http or https)
callback_url: url | required
Your callback/web hook url to get success or failed responses once payments are complete.
Redirect Checkout Session
Request Payload
The Payment Redirect API payload example.
{
"customer_details": {
"full_name": "John Doe",
"location": "Nairobi",
"phone_number": "254700123123",
"email": "johndoe@mail.com"
},
"amount": {
"order_id": "123",
"delivery_fee": "0",
"discount_fee": "0",
"total": "100",
"currency": "kes"
},
"redirect_urls": {
"success_url": "https://my-success-url.com",
"failed_url": "https://my-failed-url.com",
"callback_url": "https://my-callback-url.com"
}
}Request Response
Response
The response you get will contain a checkout_link url which can be used to redirect the user to chpter payment page.
{
"checkout_link": "https://chpter.co/checkout.sessions/hosted/session/R8K7iFxrN3CW6r0cKu",
"status": true,
"order_id": "123"
}Successful CallBack Response Payload
The response your callback/webhook gets when the payment is successful.
/* MPesa Payment */
{
"payment_method": "MPESA",
"paid": "True",
"response_status": 200,
"order_id": "945",
"message": "M-PESA Payment Successful",
"amount": "100",
"payment_status": "Payment complete."
}
/* Card Payment */
{
"payment_method": "CARD",
"paid": "False",
"response_status": 200,
"order_id": "945",
"message": "Card Payment Successful",
"amount": "100",
"payment_status": "Payment complete."
}Failed CallBack Response Payload
The response your callback/webhook gets when the payment fails.
/* MPesa Payment */
{
"payment_method": "MPESA",
"paid": "False",
"response_status": 200,
"order_id": "945",
"message": "Insufficient funds",
"amount": "100",
"payment_status": "Payment Incomplete."
}
/* Card Payment */
{
"payment_method": "CARD",
"paid": "False",
"response_status": 200,
"order_id": "945",
"message": "Insufficient funds",
"amount": "100",
"payment_status": "Payment Incomplete."
}