paybridge 0.1.3 → 0.2.2

package/dist/providers/paystack.js

@@ -0,0 +1,336 @@
+"use strict";
+/**
+ * PayStack payment provider
+ * Leading payment gateway for Africa (Nigeria, Ghana, South Africa, Kenya)
+ * @see https://paystack.com/docs/api
+ */
+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.PayStackProvider = void 0;
+const crypto = __importStar(require("crypto"));
+const base_1 = require("./base");
+const currency_1 = require("../utils/currency");
+const fetch_1 = require("../utils/fetch");
+class PayStackProvider extends base_1.PaymentProvider {
+    constructor(config) {
+        super();
+        this.name = 'paystack';
+        this.supportedCurrencies = ['NGN', 'GHS', 'ZAR', 'USD', 'KES'];
+        this.baseUrl = 'https://api.paystack.co';
+        this.apiKey = config.apiKey;
+        this.webhookSecret = config.webhookSecret;
+        this.sandbox = config.sandbox ?? this.apiKey.startsWith('sk_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 === false) {
+            throw new Error(json.message || `PayStack API error (${method} ${path}): ${response.status}`);
+        }
+        return json;
+    }
+    async createPayment(params) {
+        this.validateCurrency(params.currency);
+        const amountInMinorUnits = (0, currency_1.toMinorUnit)(params.amount, params.currency);
+        const metadata = {
+            cancel_action: params.urls.cancel,
+            reference: params.reference,
+            custom_fields: [
+                {
+                    display_name: 'Customer',
+                    variable_name: 'customer_name',
+                    value: params.customer.name,
+                },
+            ],
+        };
+        if (params.metadata) {
+            for (const [key, value] of Object.entries(params.metadata)) {
+                metadata[key] = value;
+            }
+        }
+        const requestBody = {
+            email: params.customer.email,
+            amount: amountInMinorUnits,
+            currency: params.currency,
+            reference: params.reference,
+            callback_url: params.urls.success,
+            metadata,
+        };
+        const response = await this.apiRequest('POST', '/transaction/initialize', requestBody);
+        return {
+            id: response.data.reference,
+            checkoutUrl: response.data.authorization_url,
+            status: 'pending',
+            amount: params.amount,
+            currency: params.currency.toUpperCase(),
+            reference: response.data.reference,
+            provider: 'paystack',
+            createdAt: new Date().toISOString(),
+            raw: response,
+        };
+    }
+    async createSubscription(params) {
+        this.validateCurrency(params.currency);
+        const amountInMinorUnits = (0, currency_1.toMinorUnit)(params.amount, params.currency);
+        const intervalMap = {
+            weekly: 'weekly',
+            monthly: 'monthly',
+            yearly: 'annually',
+        };
+        const paystackInterval = intervalMap[params.interval];
+        const planData = {
+            name: params.description || params.reference,
+            amount: amountInMinorUnits,
+            interval: paystackInterval,
+            currency: params.currency,
+        };
+        const planResponse = await this.apiRequest('POST', '/plan', planData);
+        const planCode = planResponse.data.plan_code;
+        const metadata = {
+            cancel_action: params.urls.cancel,
+            reference: params.reference,
+            custom_fields: [
+                {
+                    display_name: 'Customer',
+                    variable_name: 'customer_name',
+                    value: params.customer.name,
+                },
+            ],
+        };
+        if (params.metadata) {
+            for (const [key, value] of Object.entries(params.metadata)) {
+                metadata[key] = value;
+            }
+        }
+        const transactionData = {
+            email: params.customer.email,
+            plan: planCode,
+            callback_url: params.urls.success,
+            metadata,
+        };
+        const transactionResponse = await this.apiRequest('POST', '/transaction/initialize', transactionData);
+        return {
+            id: transactionResponse.data.reference,
+            checkoutUrl: transactionResponse.data.authorization_url,
+            status: 'pending',
+            amount: params.amount,
+            currency: params.currency.toUpperCase(),
+            interval: params.interval,
+            reference: params.reference,
+            provider: 'paystack',
+            startsAt: params.startDate,
+            createdAt: new Date().toISOString(),
+            raw: transactionResponse,
+        };
+    }
+    async getPayment(id) {
+        const response = await this.apiRequest('GET', `/transaction/verify/${id}`);
+        const data = response.data;
+        const currency = (data.currency || 'NGN').toUpperCase();
+        let status = 'pending';
+        if (data.status === 'success') {
+            status = 'completed';
+        }
+        else if (data.status === 'failed') {
+            status = 'failed';
+        }
+        else if (data.status === 'abandoned') {
+            status = 'cancelled';
+        }
+        return {
+            id: data.reference,
+            checkoutUrl: '',
+            status,
+            amount: (0, currency_1.toMajorUnit)(data.amount, currency),
+            currency,
+            reference: data.reference,
+            provider: 'paystack',
+            createdAt: new Date(data.created_at || data.createdAt || Date.now()).toISOString(),
+            raw: response,
+        };
+    }
+    async refund(params) {
+        const refundData = {
+            transaction: params.paymentId,
+        };
+        if (params.amount !== undefined) {
+            const currency = 'NGN';
+            refundData.amount = (0, currency_1.toMinorUnit)(params.amount, currency);
+        }
+        if (params.reason) {
+            refundData.merchant_note = params.reason;
+        }
+        const response = await this.apiRequest('POST', '/refund', refundData);
+        const data = response.data;
+        const currency = (data.currency || 'NGN').toUpperCase();
+        let status = 'pending';
+        if (data.status === 'processed') {
+            status = 'completed';
+        }
+        else if (data.status === 'failed') {
+            status = 'failed';
+        }
+        return {
+            id: data.id?.toString() || data.reference,
+            status,
+            amount: (0, currency_1.toMajorUnit)(data.amount || 0, currency),
+            currency,
+            paymentId: params.paymentId,
+            createdAt: new Date(data.created_at || data.createdAt || Date.now()).toISOString(),
+            raw: response,
+        };
+    }
+    parseWebhook(body, _headers) {
+        const event = typeof body === 'string' ? JSON.parse(body) : body;
+        const typeMap = {
+            'charge.success': 'payment.completed',
+            'charge.failed': 'payment.failed',
+            'subscription.create': 'subscription.created',
+            'subscription.disable': 'subscription.cancelled',
+            'subscription.expiring_cards': 'payment.pending',
+            'refund.processed': 'refund.completed',
+            'refund.failed': 'payment.failed',
+        };
+        const eventType = typeMap[event.event] || 'payment.pending';
+        const data = event.data || {};
+        let payment;
+        let subscription;
+        let refund;
+        if (event.event.startsWith('charge.')) {
+            const currency = (data.currency || 'NGN').toUpperCase();
+            let status = 'pending';
+            if (event.event === 'charge.success') {
+                status = 'completed';
+            }
+            else if (event.event === 'charge.failed') {
+                status = 'failed';
+            }
+            payment = {
+                id: data.reference,
+                checkoutUrl: '',
+                status,
+                amount: (0, currency_1.toMajorUnit)(data.amount || 0, currency),
+                currency,
+                reference: data.reference,
+                provider: 'paystack',
+                createdAt: new Date(data.created_at || data.paid_at || Date.now()).toISOString(),
+            };
+        }
+        else if (event.event.startsWith('subscription.')) {
+            const currency = (data.currency || 'NGN').toUpperCase();
+            subscription = {
+                id: data.subscription_code || data.id?.toString() || '',
+                checkoutUrl: '',
+                status: event.event === 'subscription.disable' ? 'cancelled' : 'active',
+                amount: (0, currency_1.toMajorUnit)(data.amount || 0, currency),
+                currency,
+                interval: 'monthly',
+                reference: data.subscription_code || '',
+                provider: 'paystack',
+                createdAt: new Date(data.created_at || Date.now()).toISOString(),
+            };
+        }
+        else if (event.event.startsWith('refund.')) {
+            const currency = (data.currency || 'NGN').toUpperCase();
+            refund = {
+                id: data.id?.toString() || data.refund_id?.toString() || '',
+                status: event.event === 'refund.processed' ? 'completed' : 'failed',
+                amount: (0, currency_1.toMajorUnit)(data.amount || 0, currency),
+                currency,
+                paymentId: data.transaction_reference || data.transaction || '',
+                createdAt: new Date(data.created_at || Date.now()).toISOString(),
+            };
+        }
+        return {
+            type: eventType,
+            payment,
+            subscription,
+            refund,
+            raw: event,
+        };
+    }
+    /**
+     * Verify webhook signature using PayStack's HMAC-SHA512 scheme.
+     *
+     * CRITICAL: body must be the raw string or Buffer from the webhook request.
+     * Passing a parsed JSON object will cause signature verification to fail.
+     */
+    verifyWebhook(body, headers) {
+        if (!this.apiKey) {
+            return false;
+        }
+        const signature = headers?.['x-paystack-signature'] || headers?.['X-Paystack-Signature'];
+        if (!signature) {
+            return false;
+        }
+        const rawBody = typeof body === 'string' ? body : body.toString('utf8');
+        const computedSig = crypto
+            .createHmac('sha512', this.apiKey)
+            .update(rawBody)
+            .digest('hex');
+        try {
+            const computedBuffer = Buffer.from(computedSig, 'hex');
+            const expectedBuffer = Buffer.from(signature, 'hex');
+            if (computedBuffer.length !== expectedBuffer.length) {
+                return false;
+            }
+            return crypto.timingSafeEqual(computedBuffer, expectedBuffer);
+        }
+        catch {
+            return false;
+        }
+    }
+    getCapabilities() {
+        return {
+            fees: {
+                fixed: 100,
+                percent: 1.5,
+                currency: 'NGN',
+            },
+            currencies: this.supportedCurrencies,
+            country: 'NG',
+            avgLatencyMs: 600,
+        };
+    }
+}
+exports.PayStackProvider = PayStackProvider;

package/dist/providers/peach.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Peach Payments provider
+ * South African payment gateway using Open Payment Platform (OPP)
+ * @see https://docs.peachpayments.com
+ */
+import { PaymentProvider } from './base';
+import { CreatePaymentParams, PaymentResult, CreateSubscriptionParams, SubscriptionResult, RefundParams, RefundResult, WebhookEvent } from '../types';
+import { ProviderCapabilities } from '../routing-types';
+interface PeachConfig {
+    accessToken: string;
+    entityId: string;
+    sandbox: boolean;
+    webhookSecret?: string;
+}
+export declare class PeachProvider extends PaymentProvider {
+    readonly name = "peach";
+    readonly supportedCurrencies: string[];
+    private accessToken;
+    private entityId;
+    private sandbox;
+    private webhookSecret?;
+    private baseUrl;
+    constructor(config: PeachConfig);
+    private buildFormData;
+    private apiRequest;
+    private mapPeachStatus;
+    /**
+     * Create a one-time payment checkout.
+     *
+     * IMPORTANT: The returned checkoutUrl is a JavaScript widget URL, not a direct redirect.
+     * You must embed it in an HTML page with:
+     *
+     * <script src="{checkoutUrl}"></script>
+     * <form action="{successUrl}" class="paymentWidgets" data-brands="VISA MASTER"></form>
+     *
+     * The widget will render the payment form inside the <form> element.
+     */
+    createPayment(params: CreatePaymentParams): Promise<PaymentResult>;
+    /**
+     * Peach Payments subscriptions require Registration + scheduled charges flow.
+     * This is not yet supported by paybridge. Use Stripe or PayFast for subscriptions.
+     */
+    createSubscription(_params: CreateSubscriptionParams): Promise<SubscriptionResult>;
+    getPayment(id: string): Promise<PaymentResult>;
+    refund(params: RefundParams): Promise<RefundResult>;
+    parseWebhook(body: any, headers?: any): WebhookEvent;
+    verifyWebhook(body: string | Buffer, headers?: any): boolean;
+    getCapabilities(): ProviderCapabilities;
+}
+export {};

package/dist/providers/peach.js

@@ -0,0 +1,302 @@
+"use strict";
+/**
+ * Peach Payments provider
+ * South African payment gateway using Open Payment Platform (OPP)
+ * @see https://docs.peachpayments.com
+ */
+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.PeachProvider = void 0;
+const crypto = __importStar(require("crypto"));
+const base_1 = require("./base");
+const fetch_1 = require("../utils/fetch");
+class PeachProvider extends base_1.PaymentProvider {
+    constructor(config) {
+        super();
+        this.name = 'peach';
+        this.supportedCurrencies = ['ZAR', 'USD', 'EUR', 'GBP'];
+        this.accessToken = config.accessToken;
+        this.entityId = config.entityId;
+        this.sandbox = config.sandbox;
+        this.webhookSecret = config.webhookSecret;
+        this.baseUrl = this.sandbox
+            ? 'https://eu-test.oppwa.com'
+            : 'https://eu-prod.oppwa.com';
+    }
+    buildFormData(data) {
+        const parts = [];
+        for (const [key, value] of Object.entries(data)) {
+            if (value === undefined || value === null)
+                continue;
+            parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+        }
+        return parts.join('&');
+    }
+    async apiRequest(method, path, data) {
+        const url = `${this.baseUrl}${path}`;
+        let finalUrl = url;
+        let body;
+        if (method === 'GET' && data) {
+            const queryData = { entityId: this.entityId, ...data };
+            const queryString = this.buildFormData(queryData);
+            finalUrl = `${url}?${queryString}`;
+        }
+        else if (data) {
+            const bodyData = { entityId: this.entityId, ...data };
+            body = this.buildFormData(bodyData);
+        }
+        const response = await (0, fetch_1.timedFetchOrThrow)(finalUrl, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.accessToken}`,
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body,
+        });
+        return (await response.json());
+    }
+    mapPeachStatus(code) {
+        if (code.startsWith('000.000.') || code.startsWith('000.100.')) {
+            return 'completed';
+        }
+        if (code.startsWith('000.200.')) {
+            return 'pending';
+        }
+        if (code.startsWith('000.400.')) {
+            return 'cancelled';
+        }
+        if (code.startsWith('100.') ||
+            code.startsWith('200.') ||
+            code.startsWith('300.') ||
+            code.startsWith('400.') ||
+            code.startsWith('500.') ||
+            code.startsWith('600.') ||
+            code.startsWith('700.') ||
+            code.startsWith('800.') ||
+            code.startsWith('900.')) {
+            return 'failed';
+        }
+        return 'pending';
+    }
+    /**
+     * Create a one-time payment checkout.
+     *
+     * IMPORTANT: The returned checkoutUrl is a JavaScript widget URL, not a direct redirect.
+     * You must embed it in an HTML page with:
+     *
+     * <script src="{checkoutUrl}"></script>
+     * <form action="{successUrl}" class="paymentWidgets" data-brands="VISA MASTER"></form>
+     *
+     * The widget will render the payment form inside the <form> element.
+     */
+    async createPayment(params) {
+        this.validateCurrency(params.currency);
+        const nameParts = params.customer.name.split(' ');
+        const givenName = nameParts[0] || '';
+        const surname = nameParts.slice(1).join(' ') || givenName;
+        const formData = {
+            amount: params.amount.toFixed(2),
+            currency: params.currency,
+            paymentType: 'DB',
+            merchantTransactionId: params.reference,
+            'customer.email': params.customer.email,
+            'customer.givenName': givenName,
+            'customer.surname': surname,
+            'billing.country': 'ZA',
+            shopperResultUrl: params.urls.success,
+            notificationUrl: params.urls.webhook,
+            'customParameters[reference]': params.reference,
+        };
+        if (params.metadata) {
+            for (const [key, value] of Object.entries(params.metadata)) {
+                formData[`customParameters[${key}]`] = String(value);
+            }
+        }
+        const response = await this.apiRequest('POST', '/v1/checkouts', formData);
+        if (!response.result?.code.startsWith('000.')) {
+            throw new Error(`${response.result?.code}: ${response.result?.description}`);
+        }
+        const checkoutUrl = `${this.baseUrl}/v1/paymentWidgets.js?checkoutId=${response.id}`;
+        return {
+            id: response.id,
+            checkoutUrl,
+            status: 'pending',
+            amount: params.amount,
+            currency: params.currency,
+            reference: params.reference,
+            provider: 'peach',
+            createdAt: response.timestamp || new Date().toISOString(),
+            raw: response,
+        };
+    }
+    /**
+     * Peach Payments subscriptions require Registration + scheduled charges flow.
+     * This is not yet supported by paybridge. Use Stripe or PayFast for subscriptions.
+     */
+    async createSubscription(_params) {
+        throw new Error('Peach Payments subscriptions require Registration + scheduled charges; not yet supported by paybridge. Use Stripe or PayFast for subscriptions.');
+    }
+    async getPayment(id) {
+        const response = await this.apiRequest('GET', `/v1/checkouts/${id}/payment`, {});
+        const status = this.mapPeachStatus(response.result?.code || '');
+        return {
+            id: response.id,
+            checkoutUrl: '',
+            status,
+            amount: parseFloat(response.amount || '0'),
+            currency: response.currency || 'ZAR',
+            reference: response.merchantTransactionId || id,
+            provider: 'peach',
+            createdAt: response.timestamp || new Date().toISOString(),
+            raw: response,
+        };
+    }
+    async refund(params) {
+        const formData = {
+            paymentType: 'RF',
+        };
+        if (params.amount !== undefined) {
+            formData.amount = params.amount.toFixed(2);
+            formData.currency = 'ZAR';
+        }
+        const response = await this.apiRequest('POST', `/v1/payments/${params.paymentId}`, formData);
+        const code = response.result?.code || '';
+        let status = 'pending';
+        if (code.startsWith('000.') && !code.startsWith('000.200.')) {
+            status = 'completed';
+        }
+        else if (code.startsWith('000.200.')) {
+            status = 'pending';
+        }
+        else {
+            status = 'failed';
+        }
+        const currency = response.currency || 'ZAR';
+        return {
+            id: response.id || `refund_${params.paymentId}_${Date.now()}`,
+            status,
+            amount: parseFloat(response.amount || String(params.amount || 0)),
+            currency,
+            paymentId: params.paymentId,
+            createdAt: response.timestamp || new Date().toISOString(),
+            raw: response,
+        };
+    }
+    parseWebhook(body, headers) {
+        let event;
+        if (this.webhookSecret && headers) {
+            try {
+                const rawBody = typeof body === 'string' ? body : JSON.stringify(body);
+                const key = Buffer.from(this.webhookSecret, 'hex');
+                const iv = Buffer.from(headers['x-initialization-vector'], 'hex');
+                const authTag = Buffer.from(headers['x-authentication-tag'], 'hex');
+                const ciphertext = Buffer.from(rawBody, 'hex');
+                const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+                decipher.setAuthTag(authTag);
+                const plaintext = Buffer.concat([
+                    decipher.update(ciphertext),
+                    decipher.final(),
+                ]).toString('utf8');
+                event = JSON.parse(plaintext);
+            }
+            catch {
+                event = typeof body === 'string' ? JSON.parse(body) : body;
+            }
+        }
+        else {
+            event = typeof body === 'string' ? JSON.parse(body) : body;
+        }
+        const payload = event.payload || event;
+        const resultCode = payload.result?.code || '';
+        const status = this.mapPeachStatus(resultCode);
+        let eventType = 'payment.pending';
+        if (status === 'completed') {
+            eventType = 'payment.completed';
+        }
+        else if (status === 'failed') {
+            eventType = 'payment.failed';
+        }
+        else if (status === 'cancelled') {
+            eventType = 'payment.cancelled';
+        }
+        return {
+            type: eventType,
+            payment: {
+                id: payload.id || '',
+                checkoutUrl: '',
+                status,
+                amount: parseFloat(payload.amount || '0'),
+                currency: payload.currency || 'ZAR',
+                reference: payload.merchantTransactionId || '',
+                provider: 'peach',
+                createdAt: new Date().toISOString(),
+            },
+            raw: event,
+        };
+    }
+    verifyWebhook(body, headers) {
+        if (!this.webhookSecret) {
+            return false;
+        }
+        try {
+            const rawBody = typeof body === 'string' ? body : body.toString('utf8');
+            const key = Buffer.from(this.webhookSecret, 'hex');
+            const iv = Buffer.from(headers['x-initialization-vector'], 'hex');
+            const authTag = Buffer.from(headers['x-authentication-tag'], 'hex');
+            const ciphertext = Buffer.from(rawBody, 'hex');
+            const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+            decipher.setAuthTag(authTag);
+            decipher.update(ciphertext);
+            decipher.final();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    getCapabilities() {
+        return {
+            fees: {
+                fixed: 1.0,
+                percent: 2.85,
+                currency: 'ZAR',
+            },
+            currencies: this.supportedCurrencies,
+            country: 'ZA',
+            avgLatencyMs: 600,
+        };
+    }
+}
+exports.PeachProvider = PeachProvider;