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 method | Minimum per payment | Maximum per payment |
|---|---|---|
| telebirr | ETB 1 | ETB 75,000 |
| CBEBirr | ETB 1 | ETB 150,000 |
| M-Pesa | ETB 20 | ETB 75,000 |
| AwashBirr | ETB 1 | ETB 600,000 |
| Coopay-Ebirr | ETB 1 | Unlimited |
| Amole | ETB 1 | Unlimited |
| CBE Bank Transfer | ETB 1 | ETB 9,999,999 |
| COOP | ETB 1 | ETB 1,000,000 |
| Awash Bank, Enat Bank, Amhara Bank | ETB 1 | Unlimited |
| Credit or debit card | ETB 10 | ETB 500,000 |
| PayPal | ETB 10 | ETB 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 website: chapa.co
- Create a new account: dashboard.chapa.global/signup, where Chapa's "Start Now" button goes
- Sign in to an existing account: dashboard.chapa.co, where Chapa's "Sign in" link goes
- Developer docs for API v2: docs.chapa.global
- Developer docs for API v1: developer.chapa.co
- Pricing: chapa.co/pricing
- Help Center: support.chapa.co
- API status: status.chapa.co
- Contact Chapa: chapa.co/contact
- SDKs and plugins: Chapa on GitHub
- Developer community: Chapa developers on Telegram
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:
- Your server asks Chapa to start a payment and gets a
checkout_url. - You send the customer to that URL, and they pay on Chapa's page.
- Chapa sends the customer back to your
return_urland notifies your server. - 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.
| What | API v2 | API v1 |
|---|---|---|
| Where the account lives | dashboard.chapa.global, where chapa.co's "Start Now" button goes | dashboard.chapa.co |
| Secret key starts with | CHAPA_TEST_ in test mode, CHAPA_LIVE_ in live mode | CHASECK_TEST- in test mode, CHASECK- in live mode |
| Base URL | https://api.chapa.global/v2 | https://api.chapa.co/v1 |
| Start a payment | POST /v2/payments/hosted | POST /v1/transaction/initialize |
| Verify a payment | GET /v2/payments/{reference}/verify | GET /v1/transaction/verify/{tx_ref} |
| Amount format | Integer cents: 10000 is ETB 100 | Birr: "100" is ETB 100 |
| Your order reference | merchant_reference, at most 20 characters | tx_ref |
| Extra header | Idempotency-Key | None |
| Docs | docs.chapa.global | developer.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
- Create your Chapa account and confirm your email address.
- Open Settings, then API Keys. On v1, click your initials at the top right, choose Settings and open the API tab.
- Make sure the dashboard is in Test mode. Test mode moves no real money.
- 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 -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 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 --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
// 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:
{
"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_urlwith a GET request containingtrx_ref,ref_idandstatus. - 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:
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
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 testingIf 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:
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
$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_atso 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:
| Test | API v2 | API v1 |
|---|---|---|
| Test card | 4242 4242 4242 4242 succeeds. Use any future expiry date and any 3-digit CVV | 4200 0000 0000 0000, CVV 123, expiry 12/34 |
| Failing cards | 4000 0000 0000 9995 (insufficient funds), 4000 0000 0000 0002 (declined) | Not listed |
| Mobile money that succeeds | 251900000000 | telebirr, CBEBirr or COOPPay-ebirr: 0900123456, 0900112233 or 0900881111. M-Pesa: 0700123456 |
| Mobile money that fails | 251911111111 (insufficient funds), 251922222222 (customer cancels), 251933333333 (times out) | Any number not on Chapa's list returns a failed status |
| OTP | Simulated, no SMS is sent | 12345 for the Awash Bank and Amole test numbers |
Before you go live, test these cases:
- A successful payment marks the order paid exactly once.
- A failed or cancelled payment leaves the order unpaid, and the customer can try again.
- Opening the return URL without paying does not mark the order paid.
- Sending the same webhook twice does not deliver the order twice.
- A webhook with a wrong signature is rejected.
- A verify response with the wrong amount or currency is rejected.
To go live:
- Submit your business documents in the dashboard and wait for compliance approval.
- Switch the dashboard to Live mode and copy your live keys.
- 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.
- Check your webhook URL and secret in live mode.
- 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 type | Chapa fee | Example |
|---|---|---|
| Local (domestic) payment | 2.5% per successful transaction | ETB 25 on ETB 1,000 |
| International payment | 1% per successful transaction | USD 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):
- Create a subaccount in the dashboard or with
POST https://api.chapa.co/v1/subaccount. Sendbusiness_name,account_name,bank_code,account_number,split_typeandsplit_value. Get thebank_codefromGET https://api.chapa.co/v1/banks. - Save the subaccount ID that Chapa returns.
- Add it when you initialize the payment, as
"subaccounts": { "id": "..." }. You can overridesplit_typeandsplit_valuefor 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 message | What it means | How to fix it |
|---|---|---|
| Authorization required | The Authorization header is missing | Send Authorization: Bearer plus your secret key, from your server |
| Invalid API Key or User doesn't exist | The key is wrong, cut short or replaced | Copy the key again from the dashboard and check for spaces |
| Transaction reference has been used before | The 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/json | The Content-Type header is missing | Add Content-Type: application/json |
| Required Attribute: [ "validation.required"] | A required field is missing | Send amount, currency and tx_ref |
| Invalid currency, currency is not supported | The currency is not accepted | Use ETB or USD on v1 |
| The phone number must be a valid Ethiopian phone number. | The phone number format is wrong | On v1, use 10 digits: 09xxxxxxxx or 07xxxxxxxx |
| Live secret keys can't be used to verify a test transaction | Test 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 yet | The customer has not finished paying | Wait for the webhook, then verify again |
| Invalid transaction or Transaction not found | Wrong reference, or a key from the other mode | Check the reference and which mode your key is for |
| Idempotency-Key header is required for payment operations | A v2 payment request has no Idempotency-Key | Send 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 Birr | Start 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 fee | Lower the subaccount's share |
| Payments through API is disabled, please contact us | API payments are turned off for your account | Contact 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,
100is 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

