Agent Payment Rail

Universal payment infrastructure for AI Agents. Support multiple payment providers (Stripe, PayPal, etc.) with a unified API.

Features

• Multi-Provider Support - Stripe, PayPal, and more
• Unified API - Single interface for all payment providers
• Type-Safe - Full TypeScript support
• Agent-Friendly - Designed for AI agent integration
• CLI Tool - Command-line interface for quick operations
• OpenClaw Skill - Ready-to-use skill definition

Quick Start

Installation

npm install openclaw-agent-payment-rail

Basic Usage

import { PaymentRail } from 'openclaw-agent-payment-rail';

const rail = new PaymentRail();

// Initialize with Stripe
await rail.initialize({
  provider: 'stripe',
  apiKey: process.env.STRIPE_API_KEY,
});

// Create a payment
const payment = await rail.createPayment({
  amount: 99.99,
  currency: 'USD',
  description: 'Premium subscription',
});

console.log(`Payment created: ${payment.transactionId}`);
console.log(`Status: ${payment.status}`);

Supported Providers

| Provider | Status | Features | |----------|--------|----------| | Stripe | ✅ Full | Payments, Refunds, Cancellations | | PayPal | 🚧 Mock | Coming soon | | Alipay | 📋 Planned | - | | WeChat Pay | 📋 Planned | - |

API Reference

PaymentRail

initialize(config: PaymentConfig): Promise<void>

Initialize a payment provider.

await rail.initialize({
  provider: 'stripe',
  apiKey: 'sk_test_...',
  environment: 'sandbox', // or 'production'
});

createPayment(request: PaymentRequest): Promise<PaymentResponse>

Create a new payment.

const payment = await rail.createPayment({
  amount: 100.00,
  currency: 'USD',
  description: 'Product purchase',
  metadata: {
    orderId: 'order_123',
    customerId: 'user_456',
  },
});

getTransaction(transactionId: string): Promise<Transaction>

Get transaction details.

const transaction = await rail.getTransaction('pi_123456');
console.log(`Status: ${transaction.status}`);

refund(request: RefundRequest): Promise<RefundResponse>

Refund a payment.

const refund = await rail.refund({
  transactionId: 'pi_123456',
  amount: 50.00, // Partial refund (optional)
  reason: 'Customer request',
});

cancelPayment(transactionId: string): Promise<boolean>

Cancel a pending payment.

const cancelled = await rail.cancelPayment('pi_123456');

Types

type PaymentProvider = 'stripe' | 'paypal' | 'alipay' | 'wechat';
type Currency = 'USD' | 'EUR' | 'GBP' | 'CNY' | 'JPY';
type TransactionStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'refunded' | 'cancelled';

interface PaymentRequest {
  amount: number;
  currency: Currency;
  description: string;
  metadata?: Record<string, any>;
  customerId?: string;
}

interface PaymentResponse {
  transactionId: string;
  status: TransactionStatus;
  amount: number;
  currency: Currency;
  provider: PaymentProvider;
  createdAt: Date;
}

interface Transaction {
  id: string;
  provider: PaymentProvider;
  amount: number;
  currency: Currency;
  status: TransactionStatus;
  description: string;
  createdAt: Date;
  updatedAt: Date;
}

CLI Usage

# Install globally
npm install -g openclaw-agent-payment-rail

# The CLI provides two commands:
# - openclaw-agent-payment-rail (full command)
# - agent-payment-rail (short alias)

# Initialize provider
agent-payment-rail init stripe
export STRIPE_API_KEY="sk_test_..."

# Create payment
agent-payment-rail pay 99.99 USD --desc "Premium plan"

# Check status
agent-payment-rail status pi_123456

# Refund
agent-payment-rail refund pi_123456

# Cancel
agent-payment-rail cancel pi_123456

# List providers
agent-payment-rail providers

Agent Integration

OpenClaw Skill

Install the skill:

clawhub install agent-payment-rail

Use in your agent:

// Agent can now use payment tools
agent.tools.create_payment({
  amount: 99.99,
  currency: 'USD',
  description: 'Premium subscription',
});

agent.tools.get_transaction({
  transaction_id: 'pi_123456',
});

agent.tools.refund_payment({
  transaction_id: 'pi_123456',
  reason: 'Customer request',
});

Custom Integration

import { PaymentRail } from 'openclaw-agent-payment-rail';

// Create agent tool wrapper
async function agentCreatePayment(params: {
  amount: number;
  currency: string;
  description: string;
}) {
  const rail = new PaymentRail();
  await rail.initialize({
    provider: 'stripe',
    apiKey: process.env.STRIPE_API_KEY,
  });

  const payment = await rail.createPayment(params);

  return {
    success: true,
    transactionId: payment.transactionId,
    status: payment.status,
    message: `Payment created: ${payment.transactionId}`,
  };
}

Examples

See examples/ directory for complete examples:

• basic-usage.ts - Basic payment flow
• multi-provider.ts - Using multiple providers
• agent-integration.ts - AI agent integration

Environment Variables

# Stripe
STRIPE_API_KEY=sk_test_...

# PayPal (coming soon)
PAYPAL_CLIENT_ID=...
PAYPAL_CLIENT_SECRET=...

# Alipay (planned)
ALIPAY_APP_ID=...
ALIPAY_PRIVATE_KEY=...

# WeChat Pay (planned)
WECHAT_MERCHANT_ID=...
WECHAT_API_KEY=...

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run examples
tsx examples/basic-usage.ts

Use Cases

E-commerce Agent

// Agent handles customer purchases
const payment = await rail.createPayment({
  amount: orderTotal,
  currency: 'USD',
  description: `Order #${orderId}`,
  metadata: { orderId, items },
});

Subscription Service

// Agent manages subscriptions
const payment = await rail.createPayment({
  amount: 29.99,
  currency: 'USD',
  description: 'Monthly subscription',
  metadata: { plan: 'pro', userId },
});

Refund Automation

// Agent processes refund requests
const refund = await rail.refund({
  transactionId: payment.transactionId,
  reason: 'Defective product',
});

Security

• Never commit API keys to version control
• Use environment variables for sensitive data
• Use sandbox/test mode for development
• Validate all payment amounts and currencies
• Implement proper error handling
• Log all transactions for audit trail

Roadmap

• [x] Stripe integration
• [ ] PayPal integration (full)
• [ ] Alipay integration
• [ ] WeChat Pay integration
• [ ] Webhook handling
• [ ] Recurring payments
• [ ] Subscription management
• [ ] Invoice generation
• [ ] Payment analytics
• [ ] Multi-currency conversion

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

License

MIT License - see LICENSE

Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Built with ❤️ for AI Agents