API Documentation

Integrate VerPay into your application.

Introduction

Welcome to the definitive open-source verification engine for Ethiopian fintech. This API allows businesses and developers to programmatically verify the authenticity of customer payments, completely automating checkout flows and preventing fraud from fake receipt generators. Built with extreme reliability in mind, the engine officially supports core providers with 99.9% uptime.

Getting Started

1. Database Setup (Supabase)

  1. Create a new project at Supabase.
  2. Navigate to the SQL Editor in your Supabase dashboard.
  3. Copy the contents of supabase/migrations/001_init.sql and run it to create the api_keys and usage_logs tables.
  4. Go to Project Settings > API to find your URL and Service Role Key.

2. Local Setup

git clone https://github.com/RobiAbebe/payment-verifier.git
cd payment-verifier
npm install
cp .env.example .env

Edit the .env file with your actual keys:

SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
ADMIN_KEY=your-secure-admin-password
MISTRAL_API_KEY=your-mistral-ai-key
# TELEBIRR_PROXY_URL=http://your-ethiopian-proxy.com:8080
PORT=3001

AI Image Verification

Have a screenshot instead of text? Send the base64 image! The system automatically detects QR codes for precision, uses Mistral AI for OCR data extraction, and instantly validates the findings directly with the bank!

POST
/verify-image

Request Body

{
  "image": "base64_encoded_string_here...",
  "autoVerify": true
}

Provider Endpoints

Send your verification requests directly to the standalone provider endpoints below.

CBE

The modern JSON-based CBE API verification. This is significantly faster than the legacy endpoint and does not require a suffix parameter, making it ideal for modern application integrations.

POST /verify-cbe
Reference Format: Starts with v2- followed by a long alphanumeric string. Case-sensitive.
Request Payload: 
{
  "reference": "v2-hfHCxz6TmMYrTUfWldzb"
}

Telebirr

Verification for Ethio Telecom's massive mobile money service. This endpoint is extremely robust but requires Ethiopian IP addresses to function without proxy interference.

POST /verify-telebirr
Reference Format: Exactly 10 uppercase alphanumeric characters (e.g., AG3HF92K10).
Request Payload: 
{
  "reference": "AG3HF92K10"
}

Admin Endpoints

To generate or retrieve API keys, use the /admin/api-keys endpoints passing your x-admin-key header (which corresponds to your ADMIN_KEY env variable).

POST
/admin/api-keys

Generate a new secure API key for a client.

curl -X POST https://api.yourdomain.com/admin/api-keys \
  -H "x-admin-key: your-secure-admin-password" \
  -H "Content-Type: application/json" \
  -d '{"owner": "My Production App"}'
GET
/admin/api-keys

Retrieve a list of all active generated API keys to monitor usage.

curl -X GET https://api.yourdomain.com/admin/api-keys \
  -H "x-admin-key: your-secure-admin-password"

Vercel Deployment

This project is configured out-of-the-box for serverless deployment on Vercel.

  1. Install the Vercel CLI: npm i -g vercel
  2. Run vercel and link your project.
  3. Add your environment variables using vercel env add.
  4. Deploy to production: vercel --prod

Troubleshooting

  • 1 Telebirr Proxy Errors

    Telebirr blocks non-Ethiopian IPs. If you are developing locally, you might need to comment out the proxy variables in .env. If you deploy outside Ethiopia (e.g., Vercel US), you will need a working residential Ethiopian proxy to ping their APIs.

  • 2 Mistral API Errors

    Ensure your account is active and you are passing a clean Base64 string (without the data:image/jpeg;base64, prefix) if calling the API directly. The built-in frontend handles this automatically.