Documentation Index
Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt
Use this file to discover all available pages before exploring further.
Commerce V2 supports four distinct operating models to match your business needs. Each model offers different capabilities and is designed for specific use cases, from single merchant setups to complex multi-party payment ecosystems.
Primary Merchant
Platform / Marketplace
Ecosystem
Managed Ecosystem
The default model for single businesses. Your account operates as a standalone merchant processing its own transactions.Key Features
- Single merchant configuration locked to your primary account
- Simplified setup - No sub-merchant management required
- Full payment features - Access to all payment capabilities for your own transactions
- Restricted operations:
- Cannot add sub-merchants (
POST /merchants disabled)
- Cannot delete the primary merchant (
DELETE /merchants/{id} disabled)
Use Cases
- E-commerce stores
- SaaS businesses processing their own payments
- Single-entity businesses
- Startups and small businesses
This model is ideal when you’re processing payments for your own business without the need to facilitate payments for other parties. Enable multiple sellers or service providers to process payments through your platform.Key Features
- Multi-merchant support - Add and manage multiple sub-merchants
- Individual configuration - Configure processing rules per merchant
- Transaction tracking - Track transactions by merchant for split payments
- Marketplace flows - Implement complex marketplace payment flows with splits and commissions
Use Cases
- Online marketplaces (e.g., Etsy, eBay-style platforms)
- Multi-vendor platforms
- Service marketplaces (e.g., ride-sharing, food delivery)
- Crowdfunding platforms
- B2B platforms connecting buyers and sellers
Platform model requires activation by your account manager. Contact us to discuss your use case and enable this operating model.
Grant controlled payment capabilities to third parties within your business ecosystem.Key Features
- Partner onboarding - Onboard ecosystem partners as sub-merchants
- Transaction controls - Set transaction limits and permissions per partner
- Centralized oversight - Maintain visibility of all ecosystem transactions
- Network token support - Leverage network tokens for enhanced security and conversion
Use Cases
- Mobility services (car sharing, bike sharing)
- Delivery networks
- Service networks with multiple providers
- Franchise operations
- Partner programs requiring payment facilitation
Ecosystem model requires validation of your use case by your account manager. This ensures proper setup and compliance with payment regulations.
Full payment facilitation with comprehensive merchant management capabilities provided by Starfish as a service.Key Features
- Advanced onboarding - Comprehensive sub-merchant onboarding and underwriting
- Risk management - Built-in risk management and compliance tools
- Detailed monitoring - Advanced merchant monitoring and reporting
- Complex flows - Support for complex multi-party payment flows
- Managed service - Starfish handles the operational complexity
Use Cases
- Large-scale payment facilitators
- Financial institutions offering payment services
- Enterprise platforms requiring full-service payment facilitation
- Complex multi-party payment scenarios
Managed Ecosystem requires special licensing and compliance review. This model involves additional regulatory requirements and is subject to approval.
Choosing the Right Model
Selecting the appropriate operating model depends on your business structure and requirements:
- Primary Merchant: Choose this if you’re a single business processing your own payments
- Platform / Marketplace: Ideal for platforms connecting multiple sellers or service providers
- Ecosystem: Best for networks of partners or franchise operations
- Managed Ecosystem: Suitable for large-scale payment facilitation with full-service management
Migration Between Models
Your operating model is typically set during account creation. If your business needs change, contact your account manager to discuss migration options. Some transitions may require account reconfiguration or compliance review.
API Capabilities by Model
All operating models support the core Commerce V2 features:
- Payment processing (customer and merchant initiated)
- Token management
- 3D Secure authentications
- Network token provisioning
- Payment modifications (capture, void, refund)
The differences lie in merchant management capabilities, sub-merchant support, and transaction splitting features. Refer to the Merchants API documentation for model-specific endpoint availability.
