Card Payment Endpoint
The Card 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: integer | required
The quantity of this one item.
unit_price: double | 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)
card_details: object | required
An object providing payment amount details
card_number: integer | required
The customer’s 16-digit Credit(ATM) card number required for payment. The card number must be valid to process the payment.
expiry_month: integer | required
The 2-digit number representing the card’s expiration month required for payment. The expiry month must be valid to process the payment.
expiry_year: integer | required
The 4-digit number representing the card’s expiration year required for payment. The expiry year must be valid to process the payment.
cvc: integer | required
The 3-digit card security code required for payment. The card security code must be valid to process the payment.
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 Card API payload example.
{
"customer_details": {
"payment_method": "Card",
"full_name": "John Doe",
"location": "Nairobi",
"phone_number": "254700123123",
"email": "johndoe@mail.com"
},
"products": [
{
"product_id": "08",
"product_name": "HoodEez",
"quantity": "1",
"unit_price": "1"
}
],
"amount": {
"delivery_fee": "0",
"discount_fee": "0",
"total": "10000",
"currency": "kes"
},
"card_details": {
"card_number": "4545454545454545",
"expiry_month": "08",
"expiry_year": "2024",
"cvc": "123"
},
"callback_details": {
"transaction_reference": "123456789123",
"callback_url": "https://chpter.co/callback-webhook/"
}
}Response
The response you get to confirm that the Card payment has been received for processing.
{
"message": "Card Payment Initiated",
"status": 200
}Successful CallBack Response Payload
The response your callback/web hook gets when the payment is successful.
{
"id":"chp_id_1Lp4ZNKv0vSxkVAb4mS4va8e",
"status":200,
"payment method":"CARD",
"message":"CARD Payment Success",
"amount":"200",
"currency": "kes",
"amount captured":"200",
"payment status":"Payment complete.",
"transaction id": "3Lp4ZNKv0vSxkVAb0EYGJwiB",
"paid": "True",
"timestamp": 1678863029
}Failed CallBack Response Payload
The response your callback/web hook gets when the payment fails.
{
"id":"chp_id_1Lp4ZNKv0vSxkVAb4mS4va8e",
"status":200,
"payment method":"CARD",
"message":"CARD Payment Failed",
"amount":"200",
"currency": "kes",
"payment status":"Payment incomplete.",
"transaction id": "3Lp4ZNKv0vSxkVAb0EYGJwiB",
"paid": "False",
"timestamp": 1678863029
}