Integrate Ethiopian Transaction Verification

Create an API Key

1. 1

   Sign in

   Open /login and authenticate with your account.
2. 2

   Create a key

   Create a key and save the full VERIFY_BANK_ET_your_key_here secret. It is shown once.Open API Keys
3. 3

   Set permissions

   For verification flows, include verification:write to submit requests and verification:read to poll, stream, or read history.
4. 4

   Send the header

   Add x-api-key to every API request. Add Idempotency-Key to safely retry submissions.

Register one public HTTPS URL. Verify.et sends verification.completed when a check finishes.

1. 1

   Add the endpoint

   Open Webhooks, add your URL, and copy the whsec_ secret. It is shown once.Open Webhooks
2. 2

   Send a test

   Click Send test. A 2xx response makes the endpoint active. Sign timestamp, a period, and the raw body with HMAC-SHA256, then reply 204.
3. 3

   Submit a verification

   Call POST /api/verify with your API key. On 202, store requestId. The webhook brings the result.

curl -X POST \
  "https://verify.et/api/verify" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VERIFY_ET_API_KEY" \
  -H "Idempotency-Key: checkout-1042" \
  -d '{
    "bank": "telebirr",
    "transactionNumber": "TELE123456"
  }'

Use the Production Endpoint

Verify.ET is provided through the hosted verify.et domain. These examples intentionally use the same base URL your production integration uses.

VERIFY_ET_BASE_URL=https://verify.et
VERIFY_ET_API_KEY=VERIFY_BANK_ET_your_key_here

Submit Your First Verification

POST /api/verify accepts explicit bank payloads and universal smart-router payloads. Leave webhookUrl out. An active dashboard endpoint already receives the result. Identifier fields may include full SMS text or supported receipt URLs; the server best-effort normalizes them when confident (explicit bank is never re-routed). Prefer clean fields in production. waitMs asks the API to wait briefly for a terminal result, but the server caps the wait time per bank. A photo of the receipt uses the steps in Verify from a receipt image.

curl -X POST \
  "https://verify.et/api/verify?waitMs=5000" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VERIFY_ET_API_KEY" \
  -H "Idempotency-Key: verify-demo-001" \
  -d '{
    "bank": "cbe",
    "reference": "fHCxyExampleRcpt1"
  }'

{
  "success": true,
  "message": "Verification queued.",
  "data": [],
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "statusUrl": "/api/verify/550e8400-e29b-41d4-a716-446655440000",
  "estimatedWaitMs": 5000,
  "verification": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "bank": "cbe",
    "processingStatus": "queued",
    "status": "pending",
    "verified": false
  },
  "links": {
    "statusUrl": "/api/verify/550e8400-e29b-41d4-a716-446655440000",
    "pollAfterMs": 1500
  }
}

Send a photo on the same POST /api/verify request. Put the file in one part named image.

1. 1

   Turn it on

   Image Processing starts off. The billing owner turns on the switch.Enable Image Processing
2. 2

   Add image credits

   One accepted photo spends one image credit. Packs start at 1,000 credits for 500 ETB.Top up image credits
3. 3

   Send the photo

   Post the file with x-api-key and Idempotency-Key. Use JPEG, PNG, or WebP, up to 8 MB. 200 is finished and 202 is queued. Read imageProcessing on the response.

curl -X POST \
  "https://verify.et/api/verify?waitMs=5000" \
  -H "x-api-key: $VERIFY_ET_API_KEY" \
  -H "Idempotency-Key: receipt-order-123" \
  -F "[email protected];type=image/jpeg" \
  -F "bank=cbe" \
  -F "reference=fHCxyExampleRcpt1"

{
  "success": true,
  "message": "Verification queued.",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "imageProcessing": {
    "attemptId": "img_018f2c4e-9b1a-7d33-a6c0-e5b4c8d21a90",
    "method": "qr",
    "chargedCredits": 1
  },
  "verification": {
    "processingStatus": "queued",
    "status": "pending",
    "verified": false
  },
  "links": {
    "statusUrl": "/api/verify/550e8400-e29b-41d4-a716-446655440000",
    "pollAfterMs": 1500
  }
}

Use this when a page should show progress. Poll GET /api/verify/:requestId until processingStatus is completed or failed, for up to 125 seconds. Do not submit the same receipt again while that request is in flight. Keep the webhook you registered above so the result still arrives if the customer leaves.

const baseUrl = process.env.VERIFY_ET_BASE_URL ?? "https://verify.et";
const requestId = process.env.VERIFY_ET_REQUEST_ID!;
const statusUrl = `${baseUrl}/api/verify/${encodeURIComponent(requestId)}`;

const deadline = Date.now() + 125_000;
while (Date.now() < deadline) {
  const response = await fetch(statusUrl, {
    headers: { "x-api-key": process.env.VERIFY_ET_API_KEY! },
  });
  const body = await response.json();
  const status = body.data?.processingStatus;

  if (status === "completed" || status === "failed") {
    return body.data;
  }

  await new Promise((resolve) => setTimeout(resolve, body.links?.pollAfterMs ?? 1500));
}

throw new Error("Verification did not finish within 125 seconds.");

VERIFY_ET_BASE_URL="https://verify.et"
VERIFY_ET_REQUEST_ID="replace-with-the-request-id-from-submit"

curl -N \
  -H "Accept: text/event-stream" \
  -H "x-api-key: $VERIFY_ET_API_KEY" \
  "$VERIFY_ET_BASE_URL/api/verify/$VERIFY_ET_REQUEST_ID/events"

Bank Fields

Use universal fields when you want the router to detect the provider. Use explicit bank fields when your checkout already knows the bank or wallet.

Explicit Bank Payloads

Field	Required	Description
cbe	Required	Send the Receipt ID in reference or referenceNumber. No suffix. A full mbreciept.cbe.com.et link is accepted. Older FT references still need an 8-digit suffix.
boa	Required	Use referenceNumber/reference plus accountSuffix/suffix exactly 5 digits.
telebirr	Required	Use transactionNumber or reference.
mpesa	Required	Use transactionNumber or reference. Receipt URLs and supported SMS text can be parsed.
cbebirr	Required	Use receiptNumber/reference plus phone/phoneNumber.
dashen / awash / siinqee	Required	Use referenceNumber or reference.
kaafiebirr	Required	Use referenceNumber/reference. phone/phoneNumber is optional.
coopayebirr	Required	Use referenceNumber/reference with the SMS receipt link or its token (not the SMS Ref). phone/phoneNumber is optional.

CBESend the Receipt ID in reference. No suffix. referenceNumber is the same field.

curl -X POST \
  "https://verify.et/api/verify?waitMs=5000" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VERIFY_ET_API_KEY" \
  -d '{
    "bank": "cbe",
    "reference": "fHCxyExampleRcpt1"
  }'

Bank of AbyssiniaRequires referenceNumber and a 5-digit accountSuffix.

curl -X POST \
  "https://verify.et/api/verify?waitMs=5000" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VERIFY_ET_API_KEY" \
  -d '{
    "bank": "boa",
    "referenceNumber": "BOA123456789",
    "accountSuffix": "12345"
  }'

TelebirrRequires transactionNumber or reference.

curl -X POST \
  "https://verify.et/api/verify?waitMs=5000" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VERIFY_ET_API_KEY" \
  -d '{
    "bank": "telebirr",
    "transactionNumber": "TELE123456"
  }'

MPESAAccepts a transaction number, reference, supported receipt URL, or supported SMS text.

curl -X POST \
  "https://verify.et/api/verify?waitMs=5000" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VERIFY_ET_API_KEY" \
  -d '{
    "bank": "mpesa",
    "transactionNumber": "MPESA123456"
  }'

CBE BirrRequires receiptNumber plus phone or phoneNumber.

curl -X POST \
  "https://verify.et/api/verify?waitMs=5000" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VERIFY_ET_API_KEY" \
  -d '{
    "bank": "cbebirr",
    "receiptNumber": "CBE-BIRR-123456",
    "phone": "0911223344"
  }'

DashenRequires referenceNumber or reference.

curl -X POST \
  "https://verify.et/api/verify?waitMs=5000" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VERIFY_ET_API_KEY" \
  -d '{
    "bank": "dashen",
    "referenceNumber": "DASHEN123456"
  }'

AwashRequires referenceNumber or reference.

curl -X POST \
  "https://verify.et/api/verify?waitMs=5000" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VERIFY_ET_API_KEY" \
  -d '{
    "bank": "awash",
    "referenceNumber": "AWASH123456"
  }'

SiinqeeRequires referenceNumber or reference.

curl -X POST \
  "https://verify.et/api/verify?waitMs=5000" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VERIFY_ET_API_KEY" \
  -d '{
    "bank": "siinqee",
    "referenceNumber": "SIINQEE123456"
  }'

Kaafi EbirrRequires referenceNumber or reference.phone is optional.

curl -X POST \
  "https://verify.et/api/verify?waitMs=5000" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VERIFY_ET_API_KEY" \
  -d '{
    "bank": "kaafiebirr",
    "referenceNumber": "https://receipt.ebirr.com/kaafimf/ilgi8ctn1Tr6vhw_so79kw"
  }'

Coopay EbirrRequires referenceNumber or reference set to the receipt link from the SMS, or its case-sensitive token. The SMS Ref number alone cannot be verified. phone is optional.

curl -X POST \
  "https://verify.et/api/verify?waitMs=5000" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VERIFY_ET_API_KEY" \
  -d '{
    "bank": "coopayebirr",
    "referenceNumber": "https://receipt.ebirr.com/coopay/T3stCoopayTok3n_AbCd1Q"
  }'

The API reference includes the webhook payload, signature headers, and management routes. The REST examples page has copyable receivers for Node.js, Python, and PHP.