Developers

ETHIOVERIFY_BASE_URL=https://your-host/v1   # self-hosted; locally: http://localhost:8000/v1
ETHIOVERIFY_API_KEY=evk_your_key_here

curl -X POST "$ETHIOVERIFY_BASE_URL/verify" \
  -H "X-API-Key: $ETHIOVERIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reference": "DG28H170UI", "expected_amount": 1500.00}'

{
  "outcome": "verified",
  "transaction": {
    "provider": "telebirr", "verified": true, "status": "SUCCESS",
    "reference": "DG28H170UI", "receipt_number": "DG28H170UI",
    "amount": 1500.0, "currency": "ETB",
    "sender":   {"name": "Abebe Kebede", "account": "2519****1234"},
    "receiver": {"name": "Almaz Mart",  "account": "2519****9876"},
    "timestamp": "2026-06-28T15:04:12", "metadata": {}
  },
  "fraud": {"risk_score": 0, "risk_level": "LOW", "signals": ["…"]},
  "settlement_match": true,
  "verification_count": 1,
  "latency_ms": 1412.7,
  "request_id": "…"
}

Base URL https://your-host/v1 · Live interactive docs at /docs (Swagger) · Machine-readable spec at /openapi.json

Authentication

Method	Header	For
API key	X-API-Key: evk_…	server-to-server integrations
JWT bearer	Authorization: Bearer … (from POST /v1/auth/login)	web sessions, 60-min expiry

Every response carries X-Request-ID for tracing; rate-limited endpoints add X-RateLimit-Remaining. Send X-Correlation-ID to stitch our logs to yours.

Endpoints

Verify one payment. Body: reference (required), provider, expected_amount, account_suffix, receipt_url. Returns the full result synchronously (see Getting started).

Body: {"items": [ …up to 100 verify requests… ]}. Items run concurrently (10 at a time); returns an array of results in the same order.

A stored canonical transaction by internal id.

Your verification attempts: outcome, risk score/level, settlement match, IP, device, latency, timestamp. Admin and auditor roles see all merchants.

Aggregates: totals, verified/failed, fraud-flagged, per-provider counts, average latency.

Send a phone-verification code (no auth): {"phone": "09…"}. Required once before signup; the code is delivered over Telegram and expires in ~10 min.

Self-service signup (no auth). Body: business_name, phone, otp_code (from /auth/otp/request), password; email optional. Returns merchant_id, first API key (once) and your webhook secret.

Exchange {"phone","password"} for a 60-min JWT bearer token (for web sessions; server-to-server integrations use the API key instead).

Issue an additional key. The full key appears only in this response.

Register / list receiving accounts: {"provider": "telebirr", "account_number": "2519…", "account_name": "…"}. Once registered, every result includes settlement_match and mismatches raise a fraud signal.

Set your callback: {"url": "https://…", "events": ["transaction_verified", "fraud_detected"]}. Omit events to subscribe to all.

Provider catalog with reference formats; live health probes each provider's receipt endpoint concurrently.

Liveness probe — no auth.

Outcomes

outcome	Meaning
verified	Provider record confirms the payment
not_found	No receipt exists for that reference
rejected_fraud	Receipt exists but risk scored CRITICAL
parse_error	Receipt retrieved but its layout changed — report it to us
provider_error	Provider unreachable; safe to retry

Errors

All errors share one envelope: {"error": "…", "code": "…", "request_id": "…", "context": {}}

HTTP	code
401	authentication_failed
403	forbidden (role lacks scope)
404	receipt_not_found · provider_not_found
422	validation_error · receipt_parse_error · provider_detection_failed
429	rate_limited — default 120 requests/min per account, raisable per merchant
502 / 503	provider_unavailable · circuit_open (provider temporarily disabled after repeated failures — retry after ~30 s)

Roles & scopes

Role	Can
merchant	verify, read own history/stats, manage keys, webhook, settlement accounts
developer	verify + read own history/stats
auditor	read-only across the platform, incl. audit trail
admin	everything, incl. the operator panel

Python SDK — ethiopayverify

pip install ethiopayverify

# Synchronous
from ethiopayverify import VerifyClient

client = VerifyClient(api_key="evk_...", base_url="https://your-host/v1")

result = client.verify(provider="telebirr", reference="DG28H170UI",
                       expected_amount=1500.00)
if result.verified and result.fraud.risk_level in ("LOW", "MEDIUM"):
    ship_the_order(result.transaction.reference)

# CBE needs the account suffix
result = client.verify(provider="cbe", reference="FT25211G11JQ",
                       account_suffix="21827223")

# Bulk
results = client.bulk_verify([
    {"reference": "DG28H170UI"},
    {"reference": "FT25211G11JQ", "provider": "cbe", "account_suffix": "21827223"},
])

# Async (httpx)
from ethiopayverify import AsyncVerifyClient

async with AsyncVerifyClient(api_key="evk_...", base_url="https://your-host/v1") as client:
    result = await client.verify(reference="DG28H170UI")

Errors raise typed exceptions: AuthenticationError (401), RateLimitError (429), ApiError (everything else, with .code and .request_id).

Plain REST — Node.js

const res = await fetch(process.env.ETHIOVERIFY_BASE_URL + "/verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.ETHIOVERIFY_API_KEY,
  },
  body: JSON.stringify({ reference: "DG28H170UI", expected_amount: 1500 }),
  signal: AbortSignal.timeout(60000),
});
const result = await res.json();
if (result.outcome === "verified") { /* fulfil the order */ }

Plain REST — PHP

$ch = curl_init(getenv("ETHIOVERIFY_BASE_URL") . "/verify");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 60,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: " . getenv("ETHIOVERIFY_API_KEY"),
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "reference" => "DG28H170UI",
    "expected_amount" => 1500.00,
  ]),
]);
$result = json_decode(curl_exec($ch), true);
if (($result["outcome"] ?? "") === "verified") { /* fulfil the order */ }

Webhook receiver — Node.js

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post("/hooks/ethioverify",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const raw = req.body;                          // Buffer — keep it raw
    const signature = req.header("X-EthioVerify-Signature");
    const expected = crypto
      .createHmac("sha256", process.env.ETHIOVERIFY_WEBHOOK_SECRET)
      .update(raw)
      .digest("hex");

    if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
      return res.sendStatus(401);
    }

    const { event, data } = JSON.parse(raw.toString("utf8"));
    if (event === "fraud_detected") alertTheTeam(data);

    res.sendStatus(204);                           // ack fast, work async
  });

Command line

# the ethioverify CLI ships with the platform
ethioverify verify DG28H170UI
ethioverify verify FT25211G11JQ --provider cbe --account-suffix 21827223
ethioverify status        # probe all provider endpoints
ethioverify history
ethioverify stats