@payments-platform/adapters

Payment vendor adapters for the payments-platform ecosystem.

Overview

This package contains vendor-specific payment adapters that implement the standardized PaymentVendorInterface. Each adapter handles the integration with a specific payment provider (Mesh, IronPay, etc.) while maintaining a consistent interface for the UI components.

Architecture

Plugin System

• Vendor Agnostic: All adapters implement the same interface
• Hot Swappable: Switch vendors in <2 hours via configuration
• Isolated: Each vendor adapter is completely independent
• Type Safe: Full TypeScript interfaces ensure compatibility

Core Interface

All onramp adapters must implement OnrampAdapter:

interface OnrampAdapter {
  initiate(request: OnrampRequest): Promise<OnrampResponse>;
  getStatus(vendorTxId: string): Promise<OnrampStatus>;
  parseWebhook(rawPayload: object): Promise<ParsedWebhook>;
}

Available Onramp Adapters

MeshAdapter

• Status: 🚧 Ready for implementation
• Type: Onramp (fiat-to-crypto)
• Methods: Crypto payments via wallet and exchanges
• Currencies: BTC, ETH, USDC, USDT
• Integration: Uses Mesh Connect API

Future Adapters

• IronPay: Onramp via ACH bank transfers
• Stripe: Onramp via credit/debit cards
• Coinbase: Onramp via Coinbase Pay

Usage

import { MeshAdapter } from '@payments-platform/adapters';

// Configure adapter
const meshAdapter = new MeshAdapter();
meshAdapter.configure({
  apiKey: 'your-mesh-api-key',
  environment: 'production'
});

// Use with payments-core
import { PaymentWidget } from '@payments-platform/core';

<PaymentWidget
  adapters={[meshAdapter]}
  onSuccess={handleSuccess}
  onError={handleError}
/>

Creating New Adapters

1. Implement the Interface

import { PaymentVendorInterface } from './shared/PaymentVendorInterface';

export class YourVendorAdapter implements PaymentVendorInterface {
  readonly vendorId = 'your-vendor';
  readonly vendorName = 'Your Vendor';
  
  // Implement all required methods...
}

2. Add to Registry

// The registry will auto-discover adapters
export { YourVendorAdapter } from './your-vendor/YourVendorAdapter';

3. Follow the Patterns

• Use async/await for all operations
• Handle errors gracefully with proper error codes
• Implement proper cleanup in destroy()
• Support health checking for failover scenarios

Team Responsibilities

Integration Team: Works in this package to implement:

• Vendor-specific API integrations
• Authentication and credential management
• Payment flow implementations
• Error handling and retry logic
• Webhook processing
• Health monitoring

UI Team: Consumes the interfaces from this package but doesn't modify implementations.

Development

# Install dependencies
pnpm install

# Run tests for all adapters
pnpm test

# Test specific adapter
pnpm test mesh

# Build package
pnpm build

Testing

Each adapter includes comprehensive tests:

# Unit tests
pnpm test:unit

# Integration tests (requires test credentials)
pnpm test:integration

# Mock tests (no real API calls)
pnpm test:mock

Configuration

Adapters are configured via environment variables or runtime config:

// Environment-based config
const adapter = new MeshAdapter();
adapter.configure({
  apiKey: process.env.MESH_API_KEY,
  environment: process.env.NODE_ENV
});

// Or runtime config
adapter.configure({
  apiKey: 'runtime-key',
  baseUrl: 'custom-url'
});

Error Handling

All adapters follow standardized error patterns:

interface PaymentError {
  code: string;           // VENDOR_UNAVAILABLE, INSUFFICIENT_FUNDS, etc.
  message: string;        // User-friendly message
  details?: any;          // Additional context
  timestamp: string;      // ISO 8601
  requestId: string;      // For tracking
}

Status

🚧 Foundation Complete - Core interfaces established, vendor implementations ready for development.

Dependencies

• TypeScript 5+
• Node.js 18+ (for integration tests)
• Vendor SDKs (added per adapter as needed)