EthioPay API
Create a checkout session on your server, send the customer to the hosted payment page, and get a signed webhook when the transfer is verified. All amounts are in ETB.
Need keys? Create an account then open Developers.
Authenticate server-side requests with your secret key in the Authorization: Bearer header. Never expose a secret key in browser code. Publishable keys are available for
client-side configuration endpoints.
Test keys start with sk_test_; live keys start with sk_live_. Test sessions can be completed instantly
with the simulation endpoint.
All 12 methods are verified against the issuing bank by Cheki. Use the provider code when saving a receiving account or verifying a transfer.
Commercial Bank of Ethiopia
CBE · cbe
Telebirr
TELEBIRR · telebirr
Bank of Abyssinia
BOA · boa
Dashen Bank
DASHEN · dashen
Awash Bank
AWASH · awash
M-Pesa Ethiopia
MPESA · mpesa
CBE Birr
CBE_BIRR · cbebirr
eBirr
EBIRR · ebirr
Siinqee Bank
SIINQEE · siinqee
Wegagen Bank
WEGAGEN · wegagen
Bunna International Bank
BUNNA · bunna
ZamZam Bank
ZAMZAM · zamzam
POST /v1/checkout/sessions — amount is a number in ETB. You can also pass product_id instead of amount and description.
curl -X POST https://your-domain/v1/checkout/sessions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"amount": 199.00,
"description": "Order #1042",
"success_url": "https://yoursite.com/thanks",
"metadata": { "order_id": "1042" }
}' {
"id": "cs_test_m8x2q1...",
"object": "checkout.session",
"amount": 199,
"currency": "ETB",
"status": "PENDING",
"url": "https://your-domain/pay/cs_test_m8x2q1...",
"payment_methods": [
{ "provider": "CBE", "account_number": "1000....", "account_holder_name": "Acme PLC" }
],
"created": 1763640000000
} Redirect the customer to url. The hosted page shows
the merchant's receiving accounts and verifies the bank receipt automatically.
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/checkout/sessions | Create a payment session |
| GET | /v1/checkout/sessions | List your sessions |
| GET | /v1/checkout/sessions/:id | Retrieve a session |
| GET | /v1/checkout/sessions/:id/public | Public status for the payment page |
| POST | /v1/checkout/sessions/:id/simulate | Mark a test session paid |
| GET | /v1/products | List products |
| POST | /v1/products | Create a product |
| POST | /v1/webhooks/test | Send a test webhook |
curl -X POST https://your-domain/v1/checkout/sessions/cs_test_.../simulate \ -H "Authorization: Bearer sk_test_..."
This only works with a test key and a test session. It marks the session paid and fires the same webhook a real verification would.
Configure an endpoint in the dashboard. Every event carries an Ethiobank-Signature header of the form t=<timestamp>,v1=<hmac>, where the HMAC is
SHA-256 over timestamp.rawBody using your webhook
secret. Always verify before trusting the payload.
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(
header.split(",").map((p) => p.split("=")),
);
const expected = createHmac("sha256", secret)
.update(parts.t + "." + rawBody)
.digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1 || "");
return a.length === b.length && timingSafeEqual(a, b);
}
app.post("/webhooks/ethiopay", express.raw({ type: "application/json" }), (req, res) => {
if (!verify(req.body.toString(), req.headers["ethiobank-signature"], process.env.ETHIOPAY_WEBHOOK_SECRET)) {
return res.status(400).send("Invalid signature");
}
const event = JSON.parse(req.body.toString());
if (event.type === "checkout.session.paid") {
// fulfil the order
}
res.sendStatus(200);
});A real payment is checked against the issuing bank through the same verification logic used by
Cheki. The hosted checkout and the method tester show the bank's receipt detail: amount, currency,
sender and receiver names/accounts, reference, date, bank, transaction status, and the bank page that
produced the result. Paid webhooks include the same data under data.receipt.
state is verified only
when the bank explicitly confirmed the receipt. Decoded QR codes, pasted text, local reads and failed
checks are reported separately and never presented as bank-confirmed payment.
A checkout can be verified from the transaction number, a receipt link, or an uploaded
receipt image (its QR code is read and the reference extracted) — prefixes such as FT (CBE) and DET (Telebirr) identify the bank automatically. The receipt's amount, receiver name, masked
account pattern and date are all checked. A reference is recorded globally on first success,
so a second attempt returns 409 with alreadyPaid: true.
Errors use a consistent shape with an HTTP status code: {"error": {"code": "invalid_api_key", "message": "..."}}
Bank receipt services are intermittent. When a bank cannot be reached, verification answers 503 with a Retry-After header and retryable: true. This means not checked, not rejected: nothing was charged and no one-time reference
lock was written. Wait and retry the same transaction number. A definite bank answer — no
matching receipt, wrong amount, wrong receiving account — stays 400, and an already-used reference is 409 with alreadyPaid: true.