Chapa Developer Documentation

This document goes through the necessary actions taken to authorize transactions after payment using Chapa's Direct API.

How to Authorize Transactions

Authorizing a payment depends on the method used when first initializing a transaction. This request is made after you initiate a direct charge payment. Using your transaction reference, make a POST request to the Authorize Transaction endpoint from your server.

Authorizing payments varies depending on the payment method. For example, some mobile money charges may include multiple authorization steps including OTPs. We explain what applies to each method in its guide.

Direct charge options

Here are the different options for authorizing payments initiated via direct charge. Each type of direct charge has its own unique requirements and authorization flow.

telebirr
mpesa
amole
cbebirr
ebirr
awashbirr
yaya

Type of `auth_type` parameters

otp
ussd

When to Encrypt

While using our direct charges API, you are responsible for handling sensitive security information such as OTPs. In those cases, encrypt the secure object from the payload you build. You need your encryption key from the Settings > API section of your dashboard, and you should use the 3DES algorithm for encryption.

You can see examples in our Encryption guide.

Now wrap the encrypted payload inside a JSON body like this:

Successfully Encrypted Payload

{
  "client": "0jhd12Dfee+2h/FzHA/X1zPlDmRmH5v+F4sdsfFFSEgg44FAFDSFS000+YwUHegTSogQdnXp7OGdUxPngiv6592YoL0YXa4eHcH1fRGjAimdqucGJPurFVu4sE5gJIEmBCXdESVqNPG72PwdRPfAINT9x1bXemI1M3bBdydtWvAx58ZE4fcOtWkD/IDi+o8K7qpmzgUR8YUbgZ71yi0pg5UmrT4YpcY2eq5i46Gg3L+rtjhjkgjkjg83hfkjajhf3"
}

Sample Code for Authorizing Transactions

Endpoint: https://api.chapa.co/v1/validate?type=amole
Method: POST

Authorization: Pass your secret key as a bearer token in the request header to authorize this call.

curl

curl --location 'https://api.chapa.co/v1/validate?type=amole' \
  --header 'Authorization: Bearer CHASECK-xxxxxxxxxxxxxxxx' \
  --form 'reference="CHcuKjgnN0Dk0"' \
  --form 'client="0jhd12Dfee+2h/FzHA/X1zPlDmRmH5v+F4sdsfFFSEgg44FAFDSFS000+YwUHegTSogQdnXp7OGdUxPngiv6592YoL0YXa4eHcH1fRGjAimdqucGJPurFVu4sE5gJIEmBCXdESVqNPG72PwdRPfAINT9x1bXemI1M3bBdydtWvAx58ZE4fcOtWkD/IDi+o8K7qpmzgUR8YUbgZ71yi0pg5UmrT4YpcY2eq5i46Gg3L+rtjhjkgjkjg83hfkjajhf3"'

Successful Response

{
  "message": "Payment is completed",
  "trx_ref": "CHS7WFpXdCMR0",
  "processor_id": null
}

Failed Response

{
  "message": "Invalid client data or Transaction is nowhere to be found.",
  "status": "failed",
  "data": null
}

Refer to our Error Codes page for all responses for this request.

After the Payment

Four things happen when payment is successfully authorized:

We send you a webhook if you have that enabled. You can find more information on Webhooks.
On your server, you should handle the redirect and always verify the final state of the transaction.
It is important to verify the transaction and confirm its status. Here is how you can Verify a Transaction.
Chapa has event listeners that send a message whenever a payment is successful. You can find more information on Webhooks.

Authorize Payments