Linked Accounts API
The Linked Accounts API allows you to manage connected sub-accounts for your platform. Linked accounts represent merchants, sellers, or service providers that process payments through your platform.
Overviewโ
Linked accounts enable you to:
- Connect merchant accounts to your platform for payment processing
- Manage sub-accounts for marketplace sellers and service providers
- Split payments between your platform and linked accounts
- Track account status and verification state
- Search and filter linked accounts by various criteria
Linked Account Typesโ
Individual Accountsโ
Personal accounts for individual merchants or service providers. Includes:
- Full name and contact information
- Bank account details for payouts
- Verification status
Business Accountsโ
Corporate or business accounts. Includes:
- Company name and registration details
- Tax identification number
- Bank account details for payouts
- Verification status
Linked Account Lifecycleโ
- Connect - Merchant connects their account to your platform
- Verify - Account undergoes verification (automatic or manual)
- Active - Account can process payments and receive payouts
- Suspended - Account temporarily disabled (can be reactivated)
- Disconnected - Account removed from platform
Account Statusโ
Linked accounts have the following status values:
| Status | Description |
|---|---|
pending | Account created, registration in progress |
successful | Registration completed successfully |
failed | Registration failed (check failure_code and failure_message) |
expired | Registration link expired before completion |
deleted | Account has been deleted |
Account Capabilitiesโ
Each linked account may have different capabilities enabled:
| Capability | Description |
|---|---|
card_payments | Can accept card payments |
transfers | Can receive payouts |
refunds | Can process refunds |
Authenticationโ
All linked account endpoints require your secret key for authentication. Never expose your secret key in client-side code.
Available Endpointsโ
| Method | Endpoint | Description |
|---|---|---|
| POST | /linked_accounts | Create a new linked account |
| GET | /linked_accounts | List all linked accounts |
| GET | /linked_accounts/:id | Retrieve a specific linked account |
| GET | /linked_accounts/search | Search linked accounts |
| DELETE | /linked_accounts/:id | Delete a linked account |
Common Use Casesโ
Marketplace Platformsโ
Connect seller accounts to process payments and distribute earnings automatically.
SaaS Platformsโ
Manage merchant accounts for businesses using your software platform.
Aggregator Servicesโ
Onboard and manage multiple service providers under your platform.
Franchise Networksโ
Connect and manage payments for franchise locations.
Best Practicesโ
- Verify accounts promptly after connection
- Store linked account IDs in your database
- Monitor account status for changes
- Handle verification failures gracefully
- Use metadata for categorization (merchant_type, region, etc.)
- Implement webhooks to receive account status updates
- Review account activity regularly for compliance
Security Considerationsโ
- Access control - Use secret key authentication
- Data encryption - Sensitive data is encrypted at rest
- Audit trails - Track all account modifications
- Compliance - Accounts undergo KYC verification
- Fraud prevention - Monitor for suspicious activity
Related Resourcesโ
- Transfers API - Send funds to linked accounts
- Charges API - Process payments for linked accounts
- Balance API - Check account balances
- Webhooks - Receive account status events
Need help? Contact support@omise.co for linked account setup, verification, or integration assistance.