API Reference

PaymentGatewayManager

The main class that manages multiple payment gateways.

processPayment(gatewayName: string, amount: number, currency: string, metadata?: Record<string, unknown>)

Creates a payment using the specified gateway.

const response = await manager.processPayment("stripe", 100, "usd", {
  description: "Premium subscription",
  orderId: "order_123",
});

Parameters:

• gatewayName - Name of the registered gateway
• amount - Payment amount in smallest currency unit
• currency - Three-letter currency code
• metadata - Optional payment metadata

Returns: Promise<PaymentResponseV2>

processRefund(gatewayName: string, transactionId: string, amount?: number)

Processes a refund for a previous payment.

const refund = await manager.processRefund("stripe", "pi_xxx", 50);

Parameters:

• gatewayName - Name of the registered gateway
• transactionId - Original payment transaction ID
• amount - Optional partial refund amount

Returns: Promise<RefundResponseV2>

verifyPayment(gatewayName: string, transactionId: string)

Verifies the status and validity of a payment.

const verification = await manager.verifyPayment("stripe", "pi_xxx");

Parameters:

• gatewayName - Name of the registered gateway
• transactionId - Payment transaction ID to verify

Returns: Promise<PaymentVerification>

capturePayment(gatewayName: string, orderId: string)

Captures a previously authorized payment.

const capture = await manager.capturePayment("stripe", "pi_xxx");

Parameters:

• gatewayName - Name of the registered gateway
• orderId - Payment intent or order ID to capture

Returns: Promise<PaymentResponseV2>

---

BasePaymentGateway

Abstract base class that all payment gateways must extend.

Constructor

constructor(config: GatewayConfig)

Parameters:

• config - Gateway configuration object

Abstract Methods

processPaymentRequest(amount: number, currency: string, metadata?: Record<string, unknown>)

Abstract method for processing payment requests.

Parameters:

• amount - Payment amount
• currency - Currency code
• metadata - Optional metadata

Returns: Promise<PaymentResponseV2>

processRefund(transactionId: string, amount?: number)

Abstract method for processing refunds.

Parameters:

• transactionId - Original transaction ID
• amount - Optional refund amount

Returns: Promise<RefundResponseV2>

verifyPayment(transactionId: string)

Abstract method for verifying payments.

Parameters:

• transactionId - Transaction ID to verify

Returns: Promise<PaymentVerification>

---

Interfaces

GatewayConfig

Configuration object for payment gateways.

interface GatewayConfig {
  apiKey: string;
  apiSecret?: string;
  webhookSecret?: string;
  sandbox?: boolean;
  returnUrl?: string; // PayPal specific
  cancelUrl?: string; // PayPal specific
  webhookId?: string; // PayPal specific
  maxRetries?: number;
  retryDelay?: number;
  timeout?: number;
}

PaymentResponseV2

Response object for payment operations.

interface PaymentResponseV2 {
  success: boolean;
  transactionId?: string;
  orderId?: string;
  status?: "pending" | "completed" | "failed" | "cancelled";
  amount?: number;
  currency?: string;
  paymentUrl?: string; // For redirect-based payments
  error?: {
    code: string;
    message: string;
    details?: any;
  };
  gatewayResponse?: any;
  metadata?: Record<string, unknown>;
}

RefundResponseV2

Response object for refund operations.

interface RefundResponseV2 {
  success: boolean;
  refundId?: string;
  transactionId?: string;
  amount?: number;
  currency?: string;
  status?: "pending" | "completed" | "failed";
  error?: {
    code: string;
    message: string;
    details?: any;
  };
  gatewayResponse?: any;
}

PaymentVerification

Response object for payment verification.

interface PaymentVerification {
  isValid: boolean;
  transactionId: string;
  status: "pending" | "completed" | "failed" | "cancelled" | "expired";
  amount?: number;
  currency?: string;
  paymentMethod?: string;
  createdAt?: Date;
  completedAt?: Date;
  error?: {
    code: string;
    message: string;
  };
  gatewayResponse?: any;
}

---

Utility Functions

createGateways(configs: GatewayConfigInput[])

Helper function to create multiple gateway instances.

interface GatewayConfigInput {
  gateway: "stripe" | "paypal" | "razorpay";
  config: GatewayConfig;
}

const { stripe, paypal} = createGateways([
  { gateway: "stripe", config: stripeConfig },
  { gateway: "paypal", config: paypalConfig },
  {gateway: "razorpay", config : razorpayConfig},
]);

Returns: Object with gateway instances as properties

---

Error Codes

Common error codes returned by the gateways:

Code	Description
card_declined	Card was declined by the issuer
insufficient_funds	Insufficient funds in account
invalid_card	Invalid card number or details
expired_card	Card has expired
invalid_amount	Invalid payment amount
gateway_error	Internal gateway error
network_error	Network connectivity issue
authentication_failed	Invalid API credentials
webhook_verification_failed	Webhook signature verification failed

---

Event Types

Webhook event types supported across gateways:

Event	Description
payment.created	Payment was created
payment.completed	Payment was successfully completed
payment.failed	Payment failed
payment.cancelled	Payment was cancelled
refund.created	Refund was initiated
refund.completed	Refund was completed
refund.failed	Refund failed