EthioVerify API Reference

Overview

EthioVerify provides a unified API for verifying transaction information from supported Ethiopian financial providers. Developers can send a bank identifier and transaction reference and receive a normalized JSON response.

Authentication

Authenticate requests using your EthioVerify API credential in the HTTP header as a x-api-key .

x-api-key:  ev_live_YOUR_SECRET_KEY

Verify a single transaction by providing the supported bank identifier and transaction reference.

curl -X POST https://recieptcheck.oppnestapp.com/api/v1/verify \
  -H "x-api-key: ev_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bank": "cbe",
    "reference": "FT1234567890"
  }'

Request Schema

JSON body parameters required by the verification endpoint.

Response Structure

Successful requests return a normalized response containing the provider, verification result, and transaction information when available.

{
  "success": true,
  "request_id": "901284fa921b901284fa921b",
  "data": {
    "bank": "cbe",
    "verification_result": "verified",
    "transaction": {
      "reference": "FT1234567890",
      "status": "completed",
      "amount": 140.00,
      "currency": "ETB",
      "date": "18-06-2026",
      "description": "description",
      "sender": {
        "name": "Example Sender",
        "account": "1********1234"
      },
      "receiver": {
        "name": "Example Receiver",
        "account": "1********4321"
      }
    }
  },
  "error": null
}

Error Codes & Handling

When success is false , inspect error.code to determine why the request failed and how your application should handle it.

{
  "success": false,
  "request_id": "1234567-2feb-42ab-b442-123456789",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or revoked API credential."
  }
}

Supported Banks & Inputs

EthioVerify currently supports transaction verification for the following providers.

Code Examples

Example requests using common development environments.

curl -X POST https://recieptcheck.oppnestapp.com/api/v1/verify \
  -H "x-api-key: ev_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bank": "cbe",
    "verificationInput": "FT1234567890"
  }'

// Node.js 18+

const response = await fetch(
  'https://recieptcheck.oppnestapp.com/api/v1/verify',
  {
    method: 'POST',

    headers: {
      'x-api-key':
        process.env.ETHIOVERIFY_API_KEY,

      'Content-Type':
        'application/json'
    },

    body: JSON.stringify({
      bank: 'cbe',
      verificationInput: 'FT1234567890'
    })
  }
);

const result = await response.json();

if (
  result.success &&
  result.data?.verification_result === 'verified'
) {
  console.log(
    'Amount:',
    result.data.transaction.amount
  );
}

import os
import requests

url = "https://recieptcheck.oppnestapp.com/api/v1/verify"

headers = {
    "x-api-key":
        f"os.environ.get('ETHIOVERIFY_API_KEY')",

    "Content-Type":
        "application/json"
}

payload = {
    "bank": "cbe",
    "reference":
        "FT1234567890"
}

response = requests.post(
    url,
    json=payload,
    headers=headers
)

data = response.json()

if (
    data.get("success")
    and
    data.get("data", {}).get(
        "verification_result"
    ) == "verified"
):
    print(
        data["data"]["transaction"]["amount"]
    )

Rate Limits

API requests are subject to the limits associated with your account plan.

Request ID & Debugging

API responses include a request_id that can be used to trace the request.