Create Entity Hierarchy
Before a merchant can process payments, you need to create the full entity chain: Company, Merchant, Terminal, and Channel. Each level serves a specific purpose in the platform architecture.
Step 1: Create Company
A Company is the legal entity container. It represents the registered business and can hold multiple merchants under it. KYB verification happens at this level.
Portal: Navigate to the Merchants section and select Create Company.
| Field | Description |
|---|---|
| Company name | Legal name of the business |
| Registration number | Official business registration ID |
| Country | Country of incorporation |
| Address | Registered business address |
A Company can hold multiple merchants — for example, a single legal entity operating several online stores or brands.
Step 2: Create Merchant
A Merchant is the business entity that accepts payments from customers. Every merchant belongs to exactly one company.
Portal: Select the Company, then choose Create Merchant.
| Field | Description |
|---|---|
| Merchant name | Display name for this merchant |
| Business type | Category or MCC code |
| Website | Merchant's website URL |
| Contact email | Primary contact for this merchant |
| Contact phone | Optional phone contact |
The merchant starts in sandbox status, allowing test transactions immediately. To process live payments, the merchant must go through the approval flow (see KYB Process).
Step 3: Create Terminal
A Terminal represents a connection to a specific payment provider integration. Provider credentials are securely stored in the vault and referenced by the terminal.
Terminals are tenant-level resources — they are NOT scoped to a single merchant. One terminal can serve multiple merchants. The Merchant-Terminal binding happens through Channels.
Portal: Navigate to the Terminals section at the tenant level and select Create Terminal.
| Field | Description |
|---|---|
| Terminal name | Descriptive label for this connection |
| Provider | The payment provider this terminal connects to |
| Credential reference | Reference to provider credentials stored in the vault |
| Status | test or active — determines which provider environment is used |
A tenant can have multiple terminals connecting to different providers. This enables routing and failover across providers.
Step 4: Create Channel
A Channel links a merchant to a terminal and defines which payment methods the merchant can accept through that connection.
Portal: Select the Merchant, then navigate to Channels and select Create Channel.
| Field | Description |
|---|---|
| Channel name | Descriptive label |
| Terminal | Which terminal this channel routes through |
| Payment methods | Which payment methods are available via this channel |
| Currencies | Which currencies are accepted |
A merchant can have multiple channels — for example, one channel for card payments via Provider A and another for bank transfers via Provider B.
Important Notes
- Two ways to create a merchant. Operators with merchant management permissions can create merchants from the Portal. Tenants can also enable public self-registration via the
self_service_merchant_signup_enabledflag —POST /v1/register/merchant?tenant-id=<id>then opens a public signup endpoint that creates a Company, a sandbox Merchant, and an owner user (merchant:owner). - Terminal credentials are never exposed. Provider credentials are stored in the vault and referenced by a credential ID. They are never visible in the Portal UI or API responses.
- Test before going live. After creating the entity hierarchy, use sandbox mode to verify the integration works correctly before enabling live traffic.