API Reference

This page will help you with Level - API integration flow.

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

ParameterRequiredDescription
secret_key stringYesThis is important for creating payment links
callback_url urlYesThis 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 urlYesOnce the customer cancels or after multiple failed attempts, we will redirect to the return_url with the query parameters tx_ref and status of failed.
tx_ref stringYesYour transaction reference. This MUST be unique for every transaction.
first_name stringYesThis is the first name of your customer.
last_name stringOptionalThis is the last name of your customer.
email stringOptionalThis is the email address of your customer. Transaction notification will be sent to this email address
currency stringYesCurrency to charge in. [ 'MWK', 'USD' ]
amount int32YesAmount to charge the customer.
customization arrayOptional{
"title":"Title of payment",
"description":"Description of payment",
}
meta arrayOptionalYou 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": "Hosted payment session generated successfully.",
  "status": "success",
  "data": {
    "event": "checkout.session:created",
    "checkout_url": "https://api.paychangu.com/payment/923677185321",
    "data": {
      "tx_ref": "ae041eae-6abd-4602-a949-56fbd65c29fe",
      "currency": "MWK",
      "amount": 100,
      "mode": "live",
      "status": "pending"
    }
  }
}

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:

  1. 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.

  2. Call your webhook URL (if one is set).

  3. 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 return_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.