Chapa Developer Documentation

Learn how to accept payments from your customers using Chapa's API. Initialize transactions and handle the complete payment flow.

When accepting a payment, a transaction is established and following every transaction carries out a complete payment method.

Collecting Customer Information

Before carrying out the transaction, a user must provide required information such as full name, email address, the amount to transfer, etc.

Parameter	Description
`amount`	The amount you will be charging your customer
`phone_number`	Required for high-risk businesses

Parameter	Description
`email`	A customer's email address
`first_name`	A customer's first name
`last_name`	A customer's last name
`phone_number`	The customer's phone number
`callback_url`	Function that runs when payment is successful
`return_url`	Web address to redirect the user after payment
`customization[title]`	Custom title for the payment modal
`tx_ref`	A unique reference given to each transaction
`currency`	Currency for charges (ETB or USD)

Phone number is not required, but if you pass phone_number, it must be 10 digits in 09xxxxxxxx or 07xxxxxxxx format.

Once all the information needed to proceed with the transaction is retrieved, initialize the transaction to get a payment link.

Endpoint: https://api.chapa.co/v1/transaction/initialize

Method: POST

Pass your secret key as a bearer token in the Authorization header.

JSON

cURL

JavaScript

PHP

Python

Redirect your customer to the link returned in data.checkout_url, and we'll display our checkout modal for them to complete the payment.

When payment is successful, four things will happen:

On your server, you should handle the redirect and always verify the final state of the transaction.

When the payment is completed, the callback_url will receive a GET request with:

{
  "trx_ref": "chewatatest-6669",
  "ref_id": "APqDvYw1okk2",
  "status": "success"
}

Parameter	Description
`trx_ref`	The unique transaction reference you provided
`ref_id`	Chapa's internal reference ID
`status`	Transaction status: "pending", "success", "failed", etc.