Rails Guide

Rails are the foundation of the Swipelux transfer system. Each rail represents a type of payment method for moving value, while providers are the actual services that support those payment method types.

Understanding Rails vs Providers

Our flexible architecture separates what you want to achieve (the rail/payment method type) from how it gets executed (the provider/service supporting that type):

Rails (Type of payment method)

Rails define the payment method interface your code uses. When you specify "rail": "card" in your API calls, you're requesting a card-based payment without worrying about which specific card processor handles it.

Providers (Service supporting that type)

Providers are the actual services that process transactions. For example:

• Card rail can be processed by: unlimit_crypto, alchemy_pay, or moon_pay
• Apple Pay rail can be processed by: moon_pay, alchemy_pay, or other Apple Pay-enabled providers
• Wire transfer rail can be processed by: various banking partners

No-Code Configuration

Configure providers in your Admin Panel:

1. Add API keys for desired providers (MoonPay, Unlimit Crypto, etc.)
2. Set preferences for which provider handles each rail
3. Switch providers anytime without changing your code
4. Let our system choose the optimal provider if no preference is set

This architecture enables cheap code changes - your integration code remains stable while you can switch payment processors through configuration.

Rails fall into two main categories:

Crypto Rails (Blockchain Networks)

Blockchain networks where cryptocurrency transactions are processed. These rails handle crypto-to-crypto transfers and are used as destinations for onramp transfers.

Fiat Rails (Payment Methods)

Traditional payment methods that handle fiat currencies. These rails are used for onramp transfers (fiat → crypto) and offramp transfers (crypto → fiat).

Supported Crypto Rails

We support transfers across multiple blockchain networks, each with their native tokens and standards:

Crypto Transfer Example

{
  "from": {
    "identifier": "cus_123",
    "amount": "25",
    "rail": "polygon",
    "currency": "USDC"
  },
  "to": {
    "identifier": "0x1234567890abcdef1234567890abcdef12345678",
    "rail": "polygon",
    "currency": "USDC"
  }
}

Supported Fiat Rails (Type of payment method)

Core Payment Rails

These are the abstract payment method types your code interfaces with:

Regional Payment Rails

Available Providers (Services supporting payment types)

These are the actual services that process transactions for the rails above:

Multi-Rail Providers

Regional Specialists

Provider Configuration & Selection

Admin Panel Configuration

Configure your payment stack in the Admin Panel:

1. Add Provider Credentials: Enter API keys for providers like MoonPay, Unlimit Crypto, Alchemy Pay
2. Set Rail Preferences: Choose your preferred provider for each rail:
   • Card rail → Unlimit Crypto (your preference)
   • Apple Pay rail → MoonPay (your preference)
   • Wire transfer rail → Paybis (your preference)
3. Enable/Disable Providers: Turn providers on/off without code changes

Automatic Provider Selection

When no explicit preference is configured, our system automatically selects the optimal provider based on:

• Cost optimization: Lowest fees for the transaction amount and currency
• Speed: Fastest processing time for the rail and region
• Success rates: Historical performance for similar transactions
• Geographic optimization: Best local coverage for the user's location

Code Example - Always the Same

Your code remains consistent regardless of which provider processes the transaction:

{
  "from": {
    "identifier": "cus_123", 
    "amount": "100",
    "rail": "card",  // ← Abstract protocol
    "currency": "USD"
  },
  "to": {
    "identifier": "cus_123",
    "currency": "USDC"
  }
}

Behind the scenes:

• Admin panel configured Unlimit Crypto as preferred card provider
• Transaction routes through Unlimit Crypto's card processing
• Switch to Alchemy Pay tomorrow? Zero code changes needed

Fiat Transfer Example

{
  "from": {
    "identifier": "cus_123",
    "amount": "50",
    "rail": "card",
    "currency": "USD"
  },
  "to": {
    "identifier": "cus_123",
    "currency": "USDC"
  }
}

Our OnRamp

While we support many onramp providers (AlchemyPay, Unlimint, Paybis, MoonPay, Wert, and others), Swipelux OnRamp provides maximum compatibility with our crypto rails system. Our native onramp implementation enables seamless cryptocurrency purchases through credit/debit cards, Apple Pay, and Google Pay, with both programmatic API access and embeddable widget options.

Features

• Secure crypto transactions: Support for 100+ cryptocurrencies with full fraud dispute and chargeback protection as merchant of record
• Optimal conversion rates: Pre-verified users with stored payment details maximize conversion success
• Diverse payment methods: Credit/debit cards, Apple Pay, Google Pay, and regional banking methods
• Customizable widget: Full branding customization and white-label solutions available
• Compliance features: Built-in regulatory compliance features for financial services

Supported Coverage

• Regions: 100+ countries and regions
• Cryptocurrencies: 100+ supported tokens
• Networks: All crypto rails listed above as destination networks

Quick Widget Integration

Embed the card rail widget directly in your application:

<!DOCTYPE html>
<html lang="en">
<head>
  <script
    crossorigin="anonymous"
    src="https://cdn.jsdelivr.net/npm/@swipelux/onramp-js@^1.0.0"
  ></script>
</head>
<body>
  <swipelux-widget api-key="YOUR_PUBLISHABLE_API_KEY"></swipelux-widget>
</body>
</html>

Programmatic API Integration

Create card rail transfers programmatically using our Transfer API:

{
  "from": {
    "identifier": "cus_123",
    "amount": "100.00",
    "rail": "card",
    "currency": "USD"
  },
  "to": {
    "identifier": "cus_123",
    "rail": "polygon", 
    "currency": "USDC"
  }
}

Processing flow:

1. Card payment processed through onramp partners
2. USD converted to USDC at optimal market rates
3. USDC transferred to customer's Polygon wallet
4. Real-time status updates via webhooks

Integration Paths

For detailed implementation guides including React SDK, Web Components, server-side integration, webhooks, and customization options, see our Swipelux OnRamp integration guides.

Best Practices

Rails-First Development

• Use abstract rails: Code against card, apple_pay, wire_transfer - not specific providers
• Let configuration handle routing: Keep provider logic in your Admin Panel, not your code
• Plan for provider switches: Design your integration to be provider-agnostic

Provider Strategy

• Start with one provider per rail, expand as needed
• Monitor costs and performance: Switch providers when you find better options
• Use our automatic selection: For optimal cost/speed balance when no preference is set
• Test provider combinations: Different providers excel in different regions/currencies

Configuration Management

1. Add multiple providers for redundancy and optimization
2. Set preferences for critical rails (card, apple_pay, etc.)
3. Monitor performance through Admin Panel analytics
4. Switch providers instantly without code deployment

Error Handling

Handle rail-level errors gracefully - provider-specific issues are abstracted away:

• Network connectivity: Blockchain rails may have temporary network issues
• Regional restrictions: Some rails unavailable in certain regions
• Rail validation: Always validate rail compatibility with user geography

Next Steps

• Configure Providers: Set up your payment stack in the Admin Panel
• Integration: See our Transfer API guides for implementation details
• Testing: Use sandbox environment to test different rail and provider combinations
• Support: Contact customer support for provider onboarding and rail-specific questions