openpay-ng 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenPay NG contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,222 @@
+# OpenPay NG
+
+One consistent TypeScript interface for Nigerian payment providers. OpenPay is
+a developer-friendly abstraction layer — not a replacement for Paystack,
+Flutterwave, or Bachs. You write provider-agnostic payment code; OpenPay
+handles provider-specific differences underneath.
+
+> Sandbox-proven with Paystack and Flutterwave (create → checkout → verify →
+> real webhook). Not production-hardened — see Current limitations.
+
+## 1. Installation
+
+Requires Node.js 20+.
+
+```bash
+npm install openpay-ng
+```
+
+PostgreSQL is optional but recommended: without `DATABASE_URL` the SDK runs
+stateless (no idempotency cache, no webhook/event persistence).
+
+## 2. Quick start
+
+```ts
+import { OpenPay } from "openpay-ng";
+
+const openpay = new OpenPay({
+  provider: "paystack",
+  secretKey: process.env.PAYSTACK_SECRET_KEY!,
+});
+
+const payment = await openpay.payments.create({
+  amount: "5000.00", // decimal string, never a float — see Idempotency/Money note
+  currency: "NGN",
+  customer: { email: "customer@example.com" },
+});
+
+console.log(payment.checkoutUrl); // send the customer here to pay
+```
+
+## 3. Configuration
+
+Single-provider shorthand:
+
+```ts
+new OpenPay({ provider: "paystack", secretKey: "..." });
+```
+
+Multi-provider / explicit form (an explicit per-provider block always wins):
+
+```ts
+new OpenPay({
+  defaultProvider: "paystack",
+  paystack: { secretKey: "..." },
+  flutterwave: { secretKey: "...", webhookSecretHash: "..." },
+});
+```
+
+Keys resolve explicit-config → environment, so `PAYSTACK_SECRET_KEY`,
+`FLUTTERWAVE_SECRET_KEY`, and `BACHS_SECRET_KEY` work with no config at all.
+`openpay.configuredProviders()` lists what's actually wired up. Unconfigured
+providers throw `ConfigurationError` only when used.
+
+## 4. Creating a payment
+
+```ts
+const payment = await openpay.payments.create({
+  amount: "5000.00",
+  currency: "NGN",
+  customer: { email: "customer@example.com", name: "Ada", phone: "0803..." },
+  provider: "flutterwave", // optional: overrides the default provider
+  reference: "order_123", // optional: your unique reference (generated if omitted)
+  idempotencyKey: "…", // optional: defaults to operation+provider+reference
+  redirectUrl: "https://yourapp.com/pay/callback", // REQUIRED by Flutterwave
+  metadata: { plan: "pro" }, // optional string map
+});
+// payment: { id, provider, reference, providerRef, amount, currency,
+//            status: "pending", checkoutUrl?, customerEmail?, raw? }
+```
+
+## 5. Verifying a payment
+
+```ts
+const verified = await openpay.payments.verify({ reference: payment.reference });
+// or: openpay.payments.verify({ reference, provider: "flutterwave" });
+// verified.status: "pending" | "successful" | "failed" | "unknown"
+```
+
+`unknown` is **not** `failed`: it means the outcome couldn't be determined
+(e.g. provider timeout). Verify again before retrying — never treat it as a
+failure. `payments.retrieve()` is an alias of `verify()`.
+
+Note the two verify shapes in V1: `payments.verify({ reference, provider? })`
+takes an input object, while `transfers.verify(reference, provider?)` takes
+positional arguments. Both default to the configured default provider.
+
+## 6. Webhooks
+
+Point the provider dashboard at your receiver (`POST /webhooks/paystack`,
+`POST /webhooks/flutterwave`), then feed the **raw** body plus headers into
+the SDK — raw bytes matter because signature checks run over them:
+
+```ts
+// Express-style example (use a raw-body parser, not express.json()).
+// Node/Express req.headers can be passed directly, including repeated headers.
+app.post("/webhooks/paystack", async (req, res) => {
+  const event = await openpay.webhooks.normalize("paystack", req.body, req.headers);
+  // event: { type: "payment.succeeded" | …, provider, reference?, … } | null
+  res.status(200).json({ ok: true });
+});
+```
+
+`normalizeDetailed()` additionally reports `{ event, duplicate, projected }`
+for retried deliveries. A dependency-free reference receiver ships with the
+repo (`npm run receiver`, local dev only — not part of the published API).
+
+Persistence-dependent webhook behavior requires `DATABASE_URL`. Without it
+(stateless mode) webhooks still verify and normalize, but events are not
+stored, retries are not deduplicated (`duplicate` is always false), and
+payment rows are not projected. The same applies to idempotency below.
+
+## 7. Idempotency
+
+Repeated `payments.create()` calls with the same reference/idempotency key
+return the cached result without a second provider charge. This requires
+`DATABASE_URL` (first write wins); in stateless mode every call reaches the
+provider. Webhook retries collapse via a unique `(provider, type, event)`
+record — same requirement: without persistence there is no stored record to
+deduplicate against.
+
+Money is always a decimal string (`"5000.00"`, ISO-4217 currency). The
+`normalizeAmount()` helper is exported for convenience.
+
+## 8. Supported providers
+
+| Provider | Create/verify | Webhooks | Notes |
+|---|---|---|---|
+| Paystack | ✅ sandbox-proven | ✅ sandbox-proven (HMAC-SHA512) | Full V1 surface incl. refunds/transfers (code; transfers/refunds not live-tested) |
+| Flutterwave | ✅ sandbox-proven | ✅ sandbox-proven (`verif-hash`) | `redirectUrl` required on create; refunds need the numeric transaction id; refunds/transfers not live-tested |
+| Bachs | checkout-session based | provisional | Implemented, **not live-tested**; refunds/transfers throw `CapabilityError` |
+
+## 9. Normalized payment statuses
+
+Every provider maps to `pending | successful | failed | unknown`. Timeouts and
+unrecognized provider states map to `unknown`. Webhook events project onto
+payment rows: `payment.succeeded → successful`, `payment.failed → failed`;
+`payment.pending` and non-payment events never regress a stored status.
+Projection requires persistence (see Webhooks above).
+
+### References: `reference` vs `providerRef`
+
+Every payment carries two identifiers. `reference` is yours (the merchant
+reference you passed, or a generated one). `providerRef` is the provider's
+own identifier for the same payment, and it differs per provider:
+
+- Paystack: `providerRef` echoes your reference.
+- Flutterwave: `providerRef` is the provider's `flw_ref` at creation (falls back to your `tx_ref`), then the numeric
+  transaction id after verification.
+- Bachs: `providerRef` is the `checkout_id`.
+
+You need `providerRef` when correlating OpenPay records with provider
+dashboard entries, and for provider-specific operations — e.g. Flutterwave
+refunds address the numeric transaction id, so pass the `providerRef` you
+received from `verify()` as `paymentReference`.
+
+### Data stored in Postgres
+
+Payment, transfer, refund, idempotency, and webhook rows persist the raw
+provider responses (`jsonb`), which may include provider-returned customer
+and payment metadata (e.g. customer email, card brand/last digits — never
+full card numbers, which OpenPay never touches). This audit trail is what
+powers idempotency, dedupe, and status projection. Storage only happens when
+persistence is configured (`DATABASE_URL`); stateless mode stores nothing.
+Apply your own retention and access policies to the database.
+
+## 10. Environment variables
+
+```env
+DATABASE_URL=postgres://openpay:openpay@localhost:5432/openpay
+PAYSTACK_SECRET_KEY=your_test_secret_key
+FLUTTERWAVE_SECRET_KEY=your_test_secret_key
+BACHS_SECRET_KEY=your_test_secret_key
+PAYSTACK_WEBHOOK_SECRET=your_webhook_secret
+FLUTTERWAVE_WEBHOOK_SECRET_HASH=your_webhook_secret
+BACHS_WEBHOOK_SECRET=your_webhook_secret
+OPENPAY_DEFAULT_PROVIDER=paystack
+PORT=3000
+```
+
+## 11. Sandbox/testing
+
+```bash
+npm test            # mocked unit suite, no network
+npm run build       # emits dist/
+npm pack --dry-run  # inspect publish contents (never publishes)
+npm run smoke:consumer  # builds, packs, installs into a temp project,
+                        # exercises the public API + types with mocked HTTP
+```
+
+Live sandbox checks need real test keys and (for webhooks) a public tunnel,
+e.g. `ngrok http 3000`, with the dashboard URL pointed at
+`https://<tunnel-host>/webhooks/<provider>`. Never commit real keys.
+
+## 12. Current limitations
+
+- Sandbox-proven only (Paystack + Flutterwave payments/webhooks). **Not
+  production readiness.**
+- Bachs implemented but not live-tested; no refund/transfer support there.
+- Flutterwave refunds/transfers implemented but not live-tested.
+- Webhook events do not auto-create payment rows for unknown references.
+- No routing/failover, card vaulting, dashboard, or multi-language SDKs (V1 scope).
+
+## 13. Errors
+
+All errors extend `OpenPayError` (with machine-readable `code`):
+
+- `ValidationError` — bad input (e.g. non-decimal amount, Flutterwave create without `redirectUrl`)
+- `ConfigurationError` — missing/unconfigured provider or keys
+- `ProviderError` — the provider rejected the call (`status`, `retryable`, `raw` attached)
+- `CapabilityError` — provider doesn't support the operation in V1
+- `UnknownResultError` — ambiguous outcome; verify before retrying (`retryable: true`)
+- `WebhookVerificationError` — signature/hash check failed

package/dist/config.d.ts

@@ -0,0 +1,37 @@
+import type { HttpClient, ProviderConnector } from "./connectors/types.js";
+import type { ProviderName } from "./core/types.js";
+import { type Persistence } from "./db/store.js";
+export interface ProviderConf {
+    secretKey?: string;
+    baseUrl?: string;
+    webhookSecret?: string;
+    webhookSecretHash?: string;
+    http?: HttpClient;
+    timeoutMs?: number;
+}
+export interface OpenPayConfig {
+    defaultProvider?: ProviderName;
+    paystack?: ProviderConf;
+    flutterwave?: ProviderConf;
+    bachs?: ProviderConf;
+    /**
+     * Shorthand for single-provider setups. Equivalent to setting
+     * `defaultProvider` plus `{ secretKey }` on that provider's block;
+     * an explicit per-provider block always wins.
+     *
+     *   new OpenPay({ provider: "paystack", secretKey: process.env.PAYSTACK_SECRET_KEY })
+     */
+    provider?: ProviderName;
+    secretKey?: string;
+    /** Pass DATABASE_URL to enable Postgres persistence; omit for stateless/memory. */
+    databaseUrl?: string;
+    persistence?: Persistence;
+    http?: HttpClient;
+    timeoutMs?: number;
+}
+export interface ResolvedContext {
+    connectors: Record<ProviderName, ProviderConnector>;
+    defaultProvider: ProviderName;
+    persistence?: Persistence;
+}
+export declare function resolveContext(cfg?: OpenPayConfig): ResolvedContext;

package/dist/config.js

@@ -0,0 +1,78 @@
+import { BachsConnector } from "./connectors/bachs.js";
+import { FlutterwaveConnector } from "./connectors/flutterwave.js";
+import { PaystackConnector } from "./connectors/paystack.js";
+import { ConfigurationError } from "./core/errors.js";
+import { getDb } from "./db/client.js";
+import { DrizzlePersistence, MemoryPersistence } from "./db/store.js";
+/** Env lookup that treats empty strings as unset (common in half-filled .env files). */
+function env(name) {
+    const v = process.env[name];
+    return v && v.length > 0 ? v : undefined;
+}
+export function resolveContext(cfg = {}) {
+    const defaultProvider = cfg.provider ?? cfg.defaultProvider ?? "paystack";
+    const connectors = {};
+    // Shorthand secret applies to the resolved default provider only, and loses
+    // to an explicit per-provider secretKey.
+    const shorthandKeyFor = (name) => name === defaultProvider ? cfg.secretKey : undefined;
+    const paystackKey = cfg.paystack?.secretKey || shorthandKeyFor("paystack") || env("PAYSTACK_SECRET_KEY");
+    const flwKey = cfg.flutterwave?.secretKey || shorthandKeyFor("flutterwave") || env("FLUTTERWAVE_SECRET_KEY");
+    const bachsKey = cfg.bachs?.secretKey || shorthandKeyFor("bachs") || env("BACHS_SECRET_KEY");
+    if (paystackKey) {
+        connectors.paystack = new PaystackConnector({
+            secretKey: paystackKey,
+            baseUrl: cfg.paystack?.baseUrl,
+            webhookSecret: cfg.paystack?.webhookSecret || env("PAYSTACK_WEBHOOK_SECRET"),
+            http: cfg.paystack?.http ?? cfg.http,
+            timeoutMs: cfg.paystack?.timeoutMs ?? cfg.timeoutMs,
+        });
+    }
+    if (flwKey) {
+        connectors.flutterwave = new FlutterwaveConnector({
+            secretKey: flwKey,
+            baseUrl: cfg.flutterwave?.baseUrl,
+            webhookSecretHash: cfg.flutterwave?.webhookSecretHash || env("FLUTTERWAVE_WEBHOOK_SECRET_HASH"),
+            http: cfg.flutterwave?.http ?? cfg.http,
+            timeoutMs: cfg.flutterwave?.timeoutMs ?? cfg.timeoutMs,
+        });
+    }
+    if (bachsKey) {
+        connectors.bachs = new BachsConnector({
+            secretKey: bachsKey,
+            baseUrl: cfg.bachs?.baseUrl,
+            webhookSecret: cfg.bachs?.webhookSecret || env("BACHS_WEBHOOK_SECRET"),
+            http: cfg.bachs?.http ?? cfg.http,
+            timeoutMs: cfg.bachs?.timeoutMs ?? cfg.timeoutMs,
+        });
+    }
+    if (!connectors[defaultProvider]) {
+        const available = Object.keys(connectors).join(", ") || "none";
+        throw new ConfigurationError(`Default provider '${defaultProvider}' is not configured (available: ${available}). ` +
+            `Set ${defaultProvider.toUpperCase()}_SECRET_KEY or pass explicit keys.`);
+    }
+    // Fill missing connectors lazily? No — fail fast only for the default.
+    // Accessing an unconfigured provider later throws ConfigurationError.
+    let persistence = cfg.persistence;
+    const dbUrl = cfg.databaseUrl ?? process.env.DATABASE_URL;
+    if (!persistence && dbUrl) {
+        try {
+            persistence = new DrizzlePersistence(getDb(dbUrl));
+        }
+        catch {
+            persistence = new MemoryPersistence();
+        }
+    }
+    // Proxy missing connectors so errors stay typed at call time.
+    const handler = {
+        get(target, prop) {
+            const v = target[prop];
+            if (v)
+                return v;
+            if (prop === "then")
+                return undefined;
+            throw new ConfigurationError(`Provider '${prop}' is not configured. Set its secret key first.`);
+        },
+    };
+    const proxied = new Proxy(connectors, handler);
+    return { connectors: proxied, defaultProvider, persistence };
+}

package/dist/connectors/bachs.d.ts

@@ -0,0 +1,33 @@
+import type { CreatePaymentInput, CreateRefundInput, CreateTransferInput, OpenPayEvent, Payment, PaymentStatus, ProviderCapabilities, Refund, Transfer, VerifyPaymentInput, WebhookHeaders } from "../core/types.js";
+import type { ConnectorConfig, ProviderConnector } from "./types.js";
+export declare function mapBachsPaymentStatus(s: string): PaymentStatus;
+/**
+ * Bachs is checkout-session based, not charge based.
+ * createPayment -> POST /v1/checkout-sessions (pricing + customer + reference)
+ * verifyPayment -> GET /v1/checkout-sessions/:id (payment_status + charge)
+ * Refunds/transfers have no V1 equivalent -> CapabilityError.
+ */
+export declare class BachsConnector implements ProviderConnector {
+    readonly name: "bachs";
+    readonly capabilities: ProviderCapabilities;
+    private secretKey;
+    private baseUrl;
+    private timeoutMs;
+    private http;
+    private webhookSecret?;
+    constructor(cfg: ConnectorConfig & {
+        webhookSecret?: string;
+    });
+    private headers;
+    createPayment(input: CreatePaymentInput & {
+        reference: string;
+    }): Promise<Payment>;
+    verifyPayment(input: VerifyPaymentInput): Promise<Payment>;
+    createRefund(_input: CreateRefundInput): Promise<Refund>;
+    createTransfer(_input: CreateTransferInput & {
+        reference: string;
+    }): Promise<Transfer>;
+    verifyTransfer(_reference: string): Promise<Transfer>;
+    verifyWebhookSignature(rawBody: string | Buffer, headers: WebhookHeaders): boolean;
+    normalizeWebhook(payload: unknown): OpenPayEvent | null;
+}

package/dist/connectors/bachs.js

@@ -0,0 +1,172 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { CapabilityError, ConfigurationError } from "../core/errors.js";
+import { newId } from "../core/idempotency.js";
+import { normalizeAmount } from "../core/validation.js";
+import { firstHeader, providerJson } from "./http.js";
+const SANDBOX_BASE = "https://sandbox-api.bachs.io";
+const LIVE_BASE = "https://api.bachs.io";
+export function mapBachsPaymentStatus(s) {
+    switch (s.toLowerCase()) {
+        case "succeeded":
+        case "paid":
+        case "completed":
+        case "success":
+            return "successful";
+        case "failed":
+        case "cancelled":
+        case "canceled":
+        case "expired":
+            return "failed";
+        case "pending":
+        case "processing":
+        case "requires_action":
+        case "requiresaction":
+        case "created":
+            return "pending";
+        default:
+            return "unknown";
+    }
+}
+/**
+ * Bachs is checkout-session based, not charge based.
+ * createPayment -> POST /v1/checkout-sessions (pricing + customer + reference)
+ * verifyPayment -> GET /v1/checkout-sessions/:id (payment_status + charge)
+ * Refunds/transfers have no V1 equivalent -> CapabilityError.
+ */
+export class BachsConnector {
+    name = "bachs";
+    capabilities = {
+        paymentsCreate: true,
+        paymentsVerify: true,
+        refunds: false,
+        transfers: false,
+        webhooks: true,
+    };
+    secretKey;
+    baseUrl;
+    timeoutMs;
+    http;
+    webhookSecret;
+    constructor(cfg) {
+        if (!cfg.secretKey)
+            throw new ConfigurationError("Bachs secret key is required");
+        this.secretKey = cfg.secretKey;
+        this.baseUrl = (cfg.baseUrl ?? (cfg.secretKey.startsWith("sk_live_") ? LIVE_BASE : SANDBOX_BASE)).replace(/\/$/, "");
+        this.timeoutMs = cfg.timeoutMs ?? 15_000;
+        this.http = cfg.http;
+        this.webhookSecret = cfg.webhookSecret;
+    }
+    headers(idempotencyKey) {
+        const h = { Authorization: `Bearer ${this.secretKey}` };
+        // Bachs supports Idempotency-Key on POSTs — forward ours when available.
+        if (idempotencyKey)
+            h["Idempotency-Key"] = idempotencyKey;
+        return h;
+    }
+    async createPayment(input) {
+        const amount = normalizeAmount(input.amount);
+        const data = await providerJson(`${this.baseUrl}/v1/checkout-sessions`, {
+            method: "POST",
+            headers: this.headers(input.idempotencyKey),
+            body: {
+                pricing: { currency: input.currency, amount },
+                customer: { email: input.customer.email, name: input.customer.name },
+                reference: input.reference,
+                success_url: input.redirectUrl,
+                cancel_url: input.redirectUrl,
+                metadata: input.metadata,
+            },
+            timeoutMs: this.timeoutMs,
+            provider: "bachs",
+            reference: input.reference,
+            http: this.http,
+        });
+        const checkoutId = data.checkout_id ?? data.checkoutId ?? data.id ?? input.reference;
+        const checkoutUrl = data.checkout_url ?? data.checkoutUrl ?? data.url;
+        return {
+            id: newId(),
+            provider: "bachs",
+            reference: input.reference,
+            providerRef: checkoutId,
+            amount,
+            currency: input.currency,
+            status: "pending",
+            checkoutUrl,
+            customerEmail: input.customer.email,
+            raw: data,
+        };
+    }
+    async verifyPayment(input) {
+        const data = await providerJson(`${this.baseUrl}/v1/checkout-sessions/${encodeURIComponent(input.reference)}`, {
+            headers: this.headers(),
+            timeoutMs: this.timeoutMs,
+            provider: "bachs",
+            reference: input.reference,
+            http: this.http,
+        });
+        const rawStatus = data.payment_status ?? data.charge?.status ?? data.status ?? "unknown";
+        return {
+            id: newId(),
+            provider: "bachs",
+            reference: data.checkout_id ?? input.reference,
+            providerRef: data.checkout_id ?? input.reference,
+            amount: typeof data.amount === "number"
+                ? data.amount.toFixed(2)
+                : typeof data.amount === "string"
+                    ? normalizeAmount(data.amount)
+                    : "0.00",
+            currency: data.currency ?? "NGN",
+            status: mapBachsPaymentStatus(rawStatus),
+            customerEmail: data.customer?.email,
+            raw: data,
+        };
+    }
+    async createRefund(_input) {
+        throw new CapabilityError("bachs", "refunds", "no refund API in Bachs V1 docs; use dashboard or provider API directly");
+    }
+    async createTransfer(_input) {
+        throw new CapabilityError("bachs", "transfers", "no transfer/payout API in Bachs V1 docs");
+    }
+    async verifyTransfer(_reference) {
+        throw new CapabilityError("bachs", "transfers", "no transfer/payout API in Bachs V1 docs");
+    }
+    verifyWebhookSignature(rawBody, headers) {
+        // Provisional: HMAC-SHA256 over raw body. Confirm header name against Bachs dashboard.
+        if (!this.webhookSecret)
+            return false;
+        const sig = firstHeader(headers, "x-bachs-signature", "bachs-signature", "x-webhook-signature");
+        if (!sig)
+            return false;
+        const digest = createHmac("sha256", this.webhookSecret).update(rawBody).digest("hex");
+        const a = Buffer.from(digest);
+        const b = Buffer.from(sig.replace(/^sha256=/, ""));
+        return a.length === b.length && timingSafeEqual(a, b);
+    }
+    normalizeWebhook(payload) {
+        if (typeof payload !== "object" || payload === null)
+            return null;
+        const p = payload;
+        const name = (p.type ?? p.event ?? "").toLowerCase();
+        if (!name)
+            return null;
+        if (name === "collection.succeeded" || name === "checkout.succeeded" || name === "payment.succeeded") {
+            return {
+                type: "payment.succeeded",
+                provider: "bachs",
+                providerEventId: p.data?.id,
+                reference: p.data?.checkout_id ?? p.data?.reference,
+                raw: payload,
+            };
+        }
+        if (name === "collection.failed" || name === "payment.failed" || name === "checkout.expired") {
+            return {
+                type: "payment.failed",
+                provider: "bachs",
+                providerEventId: p.data?.id,
+                reference: p.data?.checkout_id ?? p.data?.reference,
+                raw: payload,
+            };
+        }
+        return { type: "unknown", provider: "bachs", raw: payload };
+    }
+}

package/dist/connectors/flutterwave.d.ts

@@ -0,0 +1,29 @@
+import type { CreatePaymentInput, CreateRefundInput, CreateTransferInput, OpenPayEvent, Payment, PaymentStatus, ProviderCapabilities, Refund, Transfer, VerifyPaymentInput, WebhookHeaders } from "../core/types.js";
+import type { ConnectorConfig, ProviderConnector } from "./types.js";
+export declare function mapFlutterwaveStatus(s: string): PaymentStatus;
+export declare class FlutterwaveConnector implements ProviderConnector {
+    readonly name: "flutterwave";
+    readonly capabilities: ProviderCapabilities;
+    private secretKey;
+    private baseUrl;
+    private timeoutMs;
+    private http;
+    private webhookSecret;
+    constructor(cfg: ConnectorConfig & {
+        webhookSecretHash?: string;
+    });
+    private headers;
+    createPayment(input: CreatePaymentInput & {
+        reference: string;
+    }): Promise<Payment>;
+    verifyPayment(input: VerifyPaymentInput): Promise<Payment>;
+    createRefund(input: CreateRefundInput): Promise<Refund>;
+    createTransfer(input: CreateTransferInput & {
+        reference: string;
+    }): Promise<Transfer>;
+    verifyTransfer(reference: string): Promise<Transfer>;
+    verifyWebhookSignature(_rawBody: string | Buffer, headers: WebhookHeaders): boolean;
+    normalizeWebhook(payload: unknown): OpenPayEvent | null;
+    /** Documented `{event, data}` envelope shape. Unchanged behavior. */
+    private normalizeDocumentedShape;
+}