Initiate Payments

This document covers payment transactions and their initialization using our Direct Charges API or our SDKs.

This solution is specifically designed for physical stores and integrated Enterprise Resource Planning software.

Chapa Inline, Standard, and HTML checkout make it easy for you to collect payments via card, bank, or any of our supported methods with one integration. However, they come bundled with the Chapa UI, branding, and experience.

Sometimes you want more control, or a custom solution that fits your app. That is where direct charge comes in. We provide the APIs to charge customers, but you collect their payment information yourself and bring your own UI and payment flow. This means you can customize and control the customer experience as you wish.

With direct charge, you have to integrate separately for each payment method you want to support, which can be tasking. Use direct charge only when your customers will be using a specific payment method such as mobile wallets or banks.

How does direct charge work?

There are three main stages in direct charge:

1. Initiate the payment: You send the transaction details and the customer's payment details to the appropriate charge endpoint.
2. Authorize the charge: The customer authorizes the charge with their payment provider, such as their mobile wallet issuer or bank. This completes the charge.
3. Verify the payment: As a failsafe, call our API to verify that the payment was successful before giving value using the verify transaction endpoint.

These steps vary 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 collecting payments via direct charge. Each type of direct charge has its own unique requirements and authorization flow.

• telebirr
• mpesa
• cbebirr
• coopay_ebirr
• enat_bank (portal view)
• awashbirr
• yaya

Query

Body Params

Before carrying out the transaction, a user must provide required information such as full name, email address, and the amount to transfer. Below is the list of needed parameters:

Initialize the Transaction and Get a Response

Once all the information needed to proceed with the transaction is available, the next action is to send it to the charge endpoint for the chosen payment method.

Endpoint: https://api.chapa.co/v1/charges?type={payment_method_name}
Method: POST

curl

curl --location 'https://api.chapa.co/v1/charges?type=telebirr' \
  --header 'Authorization: Bearer CHASECK-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
  --form 'amount="10"' \
  --form 'currency="ETB"' \
  --form 'tx_ref="12311se2319ud4"' \
  --form 'mobile="09xxxxxxxx"'

Types of Direct Charges

USSD

A USSD push notification is sent to the account owner for transaction authorization.

Examples:

• Telebirr
• Mpesa
• AwashBirr
• Yaya Wallet
• CBEBirr
• Coopay-Ebirr

Example response for USSD

Successful Response

{
  "message": "Charge initiated",
  "status": "success",
  "data": {
    "auth_type": "ussd",
    "requestID": "66dPW486w0z6uibrcraZ2diYztK2lx2WaslwGnS18UBXTctDxRdAudYtq3jJtMu7CV6gzyCpBSfrm9kKFJBsA8Wq7zKvk0UxL",
    "meta": {
      "message": "Payment successfully initiated with telebirr",
      "status": "success",
      "ref_id": "CH3mhMQVhsHm2",
      "payment_status": "PENDING"
    },
    "mode": "live"
  }
}

Failed Response

{
  "message": "Authorization required",
  "status": "failed",
  "data": null
}

Portal View

The response contains HTML content which should be opened in a separate new tab for completing the transaction. It will not work inside a frame.

Example:

• Enat Bank

Example response for portal view

Successful Response

{
  "message": "Charge initiated",
  "status": "success",
  "data": {
    "auth_type": "portal_view",
    "requestID": "Zn6qkFmZ0Rzwbv3oxEZQPftK0h1GI5tTiPBfAe3yGQJdO4N8KH8V46wDXwZLnxxVazOiHOhBWDHG9uos6OUsu9Uplf6XLg4KL",
    "meta": {
      "message": "Payment successfully initiated with Enat Bank",
      "status": "success",
      "portal": "https://bank.com",
      "ref_id": "CHIao4sITVmom",
      "payment_status": "PENDING"
    },
    "mode": "live"
  }
}

Failed Response

{
  "message": "Payment failed",
  "status": "failed",
  "data": null
}