BICTORYS_API_URL=https://api.bictorys.com
BICTORYS_API_KEY=public-XXXX.YYYY
BICTORYS_PRIVATE_KEY=secret-XXXX.YYYY
BICTORYS_WEBHOOK_SECRET=your_webhook_secret
BICTORYS_MERCHANT_SECRET_CODE=1234

X-Api-Key: <your_key>
Content-Type: application/json

POST {BICTORYS_API_URL}/pay/v1/charges?payment_type={type}

POST {BICTORYS_API_URL}/pay/v1/charges

{
  "amount": 5000,
  "currency": "XOF",
  "country": "SN",
  "paymentReference": "ORDER-ABC123",
  "successRedirectUrl": "https://mysite.com/success?ref=ORDER-ABC123",
  "ErrorRedirectUrl": "https://mysite.com/error?ref=ORDER-ABC123",
  "customerObject": {
    "name": "Amadou Fall",
    "phone": "+221771234567",
    "email": "[email protected]",
    "country": "SN"
  },
  "otp": "123456"
}

{
  "transactionId": "33e1c83b-7cb0-437b-bc50-a7a58e5660ad",
  "redirectUrl": "https://pay.bictorys.com/checkout/33e1c83b-...",
  "link": "https://pay.bictorys.com/link/...",
  "qrCode": "data:image/png;base64,...",
  "message": "Dial *144*82# to confirm..."
}

const needsOtp = paymentType === "orange_money" && (country === "CI" || country === "BF");

const body: Record<string, unknown> = {
  amount,
  currency,
  country,
  paymentReference,
  successRedirectUrl,
  ErrorRedirectUrl,
  customerObject,
};

// Only for Orange Money CI / BF
if (otp) {
  body.otp = otp;
}

GET {BICTORYS_API_URL}/pay/v1/transactions/{transactionId}/status

POST https://your-api.com/webhooks/bictorys
Content-Type: application/json
X-Secret-Key: <your_webhook_secret>          # always present
X-Webhook-Signature: <hmac_sha256_hex>       # optional (if HMAC enabled)
X-Webhook-Timestamp: <unix_timestamp_ms>     # optional (if HMAC enabled)

import crypto from "crypto";

function verifyHmacSignature(
  rawBody: string,
  secret: string,
  signature: string,
  timestamp: string
): boolean {
  // 1. Replay protection — reject if timestamp > 5 minutes old
  const ts = parseInt(timestamp, 10);
  if (isNaN(ts) || Math.abs(Date.now() - ts) > 5 * 60 * 1000) {
    return false;
  }

  // 2. Compute the HMAC
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  // 3. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  } catch {
    return false;
  }
}

function verifyStaticKey(secretKeyHeader: string, expectedSecret: string): boolean {
  try {
    return crypto.timingSafeEqual(
      Buffer.from(secretKeyHeader),
      Buffer.from(expectedSecret)
    );
  } catch {
    return false;
  }
}

{
  "id": "33e1c83b-7cb0-437b-bc50-a7a58e5660ad",
  "merchantId": "d2d2053b-638d-4133-957e-3caf63e6b79c",
  "type": "payment",
  "amount": 5000,
  "currency": "XOF",
  "paymentReference": "ORDER-ABC123",
  "customerId": "fbd2053b-...",
  "customerObject": {
    "id": "fbd2053b-...",
    "name": "Amadou Fall",
    "phone": 221771234567,
    "email": "[email protected]",
    "address": "",
    "city": "Dakar",
    "postalCode": 0,
    "country": "SN",
    "locale": "fr-FR",
    "createdAt": "2026-03-01T12:00:00Z",
    "updatedAt": "2026-03-01T12:00:00Z"
  },
  "pspName": "wave_money",
  "paymentMeans": "+221 *** ** 67",
  "paymentChannel": "Terminal",
  "merchantFees": 150,
  "customerFees": 0,
  "merchantReference": "ORDER-ABC123",
  "status": "succeeded",
  "timestamp": "2026-03-01T12:05:00Z"
}

import express from "express";
import crypto from "crypto";

const app = express();

// ⚠️ CRITICAL ORDER: raw BEFORE json
app.use("/webhooks", express.raw({ type: "application/json" }));
app.use(express.json());

app.post("/webhooks/bictorys", async (req, res) => {
  try {
    const rawBody = Buffer.isBuffer(req.body)
      ? req.body.toString("utf-8")
      : req.body;

    const signature = req.headers["x-webhook-signature"] as string | undefined;
    const timestamp = req.headers["x-webhook-timestamp"] as string | undefined;
    const secretKey = req.headers["x-secret-key"] as string | undefined;

    // Signature verification
    let isValid = false;
    if (signature && timestamp) {
      isValid = verifyHmacSignature(rawBody, WEBHOOK_SECRET, signature, timestamp);
    } else if (secretKey) {
      isValid = verifyStaticKey(secretKey, WEBHOOK_SECRET);
    }

    if (!isValid) {
      console.error("Webhook signature invalid");
      res.status(200).json({ received: true }); // 200 anyway
      return;
    }

    const payload = JSON.parse(rawBody);
    const { id, status, paymentReference, amount, currency } = payload;

    // → Log, verify anti-fraud, process idempotently
    // → Your business logic here

    res.status(200).json({ received: true });
  } catch (error) {
    console.error("Webhook error:", error);
    res.status(200).json({ received: true }); // ALWAYS 200
  }
});

POST {BICTORYS_API_URL}/pay/v1/payouts?payment_type={type}

{
  "amount": 10000,
  "currency": "XOF",
  "country": "SN",
  "customerObject": {
    "name": "Amadou Fall",
    "phone": "+221771234567",
    "email": "[email protected]",
    "country": "SN",
    "locale": "fr-FR"
  },
  "transactionType": "payment",
  "paymentReason": "Fund transfer",
  "merchantReference": "WD-ABC123",
  "merchant": {
    "secretCode": "1234"
  }
}

{
  "id": "abc123-def456",
  "merchantId": "d2d2053b-...",
  "amount": -10000,
  "merchantFee": 150,
  "customerFee": 0,
  "currency": "XOF",
  "paymentReference": "...",
  "customerName": "Amadou Fall",
  "customerPhone": "221771234567",
  "customerCountry": "SN",
  "pspName": "wave_money",
  "merchantReference": "WD-ABC123",
  "status": 0,
  "createdAt": "2026-03-01T12:00:00Z"
}

GET {BICTORYS_API_URL}/onboarding/v1/payment-methods/me
X-API-Key: BICTORYS_PRIVATE_KEY

// bictorys-provider.ts
import crypto from "crypto";

const API_URL = process.env.BICTORYS_API_URL!;
const API_KEY = process.env.BICTORYS_API_KEY!;
const PRIVATE_KEY = process.env.BICTORYS_PRIVATE_KEY!;
const WEBHOOK_SECRET = process.env.BICTORYS_WEBHOOK_SECRET!;
const MERCHANT_SECRET_CODE = process.env.BICTORYS_MERCHANT_SECRET_CODE!;

// ─── Create a payment ───────────────────────────────────────

interface CreateChargeParams {
  amount: number;
  currency: "XOF";
  country: string;
  paymentType: string;
  paymentReference: string;
  successRedirectUrl: string;
  errorRedirectUrl: string;
  customer?: {
    name: string;
    phone: string;
    email: string;
    country: string;
  };
  otp?: string;
}

interface ChargeResult {
  transactionId: string;
  redirectUrl: string;
  link?: string;
  qrCode?: string;
  message?: string;
}

async function createCharge(params: CreateChargeParams): Promise<ChargeResult> {
  // For cards, add payment_category=card
  const queryParams =
    params.paymentType === "card"
      ? `payment_type=card&payment_category=card`
      : `payment_type=${params.paymentType}`;

  const url = `${API_URL}/pay/v1/charges?${queryParams}`;

  const body: Record<string, unknown> = {
    amount: params.amount,
    currency: params.currency,
    country: params.country,
    paymentReference: params.paymentReference,
    successRedirectUrl: params.successRedirectUrl,
    ErrorRedirectUrl: params.errorRedirectUrl, // ⚠️ capital E
    customerObject: params.customer,
  };

  // otp field only for Orange Money CI / BF
  if (params.otp) body.otp = params.otp;

  const MAX_RETRIES = 3;
  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
    // Exponential backoff on retries (WAF)
    if (attempt > 0) {
      await new Promise((r) => setTimeout(r, Math.pow(2, attempt) * 1000));
    }

    const response = await fetch(url, {
      method: "POST",
      headers: {
        "X-Api-Key": API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });

    if (response.ok) return await response.json();

    const errorText = await response.text();
    // WAF 403 → retry
    if (
      response.status === 403 &&
      errorText.includes("Forbidden") &&
      attempt < MAX_RETRIES
    ) {
      continue;
    }

    throw new Error(`Bictorys charge error (${response.status}): ${errorText}`);
  }

  throw new Error("Bictorys charge: max retries reached");
}

// ─── Check transaction status ────────────────────────────────

async function checkChargeStatus(transactionId: string): Promise<string> {
  const response = await fetch(`${API_URL}/pay/v1/charges/${transactionId}`, {
    headers: { "X-Api-Key": API_KEY },
  });

  if (!response.ok) throw new Error(`Status check error: ${response.status}`);

  const data = await response.json();
  return data.status; // "succeeded", "pending", "failed", etc.
}

// ─── Create a payout ─────────────────────────────────────────

interface PayoutParams {
  amount: number;
  paymentType: "wave_money" | "orange_money";
  phone: string;
  name: string;
  email: string;
  merchantReference: string;
}

async function createPayout(params: PayoutParams, idempotencyKey: string) {
  const url = `${API_URL}/pay/v1/payouts?payment_type=${params.paymentType}`;

  const body = {
    amount: params.amount,
    currency: "XOF",
    country: "SN",
    customerObject: {
      name: params.name,
      phone: params.phone,
      email: params.email,
      country: "SN",
      locale: "fr-FR",
    },
    transactionType: "payment",
    paymentReason: "Fund transfer",
    merchantReference: params.merchantReference,
    merchant: { secretCode: MERCHANT_SECRET_CODE },
  };

  // 30s timeout (payouts can be slow)
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 30000);

  try {
    const response = await fetch(url, {
      method: "POST",
      headers: {
        "X-API-Key": PRIVATE_KEY, // ⚠️ private key mandatory
        "Content-Type": "application/json",
        accept: "application/json",
        "idempotency-key": idempotencyKey,
      },
      body: JSON.stringify(body),
      signal: controller.signal,
    });
    clearTimeout(timeout);

    if (response.ok) return { success: true, data: await response.json() };

    const errorText = await response.text();
    return {
      success: false,
      error: errorText,
      httpStatus: response.status,
    };
  } catch (error) {
    clearTimeout(timeout);
    throw error;
  }
}

// ─── Verify a webhook ────────────────────────────────────────

function verifyWebhook(
  rawBody: string,
  headers: Record<string, string | undefined>
): boolean {
  const signature = headers["x-webhook-signature"];
  const timestamp = headers["x-webhook-timestamp"];
  const secretKey = headers["x-secret-key"];

  // Method 1: HMAC-SHA256 (recommended)
  if (signature && timestamp) {
    const ts = parseInt(timestamp, 10);
    // Replay protection: 5 minutes
    if (isNaN(ts) || Math.abs(Date.now() - ts) > 5 * 60 * 1000) return false;

    const expected = crypto
      .createHmac("sha256", WEBHOOK_SECRET)
      .update(`${timestamp}.${rawBody}`)
      .digest("hex");

    try {
      return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expected)
      );
    } catch {
      return false;
    }
  }

  // Method 2: Static key (fallback)
  if (secretKey) {
    try {
      return crypto.timingSafeEqual(
        Buffer.from(secretKey),
        Buffer.from(WEBHOOK_SECRET)
      );
    } catch {
      return false;
    }
  }

  return false;
}

// ─── Detect country from phone number ────────────────────────

function detectCountryFromPhone(phone: string): string | null {
  if (phone.startsWith("+221") || phone.startsWith("221")) return "SN";
  if (phone.startsWith("+225") || phone.startsWith("225")) return "CI";
  if (phone.startsWith("+226") || phone.startsWith("226")) return "BF";
  if (phone.startsWith("+223") || phone.startsWith("223")) return "ML";
  if (phone.startsWith("+228") || phone.startsWith("228")) return "TG";
  if (phone.startsWith("+229") || phone.startsWith("229")) return "BJ";
  return null;
}