Card Payments API

Welcome
Payments
Payouts
Postman

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.

🌐
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: integerrequired

The quantity of this one item.

unit_price: double | 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)

card_details: objectrequired

An object providing payment amount details

card_number: integerrequired

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

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