Level

PayChangu provides access to your resources through RESTful endpoints, allowing you to test the API. You can also access your test API credentials and keys from here.

HTTP Request Sample

We provide cURL request samples so you can quickly test each endpoint on your terminal or command line. Need a quick how-to for making cURL requests? Just use an HTTP client such as Postman, like the rest of us!

Requests and Responses

Both request body data and response data are formatted as JSON. Content type for responses are always of the type application/json. You can use the PayChangu API in test mode, which does not affect your live data. The API key you use to authenticate the request determines whether the request is live mode or test mode

Initiate Transaction

Parameter	Required	Description
secret_key string	Yes	This is important for creating payment links
callback_url url	Optional	This is your IPN URL, which is essential for receiving payment notifications. Successful transactions will redirect to this URL after payment. The {tx_ref} is returned, so you don’t need to include it in your URL.
return_url url	Optional	URL to redirect to upon transaction completion. This is particularly useful for 3D Secure payments, allowing us to redirect your customer back to a custom page you want to display.
tx_ref string	Optional	Your transaction reference. This MUST be unique for every transaction.
first_name string	Yes	This is the first name of your customer.
last_name string	Yes	This is the last name of your customer.
email string	Yes	This is the email address of your customer. Transaction notification will be sent to this email address
currency string	Yes	Currency to charge in. [ 'MWK', 'USD' ]
amount int32	Yes	Amount to charge the customer.
customization array	Yes	{ "title":"Title of payment", "description":"Description of payment", "logo":"https://domain.com/logo.png" }
meta array	Optional	You can pass on extra information here.

curl -X POST "https://api.paychangu.com/payment"
-H "Accept: application/json"
-H "Authorization: Bearer {secret_key}"
-d "{
    "amount": "100",
    "currency": "MWK",
    "email": "[email protected]",
    "first_name":"Kelvin",
    "last_name":"Banda",
    "callback_url": "https://webhook.site/9d0b00ba-9a69-44fa-a43d-a82c33c36fdc",
    "return_url": "https://webhook.site",
    "tx_ref": '' + Math.floor((Math.random() * 1000000000) + 1),
    "customization": {
      "title": "Test Payment",
      "description": "Payment Description",
    },
    "meta": {
      "uuid": "uuid",
      "response": "Response"
    }
}"

Response

{
    "message": "Payment link created",
    "status": "success",
    "data": {
        "checkout_url": "https://api.paychangu.com/payment/09229936784"
    }
}

When you provide the user with the returned link, they will be directed to our checkout page to complete the payment, as shown below.

What happens when the user completes the transaction on the page?
When the user enters their payment details, PayChangu will validate and then charge the card. Once the charge is completed, we will:

Call your specified redirect_url and post the response to you. We will also append your transaction ID (transaction_id), transaction reference (tx_ref), and the transaction status.
Call your webhook URL (if one is set).
Send an email to you and your customer on the successful payment.

Before providing value to the customer, please make a server-side call to our transaction verification endpoint to confirm the status of the transaction.

After the Payment

Four things will happen when a payment is successful:

We’ll redirect you to your callback_url with status tx_ref after payment is complete.
We’ll send you a webhook if you have it enabled. Learn more about webhooks and see examples here.
We’ll send an email receipt to your customer if the payment was successful (unless you’ve disabled this feature).
We’ll send you an email notification (unless you’ve disabled this feature).

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

What if the Payment Fails?

If the payment attempt fails (for instance, due to insufficient funds), you don’t need to take any action. The payment page will remain open, allowing the customer to try again until the payment succeeds or they choose to cancel. Once the customer cancels or after multiple failed attempts, we will redirect to the redirect_url with the query parameters tx_ref and status of failed.

If you have webhooks enabled, we’ll send you a notification for each failed payment attempt. This can be useful if you want to reach out to customers who experienced issues with their payment. See our webhooks guide for an example.