Core Concepts and Terminology

Understanding these terms will help you model payment flows correctly and integrate faster.

Payment rails

A payment rail is the underlying network or system used to move funds from a payer to a merchant. In Orbi, the payment rail determines:

How the customer pays (e.g., instant internal transfer vs on-chain deposit)
Settlement time (instant vs confirmation-based)
Fees (platform fees vs network/gas fees)
How payments are detected and reconciled (internal ledger events vs blockchain monitoring)

Your integration chooses a rail based on the payment experience you want to offer and the assets/networks you need to support.

Entities

The following entities appear throughout the API:

Entity	Description	Typical lifecycle
Merchant	Represents a vendor offering products or services and receiving payments through Orbi. A merchant owns resources such as orders, payments, and webhooks.	Created and configured in the Dashboard. Used as the security boundary for all `self`-scoped API keys.
Order	A payment request created by a merchant. Orders define what the customer should pay (amount, currency, rail, expiration) and track the payment status over time.	`awaiting_payment` → `paid` or `expired` / `canceled`.
Payment	A monetary transaction detected by Orbi and associated with an order. An order can have one or multiple payments depending on the rail and payment behavior (partial payments, retries, etc.).	`received` → `applied` or `failed` .
Webhook	A secure HTTP notification mechanism used by Orbi to deliver lifecycle events (order and payment updates) to your backend in near real time.	Configured per merchant. Events are delivered with retries and must be handled idempotently.

Note
All resources are merchant-scoped. API keys using self scopes can only access data owned by the authenticated merchant.

Supported rails

Orbi currently supports two payment rails:

Orbi Pay — A closed-loop payment system designed for instant settlement, low fees, and no on-chain gas costs.
Crypto deposit — On-chain deposits for selected currencies and networks, with confirmation-based settlement.

Supported assets and networks

The following table lists the crypto assets currently supported by the Orbi Payments Gateway for on-chain deposits. Supported networks vary by environment.

Note
The list of supported assets and networks may expand over time. Always refer to this table or the API responses to determine current availability.

Asset	Name	Production networks	Sandbox networks
`BTC`	Bitcoin	Bitcoin	Bitcoin Testnet
`ETH`	Ethereum	Ethereum	Ethereum Sepolia
`USDT`	USDt Tether	Ethereum, Tron	BNB Smart Chain Testnet
`USDC`	USD Coin	Ethereum	Ethereum Sepolia
`USDG`	Global Dollar	Ethereum	Ethereum Sepolia, Solana Devnet

Environment differences
Sandbox networks are designed for testing and do not represent real value. Production networks process real funds and require additional security considerations.

Amount representation and decimals

All monetary amounts in the Orbi Payments Gateway API are represented as decimal strings, never as floating-point numbers.

Each currency uses a fixed number of decimal places, defined by Orbi to ensure consistent pricing, rounding, and accounting behavior across all payment rails.

Supported decimal precision

Currency	Description	Decimal places
`USD`	US Dollar	2
`MXN`	Mexican Peso	2
`EUR`	Euro	2
`ARS`	Argentine Peso	2
`COP`	Colombian Peso	2
`BRL`	Brazilian Real	2
`USDT`	USDt Tether	6
`USDC`	USD Coin	6
`USDG`	Global Dollar	6
`BTC`	Bitcoin	8
`ETH`	Ethereum	12

Important
Clients must always treat amounts as strings and avoid floating-point arithmetic when constructing or processing API requests.

Precision vs on-chain representation

For crypto deposit rails, Orbi normalizes amounts using the decimal precision listed above for pricing and reconciliation purposes.

The exact on-chain amount received is always preserved internally and is never truncated or modified. Decimal normalization does not affect the actual funds received on-chain.

Rounding rules

When rounding is required (for example, during currency conversions or normalization), Orbi applies banker’s rounding (round half to even).

Banker’s rounding:

Minimizes cumulative rounding bias
Is widely used in financial and accounting systems
Ensures consistent results across large transaction volumes

Example:

Input value	Rounded result
1.005	1.00
1.015	1.02

Rounding is applied only when strictly necessary and never alters the final on-chain settlement amount.

Payment flow

Below is a simplified, end-to-end view of a typical payment flow in Orbi. A more detailed flow (including edge cases and status transitions) is documented in the Payment Orders section.

sequenceDiagram
  autonumber
  participant Customer
  participant MerchantApp as Merchant Backend
  participant OrbiAPI as Orbi PG API
  participant Rail as Payment Rail

  MerchantApp->>OrbiAPI: Create Order (amount, currency, rail)
  OrbiAPI-->>MerchantApp: Order created (order_id, status=awaiting_payment)

  alt Orbi Pay
    Customer->>Rail: Pay via Orbi Pay
    Rail->>OrbiAPI: Payment confirmed (instant)
  else Crypto deposit
    OrbiAPI-->>Customer: Show deposit instructions (address, amount, network)
    Customer->>Rail: Send on-chain transaction
    Rail->>OrbiAPI: Payment detected (after confirmations)
  end

  OrbiAPI->>OrbiAPI: Reconcile payment ↔ order

  OrbiAPI->>MerchantApp: Send event (order/payment update)
  MerchantApp-->>OrbiAPI: 2xx acknowledgement