# Development Guides

Welcome to Rail's API Development guides! These comprehensive, step-by-step guides will help you integrate Rail's powerful financial infrastructure into your application.

## What You'll Find Here

This section contains hands-on guides that walk you through common integration scenarios. Each guide includes:

✅ Complete code examples with curl commands
✅ Step-by-step instructions
✅ Request and response samples
✅ Best practices and gotchas
✅ Links to relevant API documentation

## Prerequisites

Before diving into these guides, you'll need:

1. **Sandbox Access** - [Request access here](https://rail.io/contact-us) to get your client ID and secret
2. **OAuth2 Credentials** - Your client ID and secret for authentication
3. **Development Environment** - A terminal or API client (Postman, Insomnia, etc.)


## Core Development Guides

### 🔐 Register for Webhooks

Set up real-time event notifications for your application.

**What You'll Learn:**

- How to register webhook subscriptions
- Implementing webhook endpoints on your server
- Verifying webhook signatures for security
- Handling webhook events and implementing idempotency
- Best practices for webhook reliability


**Use Cases:**

- Real-time balance updates
- Transaction notifications
- Application status changes
- Compliance event monitoring


[Start the Webhooks Guide →](/guides/webhooks_registration)

### 👤 Customer Onboarding

Onboard individual and corporate customers through the Applications API.

**What You'll Learn:**

- Creating applications for individuals and corporations
- Uploading KYC/KYB documents
- Retrieving document IDs from status endpoint
- Handling application status changes
- Multi-provider processing


**Scenarios Covered:**

- Individual customer onboarding (6 steps)
- Corporate customer onboarding with beneficial owners (7 steps)


**Key Concepts:**

- Application status flow (INCOMPLETE → READY_FOR_SUBMISSION → SUBMITTED → APPROVED)
- Changes requested handling
- Provider approval timing


[Start the Customer Onboarding Guide →](/guides/customer_onboarding)

### 💼 Account & Funds Management

Open accounts, manage funds, and track incoming deposits.

**What You'll Learn:**

- Opening deposit accounts for customers
- Monitoring account status changes
- Setting up webhooks for account events
- Getting deposit instructions (ACH, FEDWIRE, SWIFT)
- Tracking incoming deposits and transactions
- Account readiness verification


**Important Topics:**

- Account status meanings and lifecycle
- When to show accounts as "ready" to users
- Deposit instructions for multiple payment rails
- Transaction vs deposit concepts
- Webhooks vs polling strategies


**Best Practices:**

- Always verify account status before requesting deposit instructions
- Use webhooks for real-time monitoring
- Implement proper account card readiness checks
- Handle provider approval timing


[Start the Account Management Guide →](/guides/account_funds_management)

### 💸 Withdrawals

Process withdrawals to external bank accounts and crypto wallets.

**What You'll Learn:**

- Creating counterparties (external destinations)
- Initiating fiat and crypto withdrawals
- Handling Auto-RFI document requirements
- Managing withdrawal lifecycle
- Counterparty management operations


**Scenarios Covered:**

- Simple withdrawal (below Auto-RFI threshold)
- Withdrawal with Auto-RFI (above threshold, requires documents)


**Key Concepts:**

- Counterparty types (FIAT_US, CRYPTO, etc.)
- Auto-RFI process (similar to application onboarding)
- Withdrawal status flow
- Document upload requirements


**Best Practices:**

- Verify account balance before creating withdrawals
- Use status endpoint to check for Auto-RFI triggers
- Match asset types between accounts and counterparties
- Set up webhook subscriptions for withdrawal events


[Start the Withdrawals Guide →](/guides/withdrawals_api)

## Guides

Step-by-step guides for implementing common workflows and use cases. These guides provide practical examples and code patterns for building with the platform.

### [Collections (Payments) →](/guides/payments_collections)

Implement payment collection workflows. Learn how to accept payments from customers and process incoming funds.

### [Register for Webhooks →](/guides/subscriptions)

Set up webhook endpoints to receive real-time notifications about platform events. Essential for building event-driven applications.

### [Customer Onboarding →](/guides/applications)

Build customer onboarding flows including identity verification, KYC processes, and account creation.

### [Account Management →](/guides/accounts)

Manage customer accounts including balance inquiries, account status updates, and multi-account structures.

### [Withdrawals →](/guides/withdrawals)

Implement withdrawal workflows to move funds from customer accounts to external destinations.

## Learning Path Recommendations

### New to Rail? Start Here

1. **[Customer Onboarding](/guides/customer_onboarding)** - Learn how to onboard customers
2. **[Account & Funds Management](/guides/account_funds_management)** - Open accounts and accept deposits
3. **[Register for Webhooks](/guides/webhooks_registration)** - Set up real-time notifications
4. **[Withdrawals](/guides/withdrawals_api)** - Enable customers to send funds out


### Building Specific Use Cases?

- **Payment Processing** → Start with [Payments - Collections](/guides/payments_collections)
- **Crypto On-Ramp** → Start with [On-Ramp Guide](/guides/fiatonramp)
- **Crypto Off-Ramp** → Start with [Off-Ramp Guide](/guides/fiatofframp)
- **Digital Wallet** → Start with [Wallet as a Service](/guides/buysellhold)


## Additional Resources

### API Documentation

For complete API reference documentation with all endpoints, parameters, and schemas:

[View Full API Documentation →](/api-docs/openapi/rail-spec)

### Core Concepts

Understand the fundamental concepts behind Rail's platform:

- [Accounts](/guides/accounts) - Account types and lifecycle
- [Applications](/guides/applications) - Customer onboarding details
- [Assets](/guides/assets) - Supported currencies and digital assets
- [Counterparties](/guides/counterparties) - External destination management
- [Customers](/guides/customers) - Customer records and management
- [Deposits](/guides/deposits) - Incoming funds handling
- [Exchanges](/guides/exchanges) - Currency/asset swapping
- [Transfers](/guides/transfers) - Moving funds between accounts
- [Withdrawals](/guides/withdrawals) - Outgoing funds handling


### Developer Quick Start

Essential topics for all Rail integrations:

- [Authentication](/guides/authentication) - OAuth2 and scopes
- [Request Signing](/guides/requestsigning) - Additional security layer
- [Idempotence](/guides/idempotence) - Safe request retries
- [Pagination](/guides/pagination) - Handling large result sets
- [Subscriptions](/guides/subscriptions) - Webhook implementation details
- [Subscription Events](/guides/subscriptions_events) - Complete event list


## Getting Help

### Contact Support

- **Email**: [support@layer2financial.com](mailto:support@layer2financial.com)
- **Website**: [rail.io/contact-us](https://rail.io/contact-us)
- **Slack**: Contact your account manager for access to our developer Slack


### Common Questions

**Q: Can I use these guides in production?**
A: These guides use sandbox endpoints and test data. For production, update the base URLs and use your production credentials.

**Q: How do I get sandbox credentials?**
A: You will receive your sandbox credentials (client ID and secret) from your implementation manager when you begin working with Rail. If you don't have credentials yet, [contact us](https://rail.io/contact-us) to get started.

**Q: How long does sandbox onboarding take?**
A: Once you have credentials, sandbox accounts are typically approved within minutes. Production accounts follow standard compliance timelines.

**Q: Do I need to implement all guides?**
A: No - implement only the guides relevant to your use case. Most integrations start with Customer Onboarding, Account Management, and Webhooks.

**Q: Can I test webhooks locally?**
A: Yes! Use tools like ngrok to expose your local server, or use webhook testing services like webhook.site during development.

**Q: What's the difference between collection and environment variables in Postman?**
A: Collection variables are stored within the collection itself, making it portable and easier to share. Environment variables are separate and require additional setup.

## Next Steps

1. **Get Sandbox Access** - [Request credentials](https://rail.io/contact-us) if you haven't already
2. **Import Postman Collection** - Get started with pre-built requests
3. **Choose Your First Guide** - Pick a guide based on your use case
4. **Set Up Webhooks** - Implement real-time notifications early
5. **Test in Sandbox** - Thoroughly test your integration
6. **Go Live** - Contact your account manager when ready for production


Ready to build? Pick a guide above and start integrating!