REST API Examples

REST Examples Until Official SDKs Ship

Official SDK packages are not published yet. These examples use the current REST API directly and keep the same structure an SDK will wrap later: submit, inspect the response, poll when queued, and verify webhook signatures.

TypeScriptPythonPHPPollingWebhook receivers

Use REST First

Treat these snippets as small SDK adapters you can place in your own backend. Keep API keys server-side and never expose VERIFY_BANK_ET_your_key_here secrets in browser code.

Base URL: https://verify.et

Recommended abstraction

Build one server-side function that accepts a normalized payment reference, submits POST /api/verify, and returns either a completed verification or the requestId your app will poll.

Verification Request Helpers

type VerifyResponse = {
  success: boolean;
  message: string;
  requestId?: string;
  verification?: {
    processingStatus: "queued" | "running" | "completed" | "failed";
    status?: "success" | "failed" | "not_found" | "pending";
    verified?: boolean;
  };
  links?: {
    statusUrl: string;
    pollAfterMs?: number;
    webhookRegistered?: boolean;
  };
};

export async function verifyCbePayment() {
  const response = await fetch("https://verify.et/api/verify?waitMs=5000", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.VERIFY_ET_API_KEY!,
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      bank: "cbe",
      referenceNumber: "FT1234567890",
      accountSuffix: "12345678",
    }),
  });

  const body = (await response.json()) as VerifyResponse;

  if (!response.ok && response.status !== 202) {
    throw new Error(body.message);
  }

  return body;
}

Polling Helper

Use polling when POST /api/verify returns 202. Stop when processingStatus is completed or failed.

export async function pollVerification(requestId: string) {
  const statusUrl = "https://verify.et/api/verify/" + requestId;

  for (let attempt = 0; attempt < 30; attempt += 1) {
    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, 1500));
  }

  throw new Error("Polling timed out");
}

Webhook Receivers

Webhook endpoints should respond quickly with a 2xx status, then do heavier work asynchronously. If X-Webhook-Signature is present, verify it before trusting the payload.

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

const app = express();

app.post("/webhooks/verify", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.header("X-Webhook-Timestamp");
  const signature = req.header("X-Webhook-Signature");
  const rawBody = req.body.toString("utf8");

  if (signature && process.env.VERIFY_ET_WEBHOOK_SECRET) {
    const expected = crypto
      .createHmac("sha256", process.env.VERIFY_ET_WEBHOOK_SECRET)
      .update(`${timestamp}.${rawBody}`)
      .digest("hex");

    if (signature !== `sha256=${expected}`) {
      return res.sendStatus(401);
    }
  }

  const event = JSON.parse(rawBody);
  console.log(event.requestId, event.data.status);

  return res.sendStatus(204);
});

SDK Roadmap

JavaScript / TypeScript

Typed REST client, webhook verifier, polling helper.

Python

Requests/httpx client, retries, typed response models.

PHP

Composer package with webhook signature helper.

Dart

Flutter-friendly client for mobile merchant apps.

Next up

Full API Reference