EthioPay API

Accept bank transfers with one 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.

Authentication

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.

Supported receiving methods

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

Create a checkout session

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.

Endpoints

MethodPathPurpose
POST/v1/checkout/sessionsCreate a payment session
GET/v1/checkout/sessionsList your sessions
GET/v1/checkout/sessions/:idRetrieve a session
GET/v1/checkout/sessions/:id/publicPublic status for the payment page
POST/v1/checkout/sessions/:id/simulateMark a test session paid
GET/v1/productsList products
POST/v1/productsCreate a product
POST/v1/webhooks/testSend a test webhook

Test mode

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.

Webhooks

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);
});

Receipt detail from verification

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

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.