# Payment Rails Specification

## Overview

Payment rails for on-ramp/off-ramp, ACH, wire, and card processing integration.

## On-Ramp Integration

### Providers

**Crypto On-Ramp**:
- MoonPay
- Ramp
- Transak
- Others

### Integration Pattern

**Flow**:
1. User initiates on-ramp
2. Redirect to provider or embed widget
3. User completes purchase
4. Provider webhook notifies completion
5. Credit customer account

## Off-Ramp Integration

### Providers

Similar to on-ramp providers

### Flow

1. User initiates withdrawal
2. Verify balance and limits
3. Initiate withdrawal with provider
4. Provider processes withdrawal
5. Debit customer account
6. Monitor completion

## ACH/Wire/Card Rails

### ACH Processing

**Integration**: Banking partner or payment processor
**Use Cases**: Fiat deposits/withdrawals
**Processing Time**: 1-3 business days

### Wire Transfers

**Integration**: Banking partner
**Use Cases**: Large fiat transfers
**Processing Time**: Same day or next day

### Card Processing

**Integration**: Payment processor (Stripe, etc.)
**Use Cases**: Card purchases
**Processing Time**: Instant (authorization), 1-3 days (settlement)

## Settlement Monitoring

### Monitoring Process

**Track**:
- Transaction status
- Settlement status
- Failed transactions
- Disputes/chargebacks

### Alerts

**Trigger Conditions**:
- Settlement failures
- Unusual delays
- Disputes
- Chargebacks

## Payment Status Tracking

### Status States

- `initiated`: Payment initiated
- `pending`: Pending processing
- `processing`: Being processed
- `completed`: Successfully completed
- `failed`: Processing failed
- `refunded`: Refunded
- `disputed`: Under dispute

## References

- Account & Ledger: See `account-ledger.md`
- Compliance: See `compliance-dashboards.md`