paybridge 0.1.3 → 0.2.2

package/dist/providers/flutterwave.js

@@ -0,0 +1,339 @@
+"use strict";
+/**
+ * Flutterwave payment provider
+ * Leading payment gateway for Africa with global reach
+ * @see https://developer.flutterwave.com/docs
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlutterwaveProvider = void 0;
+const crypto = __importStar(require("crypto"));
+const base_1 = require("./base");
+const fetch_1 = require("../utils/fetch");
+class FlutterwaveProvider extends base_1.PaymentProvider {
+    constructor(config) {
+        super();
+        this.name = 'flutterwave';
+        this.supportedCurrencies = ['NGN', 'GHS', 'KES', 'UGX', 'ZAR', 'USD', 'EUR', 'GBP'];
+        this.baseUrl = 'https://api.flutterwave.com/v3';
+        this.apiKey = config.apiKey;
+        this.webhookSecret = config.webhookSecret;
+        this.sandbox = config.sandbox ?? this.apiKey.startsWith('FLWSECK_TEST-');
+    }
+    async apiRequest(method, path, data) {
+        const url = `${this.baseUrl}${path}`;
+        const response = await (0, fetch_1.timedFetch)(url, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: data ? JSON.stringify(data) : undefined,
+        });
+        const json = await response.json();
+        if (!response.ok || json.status !== 'success') {
+            throw new Error(json.message || `Flutterwave API error (${method} ${path}): ${response.status}`);
+        }
+        return json;
+    }
+    async createPayment(params) {
+        this.validateCurrency(params.currency);
+        const metadata = {
+            reference: params.reference,
+        };
+        if (params.metadata) {
+            for (const [key, value] of Object.entries(params.metadata)) {
+                metadata[key] = value;
+            }
+        }
+        const requestBody = {
+            tx_ref: params.reference,
+            amount: params.amount.toFixed(2),
+            currency: params.currency,
+            redirect_url: params.urls.success,
+            customer: {
+                email: params.customer.email,
+                phonenumber: params.customer.phone,
+                name: params.customer.name,
+            },
+            customizations: {
+                title: params.description || 'Payment',
+                description: params.description,
+            },
+            meta: metadata,
+        };
+        const response = await this.apiRequest('POST', '/payments', requestBody);
+        return {
+            id: params.reference,
+            checkoutUrl: response.data.link,
+            status: 'pending',
+            amount: params.amount,
+            currency: params.currency.toUpperCase(),
+            reference: params.reference,
+            provider: 'flutterwave',
+            createdAt: new Date().toISOString(),
+            raw: response,
+        };
+    }
+    async createSubscription(params) {
+        this.validateCurrency(params.currency);
+        const intervalMap = {
+            weekly: 'weekly',
+            monthly: 'monthly',
+            yearly: 'yearly',
+        };
+        const flutterwaveInterval = intervalMap[params.interval];
+        const planData = {
+            amount: Math.round(params.amount),
+            name: params.description || params.reference,
+            interval: flutterwaveInterval,
+            currency: params.currency,
+            duration: 0,
+        };
+        const planResponse = await this.apiRequest('POST', '/payment-plans', planData);
+        const planId = planResponse.data.id;
+        const metadata = {
+            reference: params.reference,
+        };
+        if (params.metadata) {
+            for (const [key, value] of Object.entries(params.metadata)) {
+                metadata[key] = value;
+            }
+        }
+        const paymentData = {
+            tx_ref: params.reference,
+            amount: params.amount.toFixed(2),
+            currency: params.currency,
+            redirect_url: params.urls.success,
+            payment_plan: planId,
+            customer: {
+                email: params.customer.email,
+                phonenumber: params.customer.phone,
+                name: params.customer.name,
+            },
+            customizations: {
+                title: params.description || params.reference,
+                description: params.description,
+            },
+            meta: metadata,
+        };
+        const paymentResponse = await this.apiRequest('POST', '/payments', paymentData);
+        return {
+            id: params.reference,
+            checkoutUrl: paymentResponse.data.link,
+            status: 'pending',
+            amount: params.amount,
+            currency: params.currency.toUpperCase(),
+            interval: params.interval,
+            reference: params.reference,
+            provider: 'flutterwave',
+            startsAt: params.startDate,
+            createdAt: new Date().toISOString(),
+            raw: paymentResponse,
+        };
+    }
+    async getPayment(id) {
+        const response = await this.apiRequest('GET', `/transactions/verify_by_reference?tx_ref=${id}`);
+        const data = response.data;
+        const currency = (data.currency || 'NGN').toUpperCase();
+        let status = 'pending';
+        if (data.status === 'successful') {
+            status = 'completed';
+        }
+        else if (data.status === 'failed') {
+            status = 'failed';
+        }
+        return {
+            id: data.tx_ref || id,
+            checkoutUrl: '',
+            status,
+            amount: data.amount,
+            currency,
+            reference: data.tx_ref || id,
+            provider: 'flutterwave',
+            createdAt: new Date(data.created_at || Date.now()).toISOString(),
+            raw: response,
+        };
+    }
+    async refund(params) {
+        let flwId;
+        if (/^\d+$/.test(params.paymentId)) {
+            flwId = parseInt(params.paymentId, 10);
+        }
+        else {
+            const verifyResponse = await this.apiRequest('GET', `/transactions/verify_by_reference?tx_ref=${params.paymentId}`);
+            flwId = verifyResponse.data.id;
+            if (!flwId) {
+                throw new Error('Transaction not found or has no Flutterwave ID');
+            }
+        }
+        const refundData = {};
+        if (params.amount !== undefined) {
+            refundData.amount = params.amount.toFixed(2);
+        }
+        const response = await this.apiRequest('POST', `/transactions/${flwId}/refund`, refundData);
+        const data = response.data;
+        const currency = (data.currency || 'NGN').toUpperCase();
+        let status = 'pending';
+        if (data.status === 'completed') {
+            status = 'completed';
+        }
+        else if (data.status === 'failed') {
+            status = 'failed';
+        }
+        return {
+            id: data.id?.toString() || flwId.toString(),
+            status,
+            amount: data.amount || params.amount || 0,
+            currency,
+            paymentId: params.paymentId,
+            createdAt: new Date(data.created_at || Date.now()).toISOString(),
+            raw: response,
+        };
+    }
+    parseWebhook(body, _headers) {
+        const event = typeof body === 'string' ? JSON.parse(body) : body;
+        const typeMap = {
+            'charge.completed': 'payment.completed',
+            'transfer.completed': 'payment.completed',
+            'subscription.cancelled': 'subscription.cancelled',
+            'refund.completed': 'refund.completed',
+        };
+        let eventType = 'payment.pending';
+        if (event.event === 'charge.completed' && event.data?.status === 'successful') {
+            eventType = 'payment.completed';
+        }
+        else if (event.event === 'charge.completed' && event.data?.status === 'failed') {
+            eventType = 'payment.failed';
+        }
+        else {
+            eventType = typeMap[event.event] || 'payment.pending';
+        }
+        const data = event.data || {};
+        let payment;
+        let subscription;
+        let refund;
+        if (event.event === 'charge.completed' || event.event === 'transfer.completed') {
+            const currency = (data.currency || 'NGN').toUpperCase();
+            let status = 'pending';
+            if (data.status === 'successful') {
+                status = 'completed';
+            }
+            else if (data.status === 'failed') {
+                status = 'failed';
+            }
+            payment = {
+                id: data.id?.toString() || '',
+                checkoutUrl: '',
+                status,
+                amount: data.amount || 0,
+                currency,
+                reference: data.tx_ref || '',
+                provider: 'flutterwave',
+                createdAt: new Date(data.created_at || Date.now()).toISOString(),
+            };
+        }
+        else if (event.event === 'subscription.cancelled') {
+            const currency = (data.currency || 'NGN').toUpperCase();
+            subscription = {
+                id: data.id?.toString() || '',
+                checkoutUrl: '',
+                status: 'cancelled',
+                amount: data.amount || 0,
+                currency,
+                interval: 'monthly',
+                reference: data.tx_ref || '',
+                provider: 'flutterwave',
+                createdAt: new Date(data.created_at || Date.now()).toISOString(),
+            };
+        }
+        else if (event.event === 'refund.completed') {
+            const currency = (data.currency || 'NGN').toUpperCase();
+            refund = {
+                id: data.id?.toString() || '',
+                status: 'completed',
+                amount: data.amount || 0,
+                currency,
+                paymentId: data.tx_ref || '',
+                createdAt: new Date(data.created_at || Date.now()).toISOString(),
+            };
+        }
+        return {
+            type: eventType,
+            payment,
+            subscription,
+            refund,
+            raw: event,
+        };
+    }
+    /**
+     * Verify webhook signature using Flutterwave's scheme.
+     * Flutterwave sends the configured webhook secret hash as the verif-hash header.
+     * This is a simple equality check, not HMAC.
+     */
+    verifyWebhook(body, headers) {
+        if (!this.webhookSecret) {
+            return false;
+        }
+        const receivedHash = headers?.['verif-hash'] || headers?.['Verif-Hash'];
+        if (!receivedHash) {
+            return false;
+        }
+        try {
+            const secretBuffer = Buffer.from(this.webhookSecret, 'utf8');
+            const receivedBuffer = Buffer.from(receivedHash, 'utf8');
+            if (secretBuffer.length !== receivedBuffer.length) {
+                return false;
+            }
+            return crypto.timingSafeEqual(secretBuffer, receivedBuffer);
+        }
+        catch {
+            return false;
+        }
+    }
+    getCapabilities() {
+        return {
+            fees: {
+                fixed: 0,
+                percent: 1.4,
+                currency: 'NGN',
+            },
+            currencies: this.supportedCurrencies,
+            country: 'NG',
+            avgLatencyMs: 700,
+        };
+    }
+}
+exports.FlutterwaveProvider = FlutterwaveProvider;

package/dist/providers/ozow.d.ts

@@ -5,6 +5,7 @@
  */
 import { PaymentProvider } from './base';
 import { CreatePaymentParams, PaymentResult, CreateSubscriptionParams, SubscriptionResult, RefundParams, RefundResult, WebhookEvent } from '../types';
+import { ProviderCapabilities } from '../routing-types';
 interface OzowConfig {
     apiKey: string;
     siteCode: string;
@@ -19,15 +20,32 @@ export declare class OzowProvider extends PaymentProvider {
     private privateKey;
     private sandbox;
     private baseUrl;
+    private redirectBaseUrl;
     constructor(config: OzowConfig);
     createPayment(params: CreatePaymentParams): Promise<PaymentResult>;
-    createSubscription(params: CreateSubscriptionParams): Promise<SubscriptionResult>;
+    /**
+     * Ozow does not support recurring subscriptions (EFT instant-payment provider)
+     * Use a card-based provider for subscription functionality
+     */
+    createSubscription(_params: CreateSubscriptionParams): Promise<SubscriptionResult>;
     getPayment(id: string): Promise<PaymentResult>;
-    refund(params: RefundParams): Promise<RefundResult>;
+    /**
+     * Ozow refunds require manual processing via merchant portal
+     * No public API endpoint for instant-EFT refunds
+     */
+    refund(_params: RefundParams): Promise<RefundResult>;
     parseWebhook(body: any, _headers?: any): WebhookEvent;
+    /**
+     * Verify Ozow ITN webhook signature
+     * Note: Ozow ITN has no timestamp, so no replay protection possible
+     * Caller should validate idempotency by TransactionId
+     */
     verifyWebhook(body: any, _headers?: any): boolean;
+    getCapabilities(): ProviderCapabilities;
     private mapOzowStatus;
     private mapOzowEventType;
+    private generateHash;
     private generateWebhookHash;
+    private sanitizeBankReference;
 }
 export {};