Sub-Merchants API
The Sub-Merchants API allows you to manage sub-merchants for marketplace and platform accounts. Sub-merchants represent sellers, vendors, or service providers that process payments through your platform.
Overviewโ
Sub-merchants enable you to:
- Onboard sellers and vendors onto your platform programmatically
- Split payments between your platform and sub-merchants
- Manage merchant details including business information and bank accounts
- Track transactions for each sub-merchant separately
- Comply with regulations by maintaining proper merchant records
Sub-Merchant Typesโ
Individual Sub-Merchantsโ
Personal accounts for individual sellers. Requires:
- Full legal name
- National ID or passport number
- Bank account details
- Contact information
Business Sub-Merchantsโ
Corporate or business accounts. Requires:
- Registered business name
- Business registration number
- Tax ID
- Bank account details
- Authorized representative information
Sub-Merchant Lifecycleโ
- Create - Register a new sub-merchant with required business details
- Pending - Sub-merchant undergoes verification and compliance checks
- Active - Sub-merchant can accept payments through your platform
- Suspended - Temporarily disabled (compliance issues, request, etc.)
- Deactivated - Permanently removed from platform
Platform Requirementsโ
To use the Sub-Merchants API, your account must:
- Be approved as a platform/marketplace account
- Have sub-merchant management enabled
- Comply with local payment regulations
- Maintain proper KYC/AML procedures
Contact Omise support to enable platform features on your account.
Payment Flowโ
Direct Paymentsโ
Payments are made directly to sub-merchants, with platform fees automatically deducted.
Split Paymentsโ
Payments are split between the platform and sub-merchant according to configured rules.
Aggregated Settlementsโ
Multiple transactions are aggregated before settlement to reduce transfer costs.
Authenticationโ
All sub-merchant endpoints require your secret key for authentication. Never expose your secret key in client-side code.
Available Endpointsโ
| Method | Endpoint | Description |
|---|---|---|
| POST | /sub_merchants | Create a new sub-merchant |
| GET | /sub_merchants/:id | Retrieve a specific sub-merchant |
| GET | /sub_merchants | List all sub-merchants |
| PATCH | /sub_merchants/:id | Update sub-merchant details |
| DELETE | /sub_merchants/:id | Deactivate a sub-merchant |
| GET | /sub_merchants/search | Search sub-merchants |
Common Use Casesโ
Marketplace Platformsโ
Onboard sellers and manage their payment processing, commissions, and payouts.
Service Aggregatorsโ
Manage service providers (drivers, contractors, freelancers) with individual payment accounts.
Franchise Systemsโ
Set up payment processing for franchise locations with centralized management.
Multi-Vendor E-commerceโ
Enable multiple vendors to sell products through a single storefront with separate settlements.
Booking Platformsโ
Manage hosts, property owners, or service providers with automated payment splits.
Best Practicesโ
- Validate business information before creating sub-merchants
- Store sub-merchant IDs in your database for reference
- Implement proper KYC to comply with regulations
- Monitor sub-merchant activity for fraud prevention
- Use metadata for custom categorization (business_type, region, etc.)
- Handle verification status changes via webhooks
- Test thoroughly in test mode before going live
- Keep records updated when business information changes
Sub-Merchant Status Codesโ
| Status | Description |
|---|---|
pending | Awaiting verification and approval |
active | Verified and can accept payments |
suspended | Temporarily disabled |
deactivated | Permanently removed |
rejected | Verification failed |
Failure Codesโ
When sub-merchant creation or verification fails, the failure_code attribute indicates the reason:
| Code | Message | Description |
|---|---|---|
invalid_business_info | "invalid business information" | Business details could not be verified |
document_required | "additional documents required" | More documentation needed for verification |
bank_account_invalid | "invalid bank account" | Bank account verification failed |
compliance_failed | "compliance check failed" | Did not pass compliance requirements |
duplicate_merchant | "duplicate merchant" | Sub-merchant already exists |
region_not_supported | "region not supported" | Business region is not supported |
Security Considerationsโ
- Data encryption - All sensitive data is encrypted at rest and in transit
- KYC compliance - Sub-merchants undergo identity verification
- Fraud monitoring - Transactions are monitored for suspicious activity
- Access control - Use secret key authentication
- Audit trails - All changes are logged for compliance
Related Resourcesโ
- Charges API - Process payments for sub-merchants
- Transfers API - Send payouts to sub-merchants
- Balance API - Check available balance
- Webhooks - Receive sub-merchant events
Need help? Contact support@omise.co for platform account setup, sub-merchant verification, or integration assistance.