# Moov Documentation

> Moov is a payments platform that enables developers to integrate money movement capabilities into their applications.

- Full docs: [https://docs.moov.io/llms-full.txt](https://docs.moov.io/llms-full.txt)
- OpenAPI spec (source of truth): [https://spec.speakeasy.com/moov/moov/api-v2026.01.00](https://spec.speakeasy.com/moov/moov/api-v2026.01.00)
- API reference: [https://docs.moov.io/api/](https://docs.moov.io/api/)
- Docs MCP server: [https://docs.moov.io/mcp](https://docs.moov.io/mcp)
- AI integration guide: [https://docs.moov.io/guides/developer-tools/mcp-ai/ai-integration/](https://docs.moov.io/guides/developer-tools/mcp-ai/ai-integration/)

## AI Integration Tools

- **Docs MCP server** (`https://docs.moov.io/mcp`): Search and read Moov docs from any AI coding tool. Install in Claude Code: `claude mcp add --transport http moov-docs https://docs.moov.io/mcp`
- **Moov SDK MCP server**: Live API operations via the TypeScript SDK. See [https://docs.moov.io/guides/developer-tools/mcp-ai/mcp/](https://docs.moov.io/guides/developer-tools/mcp-ai/mcp/)
- **Claude Code skill**: Offline integration patterns at [https://github.com/moovfinancial/docs/tree/main/skills/moov-api](https://github.com/moovfinancial/docs/tree/main/skills/moov-api)
- **llms-full.txt**: Complete documentation at [https://docs.moov.io/llms-full.txt](https://docs.moov.io/llms-full.txt)
- **OpenAPI spec**: Machine-readable API definition (source of truth for endpoints, schemas, fields). Download: [https://spec.speakeasy.com/moov/moov/api-v2026.01.00](https://spec.speakeasy.com/moov/moov/api-v2026.01.00)

## Best Practices for Integrating Moov

### Getting Started
1. **Create a Moov Account**: Sign up at [https://dashboard.moov.io](https://dashboard.moov.io) and obtain API keys
2. **Choose Your Integration Path**:
   - Use the REST API for maximum flexibility
   - Use backend SDKs (Go, Node.js, Python, .NET, Ruby) for type-safe server integration
   - Use Moov.js for secure client-side data collection
   - Use Moov Drops for pre-built, drop-in UI components
   - Use hosted onboarding for merchant account creation
   - Use payment links for a hosted checkout flow

### Authentication
- Always use API keys securely on the server-side
- Never expose secret keys in client-side code
- Use OAuth scopes to limit access permissions

### Money Movement
1. **Create Accounts**: Start by creating Moov accounts for your users
2. **Verify Identity**: Complete KYC/KYB verification before enabling money movement
3. **Add Payment Methods**: Link bank accounts, cards, or wallets
4. **Create Transfers**: Initiate payments between accounts
5. **Monitor Status**: Use webhooks to track transfer lifecycle events

### Payment Methods
- **ACH**: Best for bank-to-bank transfers, takes 1-3 business days
- **RTP (Real-Time Payments)**: Instant transfers, available 24/7
- **Cards**: For card payments with faster settlement
- **Wallets**: Use Moov wallets for holding funds

### Security Best Practices
- Implement webhook signature verification
- Use HTTPS for all API requests
- Store sensitive data encrypted
- Follow PCI compliance guidelines for card data
- Implement rate limiting and monitoring

### Error Handling
- Always handle API errors gracefully
- Implement retry logic with exponential backoff
- Log errors for debugging and monitoring
- Provide user-friendly error messages

### Testing
- Use sandbox mode for development
- Test all payment flows before going live
- Verify webhook handling
- Test error scenarios

## Key Resources

### Quick Start
- [Dashboard quick start](https://docs.moov.io/guides/quick-start/dashboard/index.md): This quick start guide brings you through the process of signing up for Moov and creating user accounts within the Moov Dashboard.
- [API & Drops quick start](https://docs.moov.io/guides/quick-start/api/index.md): This quick start guide brings you through the process of signing up for Moov and creating user accounts with Moov's API and Moov.js Drops.

### Essential Guides
- [Account types](https://docs.moov.io/guides/accounts/account-types/index.md): Learn about the different types of Moov accounts and the basic requirements to start moving money.
- [All accounts](https://docs.moov.io/guides/dashboard/accounts/all-accounts/index.md): View account information and manage accounts you've created.
- [Declines](https://docs.moov.io/guides/money-movement/accept-payments/card-acceptance/declines/index.md): Understand why certain card payments are declined and how Moov categorizes different types of declines.
- [Fund a wallet](https://docs.moov.io/guides/money-movement/wallets/funding/index.md): Learn how to fund a Moov wallet.
- [Instant payments with RTP](https://docs.moov.io/guides/money-movement/send-payments/instant-payments/index.md): Instantly send funds from a Moov wallet to a bank account with RTP.
- [Multiple wallets](https://docs.moov.io/guides/sources/wallets/multiple-wallets/index.md): Learn how to create and manage multiple wallets to organize funds across different business functions within a single Moov account.
- [ACH overview](https://docs.moov.io/guides/money-movement/accept-payments/ach/ach-overview/index.md): Create payments that directly involve external bank accounts using the Automated Clearing House (ACH) network.
- [Transfers overview](https://docs.moov.io/guides/money-movement/overview/index.md): Learn about the flow of transfers and the options for sources and destinations.
- [Webhook events](https://docs.moov.io/guides/webhooks/webhook-events/index.md): Moov generates events when something happens in our system. We record the relevant data and make it available to you.
- [API Documentation](https://docs.moov.io/api/index.md): Complete REST API reference

## Common Integration Patterns

### Pattern 1: Marketplace/Platform
For platforms facilitating payments between users:
1. Create accounts for each user (buyers and sellers)
2. Implement KYC verification for sellers
3. Link payment methods for buyers
4. Create transfers from buyer to seller
5. Optionally use wallets for fund holding
6. Implement fee collection via fee plans

### Pattern 2: Payouts/Disbursements
For businesses paying vendors, contractors, or users:
1. Create Moov accounts for recipients
2. Collect and verify payout methods (bank accounts)
3. Batch or individual transfer creation
4. Track transfer status via webhooks
5. Handle failed transfers with retry logic

### Pattern 3: Bill Pay/Invoicing
For collecting payments from customers:
1. Create customer accounts
2. Link payment methods (cards or bank accounts)
3. Create transfers to your business account
4. Send payment confirmations
5. Handle recurring payments with saved payment methods

### Pattern 4: Embedded Finance
For white-label financial products:
1. Use Moov Drops for pre-built UIs
2. Implement Moov.js for custom flows
3. Create wallets for users to hold funds
4. Enable money movement between wallets and external accounts
5. Provide transaction history and statements

## Support & Resources

- Documentation: [https://docs.moov.io](https://docs.moov.io)
- API Reference: [https://docs.moov.io/api/index.md](https://docs.moov.io/api/index.md)
- Dashboard: [https://dashboard.moov.io](https://dashboard.moov.io)
- Status Page: [https://status.moov.io](https://status.moov.io)

## Default Rate Limits

- Production API: 100 requests per second per account
- Sandbox API: 50 requests per second

## Common Pitfalls to Avoid
1. **Not handling async operations**: Transfers are asynchronous; use webhooks or the `x-wait-for` header
2. **Hardcoding in production**: Use environment variables for API keys
3. **Ignoring errors**: Always implement comprehensive error handling
4. **Not testing webhooks**: Verify webhook signature validation
5. **Not using idempotency keys**: Prevent duplicate transfers
6. **Skipping sandbox testing**: Always test in sandbox before production