EgoPayHQ
Developer API

curl -X GET https://bkzurgwkozsnaauztghh.supabase.co/functions/v1/egopay-customers \
  -H "Authorization: Bearer live_YOUR_API_KEY" \
  -H "X-Org-ID: your-org-slug" \
  -H "Content-Type: application/json"

import crypto from "crypto";

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// In your Express handler:
app.post("/webhooks/platform", (req, res) => {
  const sig = req.headers["x-egopayhq-signature"] as string;
  const raw = JSON.stringify(req.body);

  if (!verifyWebhook(raw, sig, process.env.PLATFORM_WEBHOOK_SECRET!)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const { event, data } = req.body;

  if (event === "va.deposit.received") {
    // Credit the customer's wallet in your app
    await creditUserWallet(data.customer_id, data.amount);
  }

  res.json({ received: true });
});

// platform-sdk.ts — minimal SDK wrapper (production-ready)
const BASE = "https://bkzurgwkozsnaauztghh.supabase.co/functions/v1";

class PlatformSDK {
  private headers: Record<string, string>;

  constructor({ apiKey, orgId }: { apiKey: string; orgId: string }) {
    this.headers = {
      "Authorization": `Bearer ${apiKey}`,
      "X-Org-ID": orgId,
      "Content-Type": "application/json",
    };
  }

  private async request<T>(method: string, fn: string, path = "", body?: unknown): Promise<T> {
    const res = await fetch(`${BASE}/${fn}${path}`, {
      method,
      headers: this.headers,
      body: body ? JSON.stringify(body) : undefined,
    });
    const data = await res.json();
    if (!res.ok) throw new Error(data.message ?? "API error");
    return data.data as T;
  }

  customers = {
    create: (body: unknown) => this.request("POST", "egopay-customers", "", body),
    get: (id: string) => this.request("GET", "egopay-customers", `/${id}`),
    list: (params?: Record<string, string>) =>
      this.request("GET", "egopay-customers", `?${new URLSearchParams(params)}`),
    getKyc: (id: string) => this.request("GET", "egopay-customers", `/${id}/kyc`),
  };

  virtualAccounts = {
    create: (body: unknown) => this.request("POST", "egopay-virtual-accounts", "", body),
    get: (id: string) => this.request("GET", "egopay-virtual-accounts", `/${id}`),
    list: (params?: Record<string, string>) =>
      this.request("GET", "egopay-virtual-accounts", `?${new URLSearchParams(params)}`),
  };

  payouts = {
    create: (body: unknown) => this.request("POST", "egopay-payouts", "", body),
    bulk: (payouts: unknown[]) => this.request("POST", "egopay-payouts", "/bulk", { payouts }),
    get: (id: string) => this.request("GET", "egopay-payouts", `/${id}`),
    list: (params?: Record<string, string>) =>
      this.request("GET", "egopay-payouts", `?${new URLSearchParams(params)}`),
    // Resolve a bank account name before sending a payout
    resolve: (accountNumber: string, bankCode: string) =>
      this.request("GET", "egopay-payouts", `/resolve?account_number=${accountNumber}&bank_code=${bankCode}`),
    // Get the full list of supported Nigerian banks (cached 24h)
    banks: () => this.request("GET", "egopay-payouts", "/banks"),
  };

  transactions = {
    list: (params?: Record<string, string>) =>
      this.request("GET", "egopay-transactions", `?${new URLSearchParams(params)}`),
    get: (id: string) => this.request("GET", "egopay-transactions", `/${id}`),
  };
}

// Usage — these are LIVE endpoints:
const sdk = new PlatformSDK({
  apiKey: process.env.PLATFORM_API_KEY!,   // live_... from your dashboard
  orgId: process.env.PLATFORM_ORG_ID!,     // your org slug e.g. "acme-finance"
});

// 1. Create a customer
const customer = await sdk.customers.create({
  full_name: "Amaka Obi",
  email: "amaka@example.com",
  phone: "+2348012345678",
  bvn: "22345678901",
});

// 2. Assign a virtual account
const account = await sdk.virtualAccounts.create({
  customer_id: customer.id,
  bvn: "22345678901",
  first_name: "Amaka",
  last_name: "Obi",
  phone: "+2348012345678",
  email: "amaka@example.com",
});

console.log(account.account_number); // "9012345678"
console.log(account.bank_name);      // "Wema Bank"

// The provider field tells you which banking backend was used.
// This is controlled by the platform admin — your code never needs to change.
console.log(account.provider);
// "ure_microfinance_bank"  → URE Microfinance Bank (via Lenco infrastructure)
// "matrixpay"             → Asset Matrix MFB (via CashMatrix)

// 3. Filter VA list by provider — useful for auditing or migration
const ureAccounts = await sdk.virtualAccounts.list({
  provider: "ure_microfinance_bank",
  limit: "50",
});
const matrixAccounts = await sdk.virtualAccounts.list({
  provider: "matrixpay",
});

// Each item in the list carries the provider field:
ureAccounts.forEach((va: { account_number: string; provider: string }) => {
  console.log(va.account_number, va.provider);
  // "9012345678"  "ure_microfinance_bank"
});

// 4. Initiate a payout
// sender_name controls the first part of the bank statement narration:
// "Adebanjo Olusayo Ayowole by YourOrgName"
const payout = await sdk.payouts.create({
  amount: 5000000,          // ₦50,000 in kobo
  bank_code: "058",
  account_number: "0123456789",
  account_name: "Chukwuemeka Nwosu",
  sender_name: "Adebanjo Olusayo Ayowole", // shown on recipient's bank statement
  narration: "Savings withdrawal",
});

console.log(payout.status);    // "success" | "pending"
console.log(payout.narration); // "Adebanjo Olusayo Ayowole by YourOrgName"