paybridge 0.4.0 → 0.5.0

package/README.md

@@ -194,6 +194,9 @@ app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
 | **Stripe** | ✅ | ✅ | ✅ | ✅ | **Production** |
 | **Peach Payments** | ✅ | ⛔ | ✅ | ✅ | **Production** |
 | **Flutterwave** | ✅ | ✅ | ✅ | ✅ | **Production** |
+| **Adyen** | ✅ | ⛔ | ✅ | ✅ | **Production** |
+| **Mercado Pago** | ✅ | ✅ | ✅ | ✅ | **Production** |
+| **Razorpay** | ✅ | ✅ | ✅ | ✅ | **Production** |
 
 ### Crypto on/off-ramp providers
 
@@ -207,7 +210,7 @@ app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
 **Notes:**
 - `⛔` marks features the underlying provider's API doesn't support — those methods throw a clear error explaining the limitation. Use a different provider for that capability or use `PayBridgeRouter` to route accordingly.
 - **Yellow Card** is gated behind `@experimental` until partner API documentation is verified — it logs a warning on instantiation. Do not use in production without partner-confirmed spec.
-- **Sandbox testing.** PayFast / PayStack / Stripe / Peach / Flutterwave are wired and unit-tested, but have not yet been validated against live sandbox credentials. To validate against real sandboxes, set the relevant `*_API_KEY` env vars and run `npm run test:e2e:sandbox`.
+- **Sandbox testing.** PayFast / PayStack / Stripe / Peach / Flutterwave / Adyen / Mercado Pago / Razorpay are wired and unit-tested, but have not yet been validated against live sandbox credentials. To validate against real sandboxes, set the relevant `*_API_KEY` env vars and run `npm run test:e2e:sandbox`.
 
 ## Provider Configuration
 
@@ -258,6 +261,58 @@ const pay = new PayBridge({
 
 **Docs:** [Ozow Hub](https://hub.ozow.com)
 
+### Adyen
+
+```typescript
+const pay = new PayBridge({
+  provider: 'adyen',
+  credentials: {
+    apiKey: 'your_api_key',
+    merchantAccount: 'YourMerchantAccount',
+    liveUrlPrefix: 'abc123' // Only for live mode
+  },
+  sandbox: true,
+  webhookSecret: 'your_hmac_key_hex'
+});
+```
+
+**Docs:** [Adyen API Explorer](https://docs.adyen.com/api-explorer/)
+
+**Note:** Adyen subscriptions require recurring tokenization flow (not yet supported). Use Stripe or PayFast for subscriptions.
+
+### Mercado Pago
+
+```typescript
+const pay = new PayBridge({
+  provider: 'mercadopago',
+  credentials: {
+    apiKey: 'TEST-...' // Or APP_USR-... for live
+  },
+  sandbox: true,
+  webhookSecret: 'your_webhook_secret'
+});
+```
+
+**Docs:** [Mercado Pago Developers](https://www.mercadopago.com/developers/en/reference)
+
+### Razorpay
+
+```typescript
+const pay = new PayBridge({
+  provider: 'razorpay',
+  credentials: {
+    apiKey: 'rzp_test_...', // key_id
+    secretKey: 'your_key_secret'
+  },
+  sandbox: true,
+  webhookSecret: 'your_webhook_secret'
+});
+```
+
+**Docs:** [Razorpay API Reference](https://razorpay.com/docs/api)
+
+**Note:** Razorpay webhooks do not include timestamp-based replay protection.
+
 ## Switch Providers in 1 Line
 
 ```typescript

package/dist/index.js

@@ -29,6 +29,9 @@ const stripe_1 = require("./providers/stripe");
 const payfast_1 = require("./providers/payfast");
 const paystack_1 = require("./providers/paystack");
 const flutterwave_1 = require("./providers/flutterwave");
+const adyen_1 = require("./providers/adyen");
+const mercadopago_1 = require("./providers/mercadopago");
+const razorpay_1 = require("./providers/razorpay");
 __exportStar(require("./types"), exports);
 __exportStar(require("./utils/currency"), exports);
 __exportStar(require("./utils/fetch"), exports);
@@ -135,6 +138,36 @@ class PayBridge {
                     sandbox,
                     webhookSecret,
                 });
+            case 'adyen':
+                if (!credentials.apiKey || !credentials.merchantAccount) {
+                    throw new Error('Adyen requires apiKey and merchantAccount');
+                }
+                return new adyen_1.AdyenProvider({
+                    apiKey: credentials.apiKey,
+                    merchantAccount: credentials.merchantAccount,
+                    liveUrlPrefix: credentials.liveUrlPrefix,
+                    sandbox,
+                    webhookSecret,
+                });
+            case 'mercadopago':
+                if (!credentials.apiKey) {
+                    throw new Error('Mercado Pago requires apiKey (access token TEST-* or APP_USR-*)');
+                }
+                return new mercadopago_1.MercadoPagoProvider({
+                    accessToken: credentials.apiKey,
+                    sandbox,
+                    webhookSecret,
+                });
+            case 'razorpay':
+                if (!credentials.apiKey || !credentials.secretKey) {
+                    throw new Error('Razorpay requires apiKey (key_id rzp_test_* or rzp_live_*) and secretKey (key_secret)');
+                }
+                return new razorpay_1.RazorpayProvider({
+                    keyId: credentials.apiKey,
+                    keySecret: credentials.secretKey,
+                    sandbox,
+                    webhookSecret,
+                });
             default:
                 throw new Error(`Unknown provider: ${provider}`);
         }

package/dist/providers/adyen.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Adyen payment provider
+ * Global payment platform supporting 150+ countries
+ * @see https://docs.adyen.com/api-explorer/Checkout/71/overview
+ */
+import { PaymentProvider } from './base';
+import { CreatePaymentParams, PaymentResult, CreateSubscriptionParams, SubscriptionResult, RefundParams, RefundResult, WebhookEvent } from '../types';
+import { ProviderCapabilities } from '../routing-types';
+interface AdyenConfig {
+    apiKey: string;
+    merchantAccount: string;
+    liveUrlPrefix?: string;
+    webhookSecret?: string;
+    sandbox?: boolean;
+}
+export declare class AdyenProvider extends PaymentProvider {
+    readonly name = "adyen";
+    readonly supportedCurrencies: string[];
+    private apiKey;
+    private merchantAccount;
+    private liveUrlPrefix?;
+    private webhookSecret?;
+    private sandbox;
+    private baseUrl;
+    constructor(config: AdyenConfig);
+    private apiRequest;
+    createPayment(params: CreatePaymentParams): Promise<PaymentResult>;
+    /**
+     * Adyen subscriptions require recurring tokenization flow (shopperReference + recurring contract).
+     * This is not yet supported by paybridge's simple checkout URL model.
+     * Use Stripe or PayFast for subscriptions.
+     */
+    createSubscription(_params: CreateSubscriptionParams): Promise<SubscriptionResult>;
+    getPayment(id: string): Promise<PaymentResult>;
+    refund(params: RefundParams): Promise<RefundResult>;
+    /**
+     * Parse Adyen webhook notification.
+     * Note: Adyen webhooks contain multiple notificationItems in a batch.
+     * This method returns only the FIRST item (paybridge webhook interface is single-event).
+     * Multi-event batches require custom handling outside paybridge.
+     */
+    parseWebhook(body: any, _headers?: any): WebhookEvent;
+    verifyWebhook(body: string | Buffer, _headers?: any): boolean;
+    getCapabilities(): ProviderCapabilities;
+}
+export {};

package/dist/providers/adyen.js

@@ -0,0 +1,289 @@
+"use strict";
+/**
+ * Adyen payment provider
+ * Global payment platform supporting 150+ countries
+ * @see https://docs.adyen.com/api-explorer/Checkout/71/overview
+ */
+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.AdyenProvider = 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 AdyenProvider extends base_1.PaymentProvider {
+    constructor(config) {
+        super();
+        this.name = 'adyen';
+        this.supportedCurrencies = ['ZAR', 'EUR', 'USD', 'GBP', 'AUD', 'BRL', 'INR', 'NGN'];
+        this.apiKey = config.apiKey;
+        this.merchantAccount = config.merchantAccount;
+        this.liveUrlPrefix = config.liveUrlPrefix;
+        this.webhookSecret = config.webhookSecret;
+        this.sandbox = config.sandbox ?? true;
+        if (this.sandbox) {
+            this.baseUrl = 'https://checkout-test.adyen.com/v71';
+        }
+        else {
+            if (!this.liveUrlPrefix) {
+                throw new Error('Adyen live mode requires liveUrlPrefix');
+            }
+            this.baseUrl = `https://checkout-${this.liveUrlPrefix}.adyenpayments.com/v71`;
+        }
+    }
+    async apiRequest(method, path, data) {
+        const url = `${this.baseUrl}${path}`;
+        const response = await (0, fetch_1.timedFetchOrThrow)(url, {
+            method,
+            headers: {
+                'x-API-key': this.apiKey,
+                'Content-Type': 'application/json',
+            },
+            body: data ? JSON.stringify(data) : undefined,
+        });
+        return (await response.json());
+    }
+    async createPayment(params) {
+        this.validateCurrency(params.currency);
+        const amountInMinorUnits = (0, currency_1.toMinorUnit)(params.amount, params.currency);
+        const [firstName, ...lastNameParts] = params.customer.name.split(' ');
+        const lastName = lastNameParts.join(' ') || firstName;
+        const sessionData = {
+            amount: {
+                value: amountInMinorUnits,
+                currency: params.currency,
+            },
+            merchantAccount: this.merchantAccount,
+            reference: params.reference,
+            returnUrl: params.urls.success,
+            shopperEmail: params.customer.email,
+            shopperName: {
+                firstName,
+                lastName,
+            },
+            countryCode: 'ZA',
+            metadata: {
+                reference: params.reference,
+                ...(params.metadata || {}),
+            },
+        };
+        const response = await this.apiRequest('POST', '/sessions', sessionData);
+        return {
+            id: response.id,
+            checkoutUrl: response.url,
+            status: 'pending',
+            amount: (0, currency_1.toMajorUnit)(response.amount.value, params.currency),
+            currency: response.amount.currency,
+            reference: params.reference,
+            provider: 'adyen',
+            createdAt: new Date().toISOString(),
+            raw: response,
+        };
+    }
+    /**
+     * Adyen subscriptions require recurring tokenization flow (shopperReference + recurring contract).
+     * This is not yet supported by paybridge's simple checkout URL model.
+     * Use Stripe or PayFast for subscriptions.
+     */
+    async createSubscription(_params) {
+        throw new Error('Adyen subscriptions require recurring tokenization flow; not yet supported by paybridge. Use Stripe or PayFast for subscriptions.');
+    }
+    async getPayment(id) {
+        const session = await this.apiRequest('GET', `/sessions/${id}`);
+        let status = 'pending';
+        if (session.status === 'completed') {
+            status = 'completed';
+        }
+        else if (session.status === 'paymentPending' || session.status === 'pending') {
+            status = 'pending';
+        }
+        else if (session.status === 'expired') {
+            status = 'cancelled';
+        }
+        else if (session.status === 'refused' || session.status === 'error') {
+            status = 'failed';
+        }
+        const currency = session.amount?.currency || 'EUR';
+        return {
+            id: session.id,
+            checkoutUrl: session.url || '',
+            status,
+            amount: (0, currency_1.toMajorUnit)(session.amount?.value || 0, currency),
+            currency,
+            reference: session.reference || session.id,
+            provider: 'adyen',
+            createdAt: new Date().toISOString(),
+            raw: session,
+        };
+    }
+    async refund(params) {
+        const refundData = {
+            merchantAccount: this.merchantAccount,
+            reference: `refund-${params.paymentId}-${Date.now()}`,
+        };
+        if (params.amount !== undefined) {
+            refundData.amount = {
+                value: (0, currency_1.toMinorUnit)(params.amount, 'EUR'),
+                currency: 'EUR',
+            };
+        }
+        const response = await this.apiRequest('POST', `/payments/${params.paymentId}/refunds`, refundData);
+        const currency = response.amount?.currency || 'EUR';
+        return {
+            id: response.pspReference,
+            status: response.status === 'received' ? 'pending' : 'completed',
+            amount: (0, currency_1.toMajorUnit)(response.amount?.value || 0, currency),
+            currency,
+            paymentId: params.paymentId,
+            createdAt: new Date().toISOString(),
+            raw: response,
+        };
+    }
+    /**
+     * Parse Adyen webhook notification.
+     * Note: Adyen webhooks contain multiple notificationItems in a batch.
+     * This method returns only the FIRST item (paybridge webhook interface is single-event).
+     * Multi-event batches require custom handling outside paybridge.
+     */
+    parseWebhook(body, _headers) {
+        const event = typeof body === 'string' ? JSON.parse(body) : body;
+        const notificationItems = event.notificationItems || [];
+        if (notificationItems.length === 0) {
+            throw new Error('Adyen webhook contains no notificationItems');
+        }
+        const item = notificationItems[0].NotificationRequestItem;
+        const typeMap = {
+            AUTHORISATION: item.success === 'true' ? 'payment.completed' : 'payment.failed',
+            CANCELLATION: 'payment.cancelled',
+            REFUND: item.success === 'true' ? 'refund.completed' : 'payment.failed',
+        };
+        const eventType = typeMap[item.eventCode] || 'payment.pending';
+        const currency = item.amount?.currency || 'EUR';
+        let payment;
+        let refund;
+        if (item.eventCode === 'AUTHORISATION') {
+            payment = {
+                id: item.pspReference,
+                checkoutUrl: '',
+                status: item.success === 'true' ? 'completed' : 'failed',
+                amount: (0, currency_1.toMajorUnit)(item.amount?.value || 0, currency),
+                currency,
+                reference: item.merchantReference,
+                provider: 'adyen',
+                createdAt: new Date().toISOString(),
+            };
+        }
+        else if (item.eventCode === 'REFUND') {
+            refund = {
+                id: item.pspReference,
+                status: item.success === 'true' ? 'completed' : 'failed',
+                amount: (0, currency_1.toMajorUnit)(item.amount?.value || 0, currency),
+                currency,
+                paymentId: item.originalReference || item.pspReference,
+                createdAt: new Date().toISOString(),
+            };
+        }
+        else if (item.eventCode === 'CANCELLATION') {
+            payment = {
+                id: item.pspReference,
+                checkoutUrl: '',
+                status: 'cancelled',
+                amount: (0, currency_1.toMajorUnit)(item.amount?.value || 0, currency),
+                currency,
+                reference: item.merchantReference,
+                provider: 'adyen',
+                createdAt: new Date().toISOString(),
+            };
+        }
+        return {
+            type: eventType,
+            payment,
+            refund,
+            raw: event,
+        };
+    }
+    verifyWebhook(body, _headers) {
+        if (!this.webhookSecret) {
+            return false;
+        }
+        const event = typeof body === 'string' ? JSON.parse(body) : JSON.parse(body.toString('utf8'));
+        const notificationItems = event.notificationItems || [];
+        if (notificationItems.length === 0) {
+            return false;
+        }
+        const item = notificationItems[0].NotificationRequestItem;
+        const hmacSignature = item.additionalData?.hmacSignature;
+        if (!hmacSignature) {
+            return false;
+        }
+        const signedFields = [
+            item.pspReference || '',
+            item.originalReference || '',
+            item.merchantAccountCode || this.merchantAccount,
+            item.merchantReference || '',
+            String(item.amount?.value || ''),
+            item.amount?.currency || '',
+            item.eventCode || '',
+            item.success || '',
+        ];
+        const signedString = signedFields.join('|');
+        const hmacKey = Buffer.from(this.webhookSecret, 'hex');
+        const computedSig = crypto.createHmac('sha256', hmacKey).update(signedString, 'utf8').digest('base64');
+        try {
+            const computedBuffer = Buffer.from(computedSig, 'utf8');
+            const expectedBuffer = Buffer.from(hmacSignature, 'utf8');
+            if (computedBuffer.length !== expectedBuffer.length) {
+                return false;
+            }
+            return crypto.timingSafeEqual(computedBuffer, expectedBuffer);
+        }
+        catch {
+            return false;
+        }
+    }
+    getCapabilities() {
+        return {
+            fees: {
+                fixed: 0.11,
+                percent: 0.6,
+                currency: 'EUR',
+            },
+            currencies: this.supportedCurrencies,
+            country: 'GLOBAL',
+            avgLatencyMs: 250,
+        };
+    }
+}
+exports.AdyenProvider = AdyenProvider;

package/dist/providers/mercadopago.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Mercado Pago payment provider
+ * Leading payment platform for Latin America
+ * @see https://www.mercadopago.com/developers/en/reference
+ */
+import { PaymentProvider } from './base';
+import { CreatePaymentParams, PaymentResult, CreateSubscriptionParams, SubscriptionResult, RefundParams, RefundResult, WebhookEvent } from '../types';
+import { ProviderCapabilities } from '../routing-types';
+interface MercadoPagoConfig {
+    accessToken: string;
+    webhookSecret?: string;
+    sandbox?: boolean;
+}
+export declare class MercadoPagoProvider extends PaymentProvider {
+    readonly name = "mercadopago";
+    readonly supportedCurrencies: string[];
+    private accessToken;
+    private webhookSecret?;
+    private sandbox;
+    private baseUrl;
+    constructor(config: MercadoPagoConfig);
+    private apiRequest;
+    createPayment(params: CreatePaymentParams): Promise<PaymentResult>;
+    createSubscription(params: CreateSubscriptionParams): Promise<SubscriptionResult>;
+    getPayment(id: string): Promise<PaymentResult>;
+    refund(params: RefundParams): Promise<RefundResult>;
+    /**
+     * Parse Mercado Pago webhook notification.
+     * Note: MP webhooks are notification events that require a follow-up API call to get full payment details.
+     * This method returns a pending event; caller should use getPayment(data.id) to fetch real status.
+     */
+    parseWebhook(body: any, _headers?: any): WebhookEvent;
+    verifyWebhook(body: string | Buffer, headers?: any): boolean;
+    getCapabilities(): ProviderCapabilities;
+}
+export {};

package/dist/providers/mercadopago.js

@@ -0,0 +1,297 @@
+"use strict";
+/**
+ * Mercado Pago payment provider
+ * Leading payment platform for Latin America
+ * @see https://www.mercadopago.com/developers/en/reference
+ */
+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.MercadoPagoProvider = void 0;
+const crypto = __importStar(require("crypto"));
+const base_1 = require("./base");
+const fetch_1 = require("../utils/fetch");
+class MercadoPagoProvider extends base_1.PaymentProvider {
+    constructor(config) {
+        super();
+        this.name = 'mercadopago';
+        this.supportedCurrencies = ['BRL', 'ARS', 'USD', 'MXN', 'COP', 'CLP', 'ZAR'];
+        this.baseUrl = 'https://api.mercadopago.com';
+        this.accessToken = config.accessToken;
+        this.webhookSecret = config.webhookSecret;
+        this.sandbox = config.sandbox ?? this.accessToken.startsWith('TEST-');
+    }
+    async apiRequest(method, path, data) {
+        const url = `${this.baseUrl}${path}`;
+        const response = await (0, fetch_1.timedFetch)(url, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.accessToken}`,
+                'Content-Type': 'application/json',
+            },
+            body: data ? JSON.stringify(data) : undefined,
+        });
+        const json = await response.json();
+        if (!response.ok) {
+            const message = json.message || json.error || `Mercado Pago API error (${method} ${path}): ${response.status}`;
+            throw new Error(message);
+        }
+        return json;
+    }
+    async createPayment(params) {
+        this.validateCurrency(params.currency);
+        const [firstName, ...lastNameParts] = params.customer.name.split(' ');
+        const lastName = lastNameParts.join(' ') || firstName;
+        const metadata = {
+            reference: params.reference,
+            ...(params.metadata || {}),
+        };
+        const requestBody = {
+            items: [
+                {
+                    title: params.description || params.reference,
+                    quantity: 1,
+                    unit_price: params.amount,
+                    currency_id: params.currency,
+                },
+            ],
+            payer: {
+                email: params.customer.email,
+                name: firstName,
+                surname: lastName,
+            },
+            external_reference: params.reference,
+            back_urls: {
+                success: params.urls.success,
+                failure: params.urls.cancel,
+                pending: params.urls.success,
+            },
+            notification_url: params.urls.webhook,
+            auto_return: 'approved',
+            metadata,
+        };
+        const response = await this.apiRequest('POST', '/checkout/preferences', requestBody);
+        const checkoutUrl = this.sandbox ? response.sandbox_init_point : response.init_point;
+        return {
+            id: response.id,
+            checkoutUrl,
+            status: 'pending',
+            amount: params.amount,
+            currency: params.currency.toUpperCase(),
+            reference: params.reference,
+            provider: 'mercadopago',
+            createdAt: new Date().toISOString(),
+            raw: response,
+        };
+    }
+    async createSubscription(params) {
+        this.validateCurrency(params.currency);
+        let frequency;
+        let frequencyType;
+        switch (params.interval) {
+            case 'weekly':
+                frequency = 7;
+                frequencyType = 'days';
+                break;
+            case 'monthly':
+                frequency = 1;
+                frequencyType = 'months';
+                break;
+            case 'yearly':
+                frequency = 12;
+                frequencyType = 'months';
+                break;
+        }
+        const requestBody = {
+            reason: params.description || params.reference,
+            auto_recurring: {
+                frequency,
+                frequency_type: frequencyType,
+                transaction_amount: params.amount,
+                currency_id: params.currency,
+            },
+            payer_email: params.customer.email,
+            back_url: params.urls.success,
+            external_reference: params.reference,
+        };
+        const response = await this.apiRequest('POST', '/preapproval', requestBody);
+        return {
+            id: response.id,
+            checkoutUrl: response.init_point,
+            status: 'pending',
+            amount: params.amount,
+            currency: params.currency.toUpperCase(),
+            interval: params.interval,
+            reference: params.reference,
+            provider: 'mercadopago',
+            startsAt: params.startDate,
+            createdAt: new Date().toISOString(),
+            raw: response,
+        };
+    }
+    async getPayment(id) {
+        const response = await this.apiRequest('GET', `/v1/payments/search?external_reference=${encodeURIComponent(id)}`);
+        if (!response.results || response.results.length === 0) {
+            return {
+                id,
+                checkoutUrl: '',
+                status: 'pending',
+                amount: 0,
+                currency: 'BRL',
+                reference: id,
+                provider: 'mercadopago',
+                createdAt: new Date().toISOString(),
+                raw: response,
+            };
+        }
+        const payment = response.results[0];
+        const currency = (payment.currency_id || 'BRL').toUpperCase();
+        let status = 'pending';
+        if (payment.status === 'approved') {
+            status = 'completed';
+        }
+        else if (payment.status === 'rejected') {
+            status = 'failed';
+        }
+        else if (payment.status === 'cancelled') {
+            status = 'cancelled';
+        }
+        return {
+            id: payment.id?.toString() || id,
+            checkoutUrl: '',
+            status,
+            amount: payment.transaction_amount || 0,
+            currency,
+            reference: payment.external_reference || id,
+            provider: 'mercadopago',
+            createdAt: new Date(payment.date_created || Date.now()).toISOString(),
+            raw: response,
+        };
+    }
+    async refund(params) {
+        const refundData = {};
+        if (params.amount !== undefined) {
+            refundData.amount = params.amount;
+        }
+        const response = await this.apiRequest('POST', `/v1/payments/${params.paymentId}/refunds`, refundData);
+        const currency = (response.payment?.currency_id || 'BRL').toUpperCase();
+        return {
+            id: response.id?.toString() || response.refund_id?.toString(),
+            status: response.status === 'approved' ? 'completed' : 'pending',
+            amount: response.amount || 0,
+            currency,
+            paymentId: params.paymentId,
+            createdAt: new Date(response.date_created || Date.now()).toISOString(),
+            raw: response,
+        };
+    }
+    /**
+     * Parse Mercado Pago webhook notification.
+     * Note: MP webhooks are notification events that require a follow-up API call to get full payment details.
+     * This method returns a pending event; caller should use getPayment(data.id) to fetch real status.
+     */
+    parseWebhook(body, _headers) {
+        const event = typeof body === 'string' ? JSON.parse(body) : body;
+        const eventType = 'payment.pending';
+        return {
+            type: eventType,
+            payment: {
+                id: event.data?.id?.toString() || '',
+                checkoutUrl: '',
+                status: 'pending',
+                amount: 0,
+                currency: 'BRL',
+                reference: '',
+                provider: 'mercadopago',
+                createdAt: new Date().toISOString(),
+            },
+            raw: event,
+        };
+    }
+    verifyWebhook(body, headers) {
+        if (!this.webhookSecret) {
+            return false;
+        }
+        const signature = headers?.['x-signature'] || headers?.['X-Signature'];
+        if (!signature) {
+            return false;
+        }
+        const parts = signature.split(',').reduce((acc, part) => {
+            const [key, value] = part.split('=');
+            if (key && value) {
+                acc[key.trim()] = value.trim();
+            }
+            return acc;
+        }, {});
+        const ts = parts.ts;
+        const v1 = parts.v1;
+        if (!ts || !v1) {
+            return false;
+        }
+        const timestampNum = parseInt(ts, 10);
+        const now = Math.floor(Date.now() / 1000);
+        if (now - timestampNum > 300) {
+            return false;
+        }
+        const requestId = headers?.['x-request-id'] || headers?.['X-Request-Id'];
+        const eventData = typeof body === 'string' ? JSON.parse(body) : body;
+        const dataId = eventData.data?.id || '';
+        const template = `id:${dataId};request-id:${requestId};ts:${ts};`;
+        const computedSig = crypto.createHmac('sha256', this.webhookSecret).update(template, 'utf8').digest('hex');
+        try {
+            const computedBuffer = Buffer.from(computedSig, 'hex');
+            const expectedBuffer = Buffer.from(v1, 'hex');
+            if (computedBuffer.length !== expectedBuffer.length) {
+                return false;
+            }
+            return crypto.timingSafeEqual(computedBuffer, expectedBuffer);
+        }
+        catch {
+            return false;
+        }
+    }
+    getCapabilities() {
+        return {
+            fees: {
+                fixed: 0,
+                percent: 4.99,
+                currency: 'BRL',
+            },
+            currencies: this.supportedCurrencies,
+            country: 'BR',
+            avgLatencyMs: 700,
+        };
+    }
+}
+exports.MercadoPagoProvider = MercadoPagoProvider;

package/dist/providers/razorpay.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Razorpay payment provider
+ * Leading payment gateway for India
+ * @see https://razorpay.com/docs/api
+ */
+import { PaymentProvider } from './base';
+import { CreatePaymentParams, PaymentResult, CreateSubscriptionParams, SubscriptionResult, RefundParams, RefundResult, WebhookEvent } from '../types';
+import { ProviderCapabilities } from '../routing-types';
+interface RazorpayConfig {
+    keyId: string;
+    keySecret: string;
+    webhookSecret?: string;
+    sandbox?: boolean;
+}
+export declare class RazorpayProvider extends PaymentProvider {
+    readonly name = "razorpay";
+    readonly supportedCurrencies: string[];
+    private keyId;
+    private keySecret;
+    private webhookSecret?;
+    private sandbox;
+    private baseUrl;
+    constructor(config: RazorpayConfig);
+    private apiRequest;
+    createPayment(params: CreatePaymentParams): Promise<PaymentResult>;
+    createSubscription(params: CreateSubscriptionParams): Promise<SubscriptionResult>;
+    getPayment(id: string): Promise<PaymentResult>;
+    refund(params: RefundParams): Promise<RefundResult>;
+    parseWebhook(body: any, _headers?: any): WebhookEvent;
+    /**
+     * Verify Razorpay webhook signature using HMAC-SHA256.
+     * Note: Razorpay does not include timestamp in webhook signature (no replay protection).
+     */
+    verifyWebhook(body: string | Buffer, headers?: any): boolean;
+    getCapabilities(): ProviderCapabilities;
+}
+export {};

package/dist/providers/razorpay.js

@@ -0,0 +1,328 @@
+"use strict";
+/**
+ * Razorpay payment provider
+ * Leading payment gateway for India
+ * @see https://razorpay.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.RazorpayProvider = 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 RazorpayProvider extends base_1.PaymentProvider {
+    constructor(config) {
+        super();
+        this.name = 'razorpay';
+        this.supportedCurrencies = ['INR', 'USD', 'EUR', 'GBP', 'SGD', 'AED', 'AUD'];
+        this.baseUrl = 'https://api.razorpay.com/v1';
+        this.keyId = config.keyId;
+        this.keySecret = config.keySecret;
+        this.webhookSecret = config.webhookSecret;
+        this.sandbox = config.sandbox ?? this.keyId.startsWith('rzp_test_');
+    }
+    async apiRequest(method, path, data) {
+        const url = `${this.baseUrl}${path}`;
+        const authString = Buffer.from(`${this.keyId}:${this.keySecret}`).toString('base64');
+        const response = await (0, fetch_1.timedFetch)(url, {
+            method,
+            headers: {
+                Authorization: `Basic ${authString}`,
+                'Content-Type': 'application/json',
+            },
+            body: data ? JSON.stringify(data) : undefined,
+        });
+        const json = await response.json();
+        if (!response.ok) {
+            const message = json.error?.description || `Razorpay API error (${method} ${path}): ${response.status}`;
+            throw new Error(message);
+        }
+        return json;
+    }
+    async createPayment(params) {
+        this.validateCurrency(params.currency);
+        const amountInMinorUnits = (0, currency_1.toMinorUnit)(params.amount, params.currency);
+        const orderData = {
+            amount: amountInMinorUnits,
+            currency: params.currency,
+            receipt: params.reference,
+            notes: {
+                reference: params.reference,
+                customerEmail: params.customer.email,
+                ...(params.metadata || {}),
+            },
+        };
+        const order = await this.apiRequest('POST', '/orders', orderData);
+        const checkoutUrl = `https://api.razorpay.com/v1/checkout/embedded?key_id=${this.keyId}&order_id=${order.id}`;
+        return {
+            id: order.id,
+            checkoutUrl,
+            status: 'pending',
+            amount: (0, currency_1.toMajorUnit)(order.amount, params.currency),
+            currency: order.currency,
+            reference: params.reference,
+            provider: 'razorpay',
+            createdAt: new Date(order.created_at * 1000).toISOString(),
+            raw: order,
+        };
+    }
+    async createSubscription(params) {
+        this.validateCurrency(params.currency);
+        const amountInMinorUnits = (0, currency_1.toMinorUnit)(params.amount, params.currency);
+        const intervalMap = {
+            weekly: 'weekly',
+            monthly: 'monthly',
+            yearly: 'yearly',
+        };
+        const planData = {
+            period: intervalMap[params.interval],
+            interval: 1,
+            item: {
+                name: params.description || params.reference,
+                amount: amountInMinorUnits,
+                currency: params.currency,
+            },
+        };
+        const plan = await this.apiRequest('POST', '/plans', planData);
+        const subscriptionData = {
+            plan_id: plan.id,
+            total_count: 12,
+            customer_notify: 1,
+            notes: {
+                reference: params.reference,
+                ...(params.metadata || {}),
+            },
+        };
+        const subscription = await this.apiRequest('POST', '/subscriptions', subscriptionData);
+        const checkoutUrl = `https://api.razorpay.com/v1/checkout/embedded?key_id=${this.keyId}&subscription_id=${subscription.id}`;
+        return {
+            id: subscription.id,
+            checkoutUrl,
+            status: 'pending',
+            amount: (0, currency_1.toMajorUnit)(subscription.plan_id ? amountInMinorUnits : 0, params.currency),
+            currency: params.currency,
+            interval: params.interval,
+            reference: params.reference,
+            provider: 'razorpay',
+            startsAt: params.startDate,
+            createdAt: new Date(subscription.created_at * 1000).toISOString(),
+            raw: subscription,
+        };
+    }
+    async getPayment(id) {
+        const paymentsResponse = await this.apiRequest('GET', `/orders/${id}/payments`);
+        if (!paymentsResponse.items || paymentsResponse.items.length === 0) {
+            const order = await this.apiRequest('GET', `/orders/${id}`);
+            const currency = order.currency || 'INR';
+            return {
+                id: order.id,
+                checkoutUrl: '',
+                status: 'pending',
+                amount: (0, currency_1.toMajorUnit)(order.amount || 0, currency),
+                currency,
+                reference: order.receipt || id,
+                provider: 'razorpay',
+                createdAt: new Date(order.created_at * 1000).toISOString(),
+                raw: order,
+            };
+        }
+        const payment = paymentsResponse.items[0];
+        const currency = payment.currency || 'INR';
+        let status = 'pending';
+        if (payment.status === 'captured') {
+            status = 'completed';
+        }
+        else if (payment.status === 'authorized') {
+            status = 'pending';
+        }
+        else if (payment.status === 'failed') {
+            status = 'failed';
+        }
+        else if (payment.status === 'refunded') {
+            status = 'refunded';
+        }
+        return {
+            id: payment.id,
+            checkoutUrl: '',
+            status,
+            amount: (0, currency_1.toMajorUnit)(payment.amount || 0, currency),
+            currency,
+            reference: payment.notes?.reference || payment.order_id || id,
+            provider: 'razorpay',
+            createdAt: new Date(payment.created_at * 1000).toISOString(),
+            raw: paymentsResponse,
+        };
+    }
+    async refund(params) {
+        let paymentId = params.paymentId;
+        if (paymentId.startsWith('order_')) {
+            const paymentsResponse = await this.apiRequest('GET', `/orders/${paymentId}/payments`);
+            if (paymentsResponse.items && paymentsResponse.items.length > 0) {
+                paymentId = paymentsResponse.items[0].id;
+            }
+            else {
+                throw new Error('Order has no payments to refund');
+            }
+        }
+        const refundData = {
+            speed: 'normal',
+        };
+        if (params.amount !== undefined) {
+            refundData.amount = (0, currency_1.toMinorUnit)(params.amount, 'INR');
+        }
+        if (params.reason) {
+            refundData.notes = { reason: params.reason };
+        }
+        const response = await this.apiRequest('POST', `/payments/${paymentId}/refund`, refundData);
+        const currency = response.currency || 'INR';
+        return {
+            id: response.id,
+            status: response.status === 'processed' ? 'completed' : 'pending',
+            amount: (0, currency_1.toMajorUnit)(response.amount || 0, currency),
+            currency,
+            paymentId: params.paymentId,
+            createdAt: new Date(response.created_at * 1000).toISOString(),
+            raw: response,
+        };
+    }
+    parseWebhook(body, _headers) {
+        const event = typeof body === 'string' ? JSON.parse(body) : body;
+        const typeMap = {
+            'payment.captured': 'payment.completed',
+            'payment.failed': 'payment.failed',
+            'subscription.activated': 'subscription.created',
+            'subscription.cancelled': 'subscription.cancelled',
+            'refund.created': 'refund.completed',
+            'refund.processed': 'refund.completed',
+        };
+        const eventType = typeMap[event.event] || 'payment.pending';
+        const data = event.payload?.payment?.entity || event.payload?.subscription?.entity || event.payload?.refund?.entity || {};
+        let payment;
+        let subscription;
+        let refund;
+        if (event.event.startsWith('payment.')) {
+            const currency = (data.currency || 'INR').toUpperCase();
+            let status = 'pending';
+            if (event.event === 'payment.captured') {
+                status = 'completed';
+            }
+            else if (event.event === 'payment.failed') {
+                status = 'failed';
+            }
+            payment = {
+                id: data.id || '',
+                checkoutUrl: '',
+                status,
+                amount: (0, currency_1.toMajorUnit)(data.amount || 0, currency),
+                currency,
+                reference: data.order_id || data.id || '',
+                provider: 'razorpay',
+                createdAt: new Date((data.created_at || Date.now() / 1000) * 1000).toISOString(),
+            };
+        }
+        else if (event.event.startsWith('subscription.')) {
+            const currency = 'INR';
+            subscription = {
+                id: data.id || '',
+                checkoutUrl: '',
+                status: event.event === 'subscription.cancelled' ? 'cancelled' : 'active',
+                amount: (0, currency_1.toMajorUnit)(data.plan_id?.amount || 0, currency),
+                currency,
+                interval: 'monthly',
+                reference: data.notes?.reference || data.id || '',
+                provider: 'razorpay',
+                createdAt: new Date((data.created_at || Date.now() / 1000) * 1000).toISOString(),
+            };
+        }
+        else if (event.event.startsWith('refund.')) {
+            const currency = (data.currency || 'INR').toUpperCase();
+            refund = {
+                id: data.id || '',
+                status: event.event === 'refund.processed' ? 'completed' : 'pending',
+                amount: (0, currency_1.toMajorUnit)(data.amount || 0, currency),
+                currency,
+                paymentId: data.payment_id || '',
+                createdAt: new Date((data.created_at || Date.now() / 1000) * 1000).toISOString(),
+            };
+        }
+        return {
+            type: eventType,
+            payment,
+            subscription,
+            refund,
+            raw: event,
+        };
+    }
+    /**
+     * Verify Razorpay webhook signature using HMAC-SHA256.
+     * Note: Razorpay does not include timestamp in webhook signature (no replay protection).
+     */
+    verifyWebhook(body, headers) {
+        if (!this.webhookSecret) {
+            return false;
+        }
+        const signature = headers?.['x-razorpay-signature'] || headers?.['X-Razorpay-Signature'];
+        if (!signature) {
+            return false;
+        }
+        const rawBody = typeof body === 'string' ? body : body.toString('utf8');
+        const computedSig = crypto.createHmac('sha256', this.webhookSecret).update(rawBody, 'utf8').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: 0,
+                percent: 2.0,
+                currency: 'INR',
+            },
+            currencies: this.supportedCurrencies,
+            country: 'IN',
+            avgLatencyMs: 500,
+        };
+    }
+}
+exports.RazorpayProvider = RazorpayProvider;

package/dist/types.d.ts

@@ -1,7 +1,7 @@
 /**
  * PayBridge — Unified payment SDK types
  */
-export type Provider = 'softycomp' | 'yoco' | 'ozow' | 'payfast' | 'paystack' | 'stripe' | 'peach' | 'flutterwave';
+export type Provider = 'softycomp' | 'yoco' | 'ozow' | 'payfast' | 'paystack' | 'stripe' | 'peach' | 'flutterwave' | 'adyen' | 'mercadopago' | 'razorpay';
 export type PaymentStatus = 'pending' | 'completed' | 'failed' | 'cancelled' | 'refunded';
 export type SubscriptionInterval = 'weekly' | 'monthly' | 'yearly';
 export type Currency = 'ZAR' | 'USD' | 'EUR' | 'GBP' | 'NGN' | 'KES' | 'UGX' | 'GHS' | string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paybridge",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "One API for fiat + crypto payments. Multi-provider routing, automatic failover, MoonPay on/off-ramp. SA-first, global-ready.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -28,7 +28,12 @@
     "payment-integration",
     "unified-api",
     "zar",
-    "payment-sdk"
+    "payment-sdk",
+    "adyen",
+    "mercadopago",
+    "razorpay",
+    "india",
+    "latam"
   ],
   "author": "Kobie Wentzel",
   "license": "MIT",