Payment Gateway
TrexWallet Payment Gateway lets a merchant create a payment order and let the payer choose one of the enabled payment terminals: crypto, built-in card acquiring, internal wallet balance, or a merchant continuation flow.
The payment UI is available under /pay and /pay-auth. See the
TrexWallet PWA changelog for user-facing changes.
Integration responsibilities
| Participant | Responsibility |
|---|---|
| TrexWallet | Payment order lifecycle, tariff application, wallet ledger, built-in payment methods, refunds, statistics. |
| Merchant integration | Provider-specific pages and API calls for custom card widgets, P2P matching, bank wire, or other custom flows. |
| Built-in card acquiring | Stripe and T-Bank checkout, provider callbacks, and reconciliation. |
Custom logic starts from the browser through the terminal continuation path configured by the
operator. order_start locks the terminal and tariff first; the merchant integration then
handles provider-specific work and reports status against the existing order.
For strict request/response contract details of merchant order creation, see:
Payment Orders Admin: put_payment_order flow model.
Entry Points
Merchant Backend Integration
The merchant backend creates a payment order through the merchant API. Depending on the request, the order can be open-ended (payer selects a terminal) or locked to a specific terminal at creation time.
Typical result contains:
- payment order id;
- payment code for
/pay; - amount and currency to pay;
- optional rate snapshot for cross-currency payments;
- optional continuation path for custom terminals.
For runnable Python and Node.js snippets (creating orders and polling payment results with proper rate-limit / failover handling), see Payment Integration Examples.
Universal /pay Page
The payer opens /pay?code=.... The page loads order information and available
terminals, then:
- shows a currency / terminal picker for open orders;
- starts the order with the selected terminal;
- renders a built-in widget, opens provider checkout, or redirects to customer continuation;
- shows the final status after payment confirmation.
Authenticated /pay-auth Page
Internal wallet-balance payments require an authenticated user session. The payer
is redirected to /pay-auth for that flow.
Built-in Payment Methods
| Method | Payer Experience | Operator Notes |
|---|---|---|
| Crypto | Payer receives a deposit address and sends funds on-chain. | Configure network, hot/system address, tariff, and scanner. |
| Built-in card acquiring | Payer is redirected to provider checkout. | Configure the Stripe or T-Bank terminal and provider credentials. |
| Internal wallet balance | Payer pays from their existing TrexWallet balance. | Requires login and sufficient balance. |
Merchant continuation
Custom provider flows live in the merchant application. Examples include custom card widgets, P2P requisites, bank wire instructions, or any provider-specific UX.
The operator configures a flow path on the terminal. When a payer selects that
terminal, /pay redirects to the merchant continuation page with the payment code
as the code query parameter. The payment page does not append terminalId; the selected
terminal is already locked on the order and must be resolved from that order context. When
country selection is required, the page also appends countryCode. The merchant integration
then performs provider work and reports the result through the private integration API.
Rules:
- The flow path is a relative route in the merchant web application, not a public API endpoint.
- Empty flow path means built-in TrexWallet handler.
- The merchant integration does not apply tariffs; TrexWallet applies tariffs before the continuation starts.
- The merchant integration should report only provider status and provider references.
Tariffs and Cross-Currency Orders
TrexWallet applies the tariff once, when the order is locked to a terminal. For cross-currency payments, TrexWallet snapshots the rate at that moment and uses the currency payment spread configured by the operator.
Operators configure:
- per-terminal payment-order eligibility;
- optional per-terminal country availability;
- currency cross-payment availability;
- payment spread;
- merchant-specific tariff overrides;
- terminal partner-info requirement when compliance needs sender metadata.
Country Availability
TrexWallet can hide payment terminals by payer country before the payer starts an order. This is a per-terminal setting — configuration and exact behavior are documented once on the admin page that owns terminals: Tokens and Networks admin → Country Restrictions.
Note for merchant-created locked orders: the country check is enforced when the payer opens /pay and the browser starts the payment (that is when the payer country is known), not at order creation time.
Payment Statistics and Guardrails
TrexWallet serves daily payment statistics by UTC day, app, currency, and
transaction type. Optional conversion guardrails evaluate each app's completed previous UTC day
using the exact ratio (total - finished) / finished; they do not use a rolling in-memory window
or merchant-wallet dimension. A separate guard can limit open orders by payer identifier.
Refunds
Refunds are handled through the merchant order API. Operators can inspect refund state from the Payment Orders admin page.
Operator Checklist
- Create or enable a terminal in
/TrexAdmin/TokenNetworks. - Ensure the terminal is allowed for payment orders.
- If needed, configure terminal Countries and verify payer-country detection.
- Configure tariff rules in
/TrexAdmin/Tariffs. - For built-in card acquiring, configure provider credentials.
- For merchant continuation, set the terminal flow path and verify that the route exists.
- Test with a small order and verify it appears in
/TrexAdmin/GatewayOrders.
Troubleshooting
| Symptom | Likely Cause | Where to Check |
|---|---|---|
Terminal is not shown on /pay | Terminal disabled, unsupported currency, missing tariff, app filter, country filter, or scope filter. | /TrexAdmin/TokenNetworks, Tariffs, payer-country detection, Payment Orders admin. |
| Payer is redirected to wrong page | Flow path misconfigured. | Terminal flow path in /TrexAdmin/TokenNetworks. |
| Card checkout URL is missing | Built-in acquiring is not configured or the provider rejected session creation. | Service logs and provider dashboard. |
| Order stuck pending | Provider callback delayed or reconciliation not running. | Payment Orders admin, scanner status. |
| Cross-currency amount looks wrong | Rate snapshot or spread configuration. | Tariffs and currency settings. |