VERIFIABLE: Self-Hosted Payment Verification Engine & SDK

Verifiable consists of two deliverables: a developer-facing SDK integrated into your application backend, and a private verification engine deployed inside your infrastructure.

Customer Browser / Mobile App
       │
       │ [1] Pastes reference or SMS proof
       ▼
Your Application Backend (Next.js / Express / Laravel / Django / Spring)
       │
       │ [2] Private HTTP call with expectedAmount: order.totalMinor
       ▼
Verifiable Engine (Self-hosted on your VPS / Docker)
       │
       ├─► Check 1: Input Extractor (Telebirr 10-char / CBE FT...)
       ├─► Check 2: Direct Provider Lookup (HTTPS to telebirr / CBE)
       ├─► Check 3: Check Completed Status
       ├─► Check 4: Compare Amount & Receiver Profile
       └─► Check 5: Atomic Replay Protection (Locks reference hash)
       │
       ▼
Returns Standardized Outcome:
  • verified             ──► Mark order paid in application database
  • already_used         ──► Reject (Fraud / Replay reuse attempt)
  • amount_mismatch      ──► Reject or request the difference
  • receiver_mismatch    ──► Reject (Payment made to wrong account)
  • not_completed        ──► Keep order pending; ask customer to wait
  • not_found            ──► Reject (Confirmed absent on provider)
  • provider_unavailable ──► Safe retry; network/provider timeout

Every request executes through these steps in strict order. Claiming occurs only at the very end, so a customer who inputs the wrong amount or submits an incomplete payment does not burn a valid receipt.

The SDK handles serialization, timeouts, and error handling when talking to your private engine.

import { PayVerifyClient, toMinorUnits } from "@verifiable/sdk";

const verifier = new PayVerifyClient({
  baseUrl: process.env.PAY_VERIFY_URL || "http://pay-verify:3000",
  apiKey: process.env.PAY_VERIFY_API_KEY!,
  timeoutMs: 15000,
});

// Inside your checkout verification endpoint:
export async function handleConfirmPayment(orderId: string, customerInput: string) {
  const order = await db.orders.get(orderId);

  const result = await verifier.verifyPayment({
    input: customerInput,
    provider: "telebirr", // optional hint
    expected: {
      amountMinor: toMinorUnits(order.totalAmount, "ETB"), // 1500.00 ETB -> 150000
      currency: "ETB",
      receiverProfile: "main-store",
    },
    context: {
      orderId: order.id,
      idempotencyKey: `payment:${order.id}`,
    },
  });

  switch (result.status) {
    case "verified":
      await markOrderPaid(order.id, result.verificationId);
      return { success: true, message: "Order confirmed" };

    case "already_used":
      await flagFraud(order.id, "Receipt reused across orders");
      return { success: false, error: "This transaction number has already been claimed." };

    case "amount_mismatch":
      return { success: false, error: "Paid amount does not match order total." };

    case "provider_unavailable":
      // Network hiccup or provider maintenance: safe to retry without marking order failed!
      return { success: false, retryable: true, error: "Provider temporarily unavailable. Please retry shortly." };

    case "not_completed":
      return { success: false, error: "Payment is still processing on provider system. Please wait." };

    case "not_found":
      return { success: false, error: "Transaction record does not exist on bank system." };

    default:
      return { success: false, error: "Verification could not be established." };
  }
}