Provider Management
Manage payment provider integrations and terminals. Providers are the external payment processors (acquirers, APMs, payout networks) that handle the actual transaction processing. You connect to them through terminals.
Provider Integrations
Provider integrations are the global catalog of available payment processor adapters. Each integration describes:
- What protocol the provider uses (REST, SOAP, ISO 8583)
- What credentials are required (dynamic form based on the provider)
- What payment methods and currencies are supported
- What features are available (3DS, tokenization, recurring, partial refunds)
Portal: Navigate to Providers to see the list of available integrations.
Provider integrations are pre-configured at the platform level. You do not create new integrations — you select from the available catalog and create terminals to connect to them with your credentials.
Provider Capabilities
Each provider declares its capabilities, which serve as the upper bound for what you can configure on a terminal:
| Capability | Description |
|---|---|
| Supported payment methods | Card, bank transfer, wallet, etc. |
| Supported brands | Visa, Mastercard, Amex, etc. (per payment method) |
| Supported currencies | Which currencies the provider can process |
| Supported countries | Which countries the provider covers |
| Features | 3DS, tokenization, recurring, manual capture, partial refund, MOTO |
| 3DS versions | Which 3DS protocol versions are supported |
| Test mode | Whether the provider offers a sandbox environment |
Terminals
A terminal is your connection to a specific provider. It holds the credentials (MID, API keys, shared secrets) needed to submit transactions to that provider.
Creating a Terminal
Portal: Select a Merchant, navigate to the Terminals tab, and select Create Terminal.
- Name: A descriptive label (e.g., "Stripe Live EUR").
- Provider integration: Select the provider from the catalog.
- Direction: Choose the transaction direction. This is immutable after creation.
| Direction | Purpose |
|---|---|
payin | Receive payments from customers |
payout | Send payments to third-party recipients |
withdrawal | Send funds to entity's own account |
exchange | Currency exchange operations (FX) |
- Credentials: Fill in the credential form. The form fields are generated dynamically based on the provider's credential schema (e.g., Stripe requires API key and webhook secret; a bank acquirer may require MID, terminal ID, and encryption keys).
- Provider cost schedule: Assign a fee schedule that reflects the provider's actual processing costs. This is required — it feeds into the fee decomposition model.
- Payment method configuration: Select which payment methods, brands, and currencies to enable on this terminal. These must be a subset of the provider's declared capabilities.
Terminal Status
| Status | New transactions | Existing transactions | Routing eligible |
|---|---|---|---|
active | Yes (live) | Yes | Yes |
test | Test only | N/A | Only for sandbox merchants |
disabled | No | Settle existing | No |
Status transitions: active can switch to test or disabled. test can switch to active or disabled. A disabled terminal cannot be re-enabled — create a new terminal instead.
Channels
A channel is the link between a merchant and a terminal. It defines which merchant can use which terminal, with what currency configuration and processing behavior.
Creating a Channel
Portal: Select a Merchant, navigate to Channels, and select Create Channel.
- Terminal: Select the terminal to link.
- Applicable currencies: Which currencies can flow through this channel. Must be a subset of the terminal's supported currencies.
- Priority: Routing priority hint (lower number = higher priority). Used by the routing engine when multiple channels are eligible.
- Weight: For weighted traffic distribution across channels with the same priority.
- Cascading: Whether this channel participates in cascading (retry on decline).
- Retry: Whether retry is allowed on this channel.
One Merchant, Multiple Channels
A single merchant can have multiple channels connecting to different terminals. This enables:
- Redundancy: If one provider is down, traffic routes through another.
- Optimization: Route specific currencies or card brands to the most cost-effective provider.
- Geographic coverage: Use different providers for different regions.
Terminals are not merchant-specific. One terminal can serve multiple merchants within your tenant. The channel is what binds a specific merchant to a terminal.
Managing Provider Credentials
Credentials are stored securely in the platform Vault — an encrypted storage system separate from the application database. The terminal record only holds a reference to the Vault path, never the credentials themselves.
Key points
- Credentials are entered during terminal creation and validated against the provider's credential schema.
- After creation, credentials are never visible in the Portal or API. You cannot retrieve them.
- To update credentials, use the credential rotation feature on the terminal's detail page (full replacement).
- Each provider connector can only access credentials for its own provider type — enforced by Vault access policies.
Never share provider credentials through email, chat, or other unsecured channels. Enter them directly in the Portal terminal creation form. The platform encrypts them immediately and stores them in the Vault.
Best Practices
Create separate terminals per direction. A payin terminal and a payout terminal should be separate, even if they use the same provider. This keeps routing rules, limits, and monitoring clean.
Assign provider cost schedules accurately. The cost schedule on the terminal should match your actual agreement with the provider. This ensures your tenantFee (margin) calculation is correct.
- Start with one terminal per provider in test mode. Verify end-to-end transaction flow before switching to active.
- Use descriptive terminal names that include the provider, direction, and primary currency (e.g., "Adyen Payin EUR").
- Review terminal status regularly — disable terminals you are no longer using rather than leaving them active.
- When rotating credentials, coordinate with the provider to avoid downtime during the transition.