Skip to main content

How to Integrate Chapa Payment in Ethiopia: Step-by-Step Guide

A plain guide for Ethiopian developers and businesses: open a Chapa account, get test keys, start and verify a payment, handle webhooks and go live. The Node.js, PHP and cURL examples follow Chapa's own documentation.

Chapa is an Ethiopian payment gateway. With one integration, your website or app can accept telebirr, CBE Birr, M-Pesa, bank transfers and cards. This guide walks through the whole process: opening an account, getting test keys, starting a payment, verifying it, handling webhooks and going live.

Every endpoint, field and header below comes from Chapa's own documentation, checked on 10 November 2026. The code examples are in Node.js, PHP and cURL. Replace the placeholder keys with your own, and keep your secret key on your server.

Chapa has two API versions. New accounts created from chapa.co use API v2. Older accounts at dashboard.chapa.co use API v1. This guide covers both, so first check which version you have.

What Chapa Is and What It Accepts

Chapa is a payment gateway for Ethiopian businesses. Your customer pays on Chapa's hosted checkout page. Chapa collects the money, takes its fee and settles the rest to your bank account.

Chapa's supported payment methods page lists these methods and limits per payment (checked 10 November 2026):

Payment methodMinimum per paymentMaximum per payment
telebirrETB 1ETB 75,000
CBEBirrETB 1ETB 150,000
M-PesaETB 20ETB 75,000
AwashBirrETB 1ETB 600,000
Coopay-EbirrETB 1Unlimited
AmoleETB 1Unlimited
CBE Bank TransferETB 1ETB 9,999,999
COOPETB 1ETB 1,000,000
Awash Bank, Enat Bank, Amhara BankETB 1Unlimited
Credit or debit cardETB 10ETB 500,000
PayPalETB 10ETB 500,000

API v1 accepts payments in ETB and USD. API v2 lists USD, UGX, ETB and DJF. Chapa also has products that need no code, such as payment links and a storefront. See WooCommerce, plugins and no-code options.

Looking for Chapa's Own Site?

This page is a guide by DreamTech, a software company in Addis Ababa. It is not Chapa's website. If you want Chapa itself, use these official links:

Chapa's error codes page gives 8911 as the support number for urgent issues. Its v2 migration guide gives techsupport@chapa.co for technical help.

What You Need Before You Go Live

You can build and test with test keys straight away. To accept real money, Chapa must approve your business first. Chapa's quick start says that until your compliance form is accepted, you can only use test mode.

Chapa's FAQ lists these documents to register (checked 10 November 2026):

  • Business licence
  • TIN certificate
  • Memorandum of association, if your company has one
  • Proof of address
  • ID of the general manager (for a PLC) or of the sole owner (for a sole proprietorship)

Prepare these as well:

  • A working website or app. Chapa's merchant agreement says Chapa evaluates the merchant's website or app and its controls for security.
  • A bank account for settlement. The merchant agreement says Chapa settles collected money to your account at your preferred bank.
  • A server you control. Your secret key, the initialize call and payment verification must run on a server, never in the browser or inside a mobile app.
  • A public HTTPS address for webhooks, so Chapa can notify your server about payments.

Some sectors count as high risk. Chapa's high-risk businesses list includes gambling, crypto exchanges, travel services, multi-level marketing, forex trading, crowdfunding, subscriptions with free trials and e-commerce with high-ticket items. For these businesses, the customer's phone number becomes a required payment field. Ask Chapa about your sector before you build.

Step-by-Step: How to Integrate Chapa

The payment flow has the same shape in both API versions:

  1. Your server asks Chapa to start a payment and gets a checkout_url.
  2. You send the customer to that URL, and they pay on Chapa's page.
  3. Chapa sends the customer back to your return_url and notifies your server.
  4. Your server asks Chapa to verify the payment. Only then do you mark the order paid.

Before you start: check your API version

Look at the start of your secret key in the Chapa dashboard. It tells you which version, and which docs, to follow.

WhatAPI v2API v1
Where the account livesdashboard.chapa.global, where chapa.co's "Start Now" button goesdashboard.chapa.co
Secret key starts withCHAPA_TEST_ in test mode, CHAPA_LIVE_ in live modeCHASECK_TEST- in test mode, CHASECK- in live mode
Base URLhttps://api.chapa.global/v2https://api.chapa.co/v1
Start a paymentPOST /v2/payments/hostedPOST /v1/transaction/initialize
Verify a paymentGET /v2/payments/{reference}/verifyGET /v1/transaction/verify/{tx_ref}
Amount formatInteger cents: 10000 is ETB 100Birr: "100" is ETB 100
Your order referencemerchant_reference, at most 20 characterstx_ref
Extra headerIdempotency-KeyNone
Docsdocs.chapa.globaldeveloper.chapa.co
Chapa's v2 docs call v1 the "legacy" API. v1 is still documented at developer.chapa.co, and many plugins use it, including Chapa's own WooCommerce plugin. If you are starting fresh with a new account, follow v2. Chapa's migration guide explains how to move from v1 to v2.

Step 1: Get your test keys

  1. Create your Chapa account and confirm your email address.
  2. Open Settings, then API Keys. On v1, click your initials at the top right, choose Settings and open the API tab.
  3. Make sure the dashboard is in Test mode. Test mode moves no real money.
  4. Put the secret key (v2 calls it the private key) in an environment variable on your server, such as CHAPA_SECRET_KEY. The public key is only for browser tools such as Inline.js and HTML checkout.

Never put your secret key in frontend code, a mobile app or Git. It can authorise any action on your account. If it leaks, generate new keys in the dashboard straight away. On v1, the Generate new keys button cancels all your old keys.

Do not mix test and live keys. A test key cannot verify a live payment, and a live key cannot verify a test payment.

Step 2: Initialize the payment on your server

When the customer clicks Pay, your server creates the order, gives it a unique reference and asks Chapa for a checkout link.

API v2. Send POST https://api.chapa.global/v2/payments/hosted with three headers: Authorization: Bearer plus your private key, Content-Type: application/json and Idempotency-Key. The required fields are amount (integer cents, minimum 100) and currency. Also send a unique merchant_reference so you can match the payment to your order. This cURL request follows Chapa's v2 quick start:

cURL
curl -X POST 'https://api.chapa.global/v2/payments/hosted' \
  -H "Authorization: Bearer $PRIVATE_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "ETB",
    "merchant_reference": "ref-1791192600",
    "customer": {
      "first_name": "Abebe",
      "last_name": "Kebede",
      "email": "abebe.kebede@example.com",
      "phone_number": "251911000000"
    },
    "callback_url": "https://example.com/chapa/callback",
    "return_url": "https://example.com/chapa/return",
    "meta": {
      "order_id": "ORD-1001"
    }
  }'

The same call in a Node.js app:

Node.js
// Node.js 18 or later (built-in fetch). Keys live in environment variables on the server.
const CHAPA_API = "https://api.chapa.global/v2";

export async function startChapaPayment(order) {
  const response = await fetch(CHAPA_API + "/payments/hosted", {
    method: "POST",
    headers: {
      "Authorization": "Bearer " + process.env.CHAPA_SECRET_KEY,
      "Idempotency-Key": order.idempotencyKey, // create once per payment, reuse on retries
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: order.totalCents,            // integer cents: 10000 = ETB 100
      currency: "ETB",
      merchant_reference: order.reference, // unique, at most 20 characters
      customer: {
        first_name: order.firstName,
        last_name: order.lastName,
        email: order.email,
        phone_number: order.phone,         // international format, e.g. 251911000000
      },
      callback_url: "https://example.com/chapa/callback",
      return_url: "https://example.com/orders/" + order.reference,
      meta: { order_id: order.id },
    }),
  });

  const result = await response.json();
  if (result.status !== "success") throw new Error(result.message);
  return result.data.checkout_url; // send the customer here
}

The Idempotency-Key stops a retried request from creating a second payment. Create one key for each new payment, save it with the order and send the same key if you retry that request.

API v1. Send POST https://api.chapa.co/v1/transaction/initialize with Authorization: Bearer plus your secret key, and Content-Type: application/json. Chapa's error codes page names amount, currency and tx_ref as fields that can be required, so always send them. currency can be ETB or USD. If you send phone_number, it must be 10 digits in the 09xxxxxxxx or 07xxxxxxxx format. This request follows Chapa's v1 accept payments page:

cURL
curl --location --request POST 'https://api.chapa.co/v1/transaction/initialize' \
  --header 'Authorization: Bearer CHASECK_TEST-xxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "amount": "10",
    "currency": "ETB",
    "email": "abebech_bekele@gmail.com",
    "first_name": "Bilen",
    "last_name": "Gizachew",
    "phone_number": "0912345678",
    "tx_ref": "chewatatest-6669",
    "callback_url": "https://example.com/chapa/callback",
    "return_url": "https://example.com/orders/chewatatest-6669"
  }'

The same call in PHP:

PHP
<?php
// Keep the secret key on the server, for example in an environment variable.
function chapaInitialize(array $order): string
{
    $payload = [
        'amount'       => (string) $order['total'], // birr, e.g. "250" for ETB 250
        'currency'     => 'ETB',
        'tx_ref'       => $order['reference'],      // new and unique for every attempt
        'email'        => $order['email'],
        'first_name'   => $order['first_name'],
        'last_name'    => $order['last_name'],
        'phone_number' => $order['phone'],          // 09xxxxxxxx or 07xxxxxxxx
        'callback_url' => 'https://example.com/chapa/callback',
        'return_url'   => 'https://example.com/orders/' . $order['reference'],
    ];

    $curl = curl_init('https://api.chapa.co/v1/transaction/initialize');
    curl_setopt_array($curl, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => json_encode($payload),
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . getenv('CHAPA_SECRET_KEY'),
            'Content-Type: application/json',
        ],
    ]);
    $result = json_decode((string) curl_exec($curl), true);

    if (($result['status'] ?? '') !== 'success') {
        throw new RuntimeException($result['message'] ?? 'Chapa initialize failed');
    }
    return $result['data']['checkout_url']; // send the customer here
}

A successful v1 response looks like this:

JSON
{
  "message": "Hosted Link",
  "status": "success",
  "data": {
    "checkout_url": "https://checkout.chapa.co/checkout/payment/V38JyhpTygC9QimkJrdful9oEjih0heIv53eJ1MsJS6xG"
  }
}

Use a new reference for every payment attempt. Chapa rejects a reused one with "Transaction reference has been used before".

Step 3: Send the customer to checkout and handle the return URL

Redirect the customer to data.checkout_url. On a website, send a redirect from your server. In a mobile app, open the URL in a browser tab or web view. The customer chooses telebirr, CBE Birr, a card or another method and pays on Chapa's page.

On API v1, Chapa's accept payments page says four things happen after a successful payment:

  • Chapa redirects the customer to your return_url, if you set one.
  • Chapa calls your callback_url with a GET request containing trx_ref, ref_id and status.
  • Chapa sends a webhook, if you have turned webhooks on.
  • Chapa sends an email notification, unless you have turned that off.

API v2 works the same way: the customer comes back to your return_url, and your server gets a webhook.

The return URL is not proof of payment. Anyone can open it in a browser. Chapa's v2 docs say redirects and webhooks are signals only. Show the customer a "checking your payment" page, then verify on your server (Step 4) before you confirm the order.

If a payment fails, Chapa keeps the checkout open so the customer can try again. On v1, a customer can retry a failed payment up to 10 times within a window you set in the dashboard, from 5 to 60 minutes (60 by default).

Step 4: Verify the payment before you deliver

This is the step that protects your money. Call Chapa's verify endpoint from your server with your reference. Then check four things against your own order: the status, the amount, the currency and the reference.

API v2. Call GET https://api.chapa.global/v2/payments/{paymentReference}/verify. You can use your merchant_reference or Chapa's payment reference. A paid payment has data.status equal to SUCCESS, in capital letters. Building on the Node.js example above:

Node.js
export async function isChapaPaymentPaid(order) {
  const response = await fetch(
    CHAPA_API + "/payments/" + encodeURIComponent(order.reference) + "/verify",
    { headers: { "Authorization": "Bearer " + process.env.CHAPA_SECRET_KEY } },
  );
  const result = await response.json();
  const data = result.data || {};

  return result.status === "success"
    && data.status === "SUCCESS"                 // uppercase on v2
    && data.merchant_reference === order.reference
    && data.currency === "ETB"
    && data.amount === order.totalCents;         // cents, same as you sent
}

API v1. Call GET https://api.chapa.co/v1/transaction/verify/<tx_ref>. The payment status is in data.status and can be success, failed or pending. Chapa's webhook guide says to check status, amount, currency, tx_ref and mode before you confirm the order. In PHP:

PHP
<?php
function chapaVerify(string $txRef): array
{
    $curl = curl_init('https://api.chapa.co/v1/transaction/verify/' . rawurlencode($txRef));
    curl_setopt_array($curl, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('CHAPA_SECRET_KEY')],
    ]);
    return json_decode((string) curl_exec($curl), true) ?? [];
}

// Before you mark the order paid:
$result = chapaVerify($order['reference']);
$data = $result['data'] ?? [];

$isPaid = ($result['status'] ?? '') === 'success'
    && ($data['status'] ?? '') === 'success'
    && ($data['tx_ref'] ?? '') === $order['reference']
    && ($data['currency'] ?? '') === 'ETB'
    && (float) ($data['amount'] ?? 0) === (float) $order['total']
    && ($data['mode'] ?? '') === 'live'; // use 'test' while you are testing

If v1 answers "Payment not paid yet", the customer has not finished. Wait for the webhook and verify again.

Make fulfilment safe to repeat. If the order is already marked paid, do nothing. Your return page, callback and webhook may all trigger a check for the same payment.

Step 5: Set up webhooks

A webhook is a POST request that Chapa sends to your server when a payment changes state. It catches payments that finish after the customer closes the browser, such as a slow mobile money confirmation.

To turn it on, open your dashboard settings, go to the Webhooks tab and add your webhook URL and a secret. Store the same secret on your server as an environment variable, such as CHAPA_WEBHOOK_SECRET.

API v2. Chapa signs each webhook. The x-chapa-signature header holds a lowercase hex HMAC-SHA256 of the raw request body, made with your webhook secret. Chapa's v2 webhook docs warn that JSON.stringify(req.body) can change the bytes, so check the raw body with a constant-time comparison. This Express handler follows Chapa's example, then verifies the payment as in Step 4:

Node.js
import crypto from "node:crypto";
import express from "express";

const app = express();

function isValidChapaWebhook(rawBody, receivedSignature) {
  const secret = process.env.CHAPA_WEBHOOK_SECRET;
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return (
    typeof receivedSignature === "string" &&
    /^[a-f0-9]{64}$/i.test(receivedSignature) &&
    crypto.timingSafeEqual(
      Buffer.from(receivedSignature, "hex"),
      Buffer.from(expectedSignature, "hex")
    )
  );
}

// express.raw keeps the exact bytes Chapa signed.
app.post("/webhooks/chapa", express.raw({ type: "application/json" }), async (req, res) => {
  if (!isValidChapaWebhook(req.body, req.get("x-chapa-signature"))) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body.toString("utf8"));

  if (event.webhook_type === "payment" && event.event === "payment.success") {
    const order = await findOrderByReference(event.merchant_reference); // your code
    if (order && !order.paid && (await isChapaPaymentPaid(order))) {
      await markOrderPaid(order); // your code; must be safe to run twice
    }
  }

  return res.sendStatus(200);
});

The same signature check in PHP, from Chapa's v2 docs:

PHP
<?php
$secret = getenv('CHAPA_WEBHOOK_SECRET');
$rawBody = file_get_contents('php://input');
$receivedSignature = $_SERVER['HTTP_X_CHAPA_SIGNATURE'] ?? '';
$expectedSignature = hash_hmac('sha256', $rawBody, $secret);

if (!hash_equals($expectedSignature, $receivedSignature)) {
    http_response_code(401);
    exit;
}

$event = json_decode($rawBody, true, flags: JSON_THROW_ON_ERROR);
// Process $event idempotently: verify the payment (Step 4) before you deliver.
http_response_code(200);

API v1. Chapa sends two headers, chapa-signature and x-chapa-signature. Chapa's v1 webhook page says x-chapa-signature is an HMAC SHA256 of the event payload, and that a request is genuine if either header is valid. Events include charge.success, charge.refunded, charge.reversed and charge.failed/cancelled, and each payment event carries your tx_ref.

On v1, Chapa's webhook page calls the signing key "your secret key" in one place, and asks you to set a "secret hash" in the Webhooks tab in another. Send a test-mode payment and confirm which value matches the header before you go live.

Webhook rules for both versions:

  • Reply with 200 OK quickly. On v1, Chapa retries every 10 minutes, up to 10 times over 72 hours, until it gets a 200.
  • Expect duplicates. The same event can arrive more than once. Handling it twice must not deliver the order twice.
  • Expect events out of order. Chapa's v2 docs say to use updated_at so an older event never overwrites a newer state.
  • Verify before you deliver. Call the verify endpoint before giving value, even when the signature is valid.

Step 6: Test everything, then go live

In test mode, only Chapa's test cards and test phone numbers work. Chapa still sends webhooks in test mode. From Chapa's v1 testing cards, v1 testing mobile, v2 test cards and v2 test mobile pages:

TestAPI v2API v1
Test card4242 4242 4242 4242 succeeds. Use any future expiry date and any 3-digit CVV4200 0000 0000 0000, CVV 123, expiry 12/34
Failing cards4000 0000 0000 9995 (insufficient funds), 4000 0000 0000 0002 (declined)Not listed
Mobile money that succeeds251900000000telebirr, CBEBirr or COOPPay-ebirr: 0900123456, 0900112233 or 0900881111. M-Pesa: 0700123456
Mobile money that fails251911111111 (insufficient funds), 251922222222 (customer cancels), 251933333333 (times out)Any number not on Chapa's list returns a failed status
OTPSimulated, no SMS is sent12345 for the Awash Bank and Amole test numbers

Before you go live, test these cases:

  1. A successful payment marks the order paid exactly once.
  2. A failed or cancelled payment leaves the order unpaid, and the customer can try again.
  3. Opening the return URL without paying does not mark the order paid.
  4. Sending the same webhook twice does not deliver the order twice.
  5. A webhook with a wrong signature is rejected.
  6. A verify response with the wrong amount or currency is rejected.

To go live:

  1. Submit your business documents in the dashboard and wait for compliance approval.
  2. Switch the dashboard to Live mode and copy your live keys.
  3. Replace the test keys in your server's environment variables. The base URL stays the same: the key decides whether a payment is test or live.
  4. Check your webhook URL and secret in live mode.
  5. Make one small real payment and check that it appears in your Chapa dashboard and in your order system.

Chapa Fees and Settlement

Chapa's pricing page shows these rates for Ethiopia (checked 10 November 2026):

Payment typeChapa feeExample
Local (domestic) payment2.5% per successful transactionETB 25 on ETB 1,000
International payment1% per successful transactionUSD 1 on USD 100

The pricing page also says:

  • There are no setup fees, monthly fees or hidden fees.
  • The rate can change, including adjustments for sponsorship requests.
  • Businesses with large transaction volumes can get special pricing plans.

Chapa's merchant agreement adds these points:

  • Chapa takes its fee out of your money before it transfers the rest to you.
  • Fees do not include taxes. Any taxes on them are for the merchant to pay.
  • Chapa can change the fee with at least 30 business days' notice.
  • Chapa may ask for security, such as a deposit or a rolling reserve.
  • You must answer chargeback disputes with proof within 2 business days, and undisputed chargebacks are your liability.

Chapa's refund page says Chapa charges are non-refundable. When you refund a customer, the refund comes out of your available Chapa balance.

Settlement. The merchant agreement says Chapa settles collected money to your bank account at your preferred bank. Chapa's pricing page describes payouts as arriving "within hours, not days". The agreement treats settlement schedules as part of your contract, so confirm your exact schedule with Chapa before you promise payment dates to suppliers.

Split Payments

Split payments share one customer payment between you and someone else, such as a seller on your marketplace. Chapa sends each share to that party's own account.

API v1 (split payments page):

  1. Create a subaccount in the dashboard or with POST https://api.chapa.co/v1/subaccount. Send business_name, account_name, bank_code, account_number, split_type and split_value. Get the bank_code from GET https://api.chapa.co/v1/banks.
  2. Save the subaccount ID that Chapa returns.
  3. Add it when you initialize the payment, as "subaccounts": { "id": "..." }. You can override split_type and split_value for a single payment.

split_type is percentage or flat, and it sets your commission. To keep 3% of each payment, send percentage with 0.03. To keep ETB 25, send flat with 25, and the subaccount gets the rest. Subaccounts settle in ETB by default, and creating subaccounts through the API needs live mode.

API v2 (payment split rules): create a subaccount with POST https://api.chapa.global/v2/subaccounts, save the subaccount_reference, and pass a subaccounts array when you create the hosted payment. Each item has subaccount_reference, split_type and split_value.

You are responsible for your sellers. Chapa's v1 docs say knowing your vendors is your responsibility, and disputes or chargebacks on their sales are taken from your account. Split routing is also not escrow: if your app must hold money until delivery, get written approval for that money flow first. Our Chapa and Telebirr comparison explains why.

WooCommerce, Plugins and No-Code Options

WooCommerce. Chapa publishes a WooCommerce plugin on GitHub. Its README says to install it from Plugins → Add New or upload the zip, then turn it on under WooCommerce → Settings → Payments → Chapa and paste your secret and public keys. Version 1.0.3 is tested up to WordPress 6.9.1. The plugin's code calls Chapa's v1 API, so if your account is on v2, ask Chapa which plugin to use.

SDKs. Chapa's SDKs and plugins page lists packages for Node.js, NestJS, Laravel, PHP, Django, Python, Flutter, Go, Java, Kotlin, .NET and Rust. Chapa notes that some are made by its developer community, not by Chapa. The chapa.co developer hub lists the v2 SDKs. Check that an SDK matches your API version before you use it.

HTML checkout (v1). Chapa's HTML checkout is a plain form that posts to https://api.chapa.co/v1/hosted/pay with your public key. It suits a simple site, but you still need a server to verify payments with your secret key.

No code at all. On chapa.co, Payment Links let you create a payment link or invoice and share it on social media, email, SMS or chat, and Storefront gives you a simple online shop. Chapa describes both as needing no website or code. Chapa also offers QR payments, event ticketing and donation pages. These suit a small business, or a quick test before you build a full checkout.

Common Chapa Errors and How to Fix Them

These messages are copied from Chapa's v1 error codes, v1 error list and v2 error codes.

Error messageWhat it meansHow to fix it
Authorization requiredThe Authorization header is missingSend Authorization: Bearer plus your secret key, from your server
Invalid API Key or User doesn't existThe key is wrong, cut short or replacedCopy the key again from the dashboard and check for spaces
Transaction reference has been used beforeThe reference was already used. On v2: "Merchant reference has been used before"Create a new reference for every payment attempt
Incorrect header settings Please check if content-type is present and set to application/jsonThe Content-Type header is missingAdd Content-Type: application/json
Required Attribute: [ "validation.required"]A required field is missingSend amount, currency and tx_ref
Invalid currency, currency is not supportedThe currency is not acceptedUse ETB or USD on v1
The phone number must be a valid Ethiopian phone number.The phone number format is wrongOn v1, use 10 digits: 09xxxxxxxx or 07xxxxxxxx
Live secret keys can't be used to verify a test transactionTest and live keys are mixed. On v2: "API key environment does not match business environment."Use keys from the same mode as the payment
Payment not paid yetThe customer has not finished payingWait for the webhook, then verify again
Invalid transaction or Transaction not foundWrong reference, or a key from the other modeCheck the reference and which mode your key is for
Idempotency-Key header is required for payment operationsA v2 payment request has no Idempotency-KeySend an Idempotency-Key with every new payment
Retry failed. Please go back and re-initiate the payment again.Retries are not allowed for telebirr and CBE BirrStart a new payment with a new reference
Merchant's share of payment is not enough to cover transaction fee.Your split leaves too little to cover Chapa's feeLower the subaccount's share
Payments through API is disabled, please contact usAPI payments are turned off for your accountContact Chapa support

Other common mistakes:

  • Marking an order paid on the return URL without calling the verify endpoint.
  • Putting the secret key in a React, Flutter or mobile app.
  • Checking the v2 webhook signature against JSON.stringify(req.body) instead of the raw body.
  • Sending birr to v2, which expects cents. On v2, 100 is ETB 1, not ETB 100.
  • Using a reference longer than 20 characters on v2.
  • Sending an email longer than 50 characters or a first name longer than 35 characters. Chapa's error list gives these limits.

Chapa or Direct Telebirr?

Chapa already includes telebirr as a payment method. So the real question is whether you also need a direct Telebirr merchant integration with Ethio telecom.

  • Choose Chapa for a standard checkout with several payment methods through one integration. For a registered business with its documents ready, plan up to one week for a straightforward integration and testing. Chapa's compliance review can add time.
  • Choose direct Telebirr when you need a specific Telebirr product or a direct merchant relationship, and can plan for a longer onboarding. When approvals are still ahead, plan for more than three months end to end.

Our Telebirr and Chapa comparison covers requirements, timelines, settlement and escrow in more detail. For Ethio telecom's own process, see our Telebirr integration guide.

Chapa Integrated and Tested for a Fixed ETB Price

DreamTech connects Chapa to websites and apps for Ethiopian businesses. We set up checkout, confirm each payment and make sure orders update correctly.

We quote a fixed price in ETB after a short look at your website or app, whether you need Chapa alone or Chapa with direct Telebirr. Your written proposal confirms the checkout flow and the provider approvals you need. For live payments, you still need your own Chapa account and approved business documents.

See our payment gateway integration service or talk to our team about your checkout.

Frequently Asked Questions

How do I integrate Chapa payment in my website?

Create a Chapa account, copy your test secret key and call Chapa's initialize endpoint from your server to get a checkout URL. Send the customer to that URL, then verify the payment on your server before you mark the order paid. Add a webhook, test with Chapa's test cards and phone numbers, and switch to live keys once Chapa approves your business.

How much does Chapa charge per transaction?

Chapa's pricing page lists 2.5% per successful local payment and 1% per successful international payment in Ethiopia, with no setup or monthly fees (checked 10 November 2026). Chapa says the rates can change and that businesses with large volumes can ask for special pricing.

What documents do I need to open a Chapa merchant account?

Chapa asks for a business licence, TIN certificate, memorandum of association if applicable, proof of address, and the ID of the general manager (for a PLC) or the sole owner (for a sole proprietorship). You can use test mode before approval, but live payments start only after Chapa accepts your compliance documents.

Can I use Chapa without a business licence?

You can create an account and build your integration with test keys. To accept real payments, Chapa must approve your compliance documents, and its document list starts with a business licence and a TIN certificate.

Where do I find my Chapa API keys?

In the Chapa dashboard, open Settings and then API Keys. Test keys work right away. Live keys appear in live mode after Chapa approves your business. Keep the secret key on your server only.

What is the difference between Chapa API v1 and v2?

API v2 is Chapa's newer API at api.chapa.global. It takes amounts in cents, a merchant reference of up to 20 characters and an Idempotency-Key header. API v1 at api.chapa.co takes amounts in birr and a tx_ref. New accounts created from chapa.co use v2, and older dashboard.chapa.co accounts use v1. The start of your secret key tells you which one you have.

What is the difference between return_url and callback_url in Chapa?

On API v1, return_url is the page Chapa sends the customer to after payment. callback_url is a server address that Chapa calls with the transaction reference and status. Neither one proves payment by itself, so always call the verify endpoint before you deliver the order.

Does Chapa support telebirr and CBE Birr?

Yes. Chapa's supported payment methods page lists telebirr (ETB 1 to 75,000 per payment) and CBE Birr (ETB 1 to 150,000), along with M-Pesa, bank transfers, cards and PayPal (checked 10 November 2026).

How long does Chapa integration take?

For a registered business with its documents and app ready, plan up to one week for a straightforward checkout integration and testing. Chapa's compliance review can add time before you can take live payments.

How much does DreamTech charge to integrate Chapa?

We give a fixed price in ETB after a short look at your website or app. The written proposal confirms the checkout flow and the provider approvals you need.

Is this Chapa's official website?

No. This is a guide by DreamTech, a software company in Addis Ababa. Chapa's official website is chapa.co, and its developer documentation is at developer.chapa.co and docs.chapa.global.


Related resources

  • 5+Years of Experience
  • 500+Projects Delivered
  • 100%Built & Supported in Ethiopia
TechBehemoths Verification
GoodFirms Top Software Development Company 2025TechReviewer Top 100 Software Developers for Startups 2025

Ready to Start Your Project?

Book a free consultation to discuss requirements, constraints, delivery options, and the information needed for a scoped proposal.