Custom tokens support
Custom tokens support allows Enterprise customers to accept payments in their own ERC-20 tokens on supported networks. These tokens can be used only for token-to-token payments, without fiat or FX conversion, and follow the same order and payment lifecycle as standard crypto assets.
Orbi Gateway supports accepting payments in custom ERC-20 tokens provided by the merchant.
This feature is designed for businesses that need to collect payments in proprietary or non-listed tokens, while keeping the same operational guarantees as standard crypto payments.
Custom tokens are treated as payment currencies, not as exchangeable assets. As a result, they are intentionally excluded from fiat conversion and FX-based pricing.
Availability
Custom tokens support is an Enterprise-only feature and must be explicitly enabled per account.
Scope and limitations
What is supported
- ERC-20 compliant tokens only
- One custom token per order
- Token-to-token payments (no conversion)
- Partial payments
- On-chain payouts in the same token
- Ethereum (ERC-20) and Polygon networks
- Sandbox and production (using the corresponding network contracts)
What is not supported
- Fiat → token conversion
- Crypto → token conversion
- Fiat payouts
- Multiple custom tokens within the same order
- Pricing based on external FX or market rates
Token requirements
To enable a custom token, the merchant must provide:
- The smart contract address of the ERC-20 token
- The network where the token is deployed (Ethereum or Polygon)
Only standard ERC-20 tokens are supported. Tokens with non-standard behavior (e.g. rebasing, transfer fees, paused transfers) are not guaranteed to work correctly.
Important
Orbi does not evaluate the economic, legal, or security properties of custom tokens.
The merchant is fully responsible for the token contract and its on-chain behavior.
Enabling a custom token
Custom tokens are enabled through a feature flag at the account level.
The process is:
- The merchant provides the token contract address and network.
- Orbi verifies basic ERC-20 compatibility.
- The token is enabled for that specific account.
Once enabled, the token becomes available as a payment currency when creating orders.
Orders with custom tokens
When using a custom token:
- The order’s payment currency is the custom token itself.
- No FX calculation or rate lookup is performed.
- The order amount is defined directly in the token’s units.
- The order lifecycle and states are unchanged.
Payouts
Funds collected in custom tokens:
- Can only be paid out on-chain
- Are paid out in the same token
- Cannot be converted to fiat or other crypto assets
Payout mechanics follow the same operational model as other on-chain crypto payouts.
Sandbox behavior
Custom tokens can be tested in sandbox environments by providing:
- The token contract address deployed on supported test networks
- The corresponding network configuration
Sandbox behavior mirrors production, including order lifecycle, partial payments, and webhooks.
Design rationale
Custom tokens are intentionally scoped to token-native payment flows.
By excluding FX conversion and fiat settlement:
- Order amounts remain deterministic
- Reconciliation stays predictable
- Merchants retain full control over token economics
This design avoids implicit pricing assumptions and prevents accidental exposure to market volatility.
Updated 7 months ago