Transfer orders (/TrexAdmin/GatewayOrders)

Route: /TrexAdmin/GatewayOrders (filtered by TransferOrder)

A TransferOrder is an outgoing payout the merchant creates on behalf of its client onto requisites the client supplied (crypto address, card PAN, IBAN, phone, etc.). It is the mirror image of a payment order: a payment order pulls money in, a transfer order sends money out.

An open order without a terminal is created in Created with funds reserved on the merchant wallet. Selecting a payout terminal moves it to Predicted; completed recipient and metadata requirements produce Verified; provider/network confirmation produces Finished. Draft is not used for TransferOrder. Canceled orders return the reserve.

Operator view vs merchant flow

Merchant side

• Merchants create orders through /payorders/v1/ using merchant authentication:
  • put_transfer_order — create an outgoing payout. With terminalId plus recipient and the terminal's required meta it reserves funds and dispatches the payout leg in one call; with terminalId but without recipient/metadata the leg stays held until pay_transfer fills it; without a terminal it opens a Created order (net reserved) to be started later by the client via order_start.
• The two-phase flow and all order lookups reuse the shared, type-agnostic endpoints (no TransferOrder-specific duplicates), branching by order code type:
  • POST /payment/v1/order_start?… (legacy alias payment_order_start) — phase 2a (start). Re-prices the order, reserves the gross amount, creates a held payout, and returns the terminal's flowPath. It does not collect recipient details or dispatch.
  • POST /payment/v1/pay_transfer?… — phase 2b (send). Supplies recipient and meta/tag, validates the terminal's required req: metadata fields, and releases the payout for dispatch. Custom rails may call it from the merchant continuation page.
  • GET /payment/v1/get_terminals?code=… — lists payout terminals for a Created transfer order (payout filter + FX preview), the same endpoint that lists topup terminals for a payment order.
  • GET /payment/v1/get_order_info?code=… — order info by code, type-agnostic (topup or payout).
  • GET /payorders/v1/get_app_payments / get_app_payment — merchant reads; return every order for the app (TransferOrders included), by id or by code.
  • POST /payment/v1/cancel_order?code=… — universal anonymous cancel by code; address-driven, returns the reserve and closes the payout leg before the rail engages.
• Server-to-server /private/v1/create_transfer_order supports P2P collapse through txGroup: the payout is settled as an internal loopback and is not dispatched to an external network. The integrating service decides whether the transfer qualifies.

Operator / admin side

• /TrexAdmin/GatewayOrders is the staff view of the order, payout details, chosen terminal, applied tariff, and reserve state.
• Typical operator actions: search by code / externalId, inspect state (Created, Verified, Finished, Canceled), trace payout bits (SendedToModule, SendedToNetwork, NetworkConfirmed, Failed | Cancelation | Timeout), and follow up stuck payouts.

Money flow and amounts

Layer	Field	Amount	Currency
Merchant debit	TransferOrder (type 19)	gross reserve (payout debit + fee)	order / debit currency (currency)
Recipient payout	transfer_order_crypto (48) / transfer_order_bank (49) / transfer_order_internal (50)	payout amount	terminal currency

The merchant is debited in the order currency; the recipient receives the payout in the terminal currency. The commission (fee) is charged on the debit side.

Lifecycle seen from the admin page

Created      put_transfer_order without terminalId (open order, net reserved on merchant)
Predicted    terminal chosen (order_start or put_transfer_order with terminalId): gross reserve + held payout leg
Verified     release gate: recipient + required req: meta present
Finished     payout leg NetworkConfirmed -> reserve debited + commissioned
Canceled     cancel_order before the rail starts, or an unclaimed Created order reaches its configured TTL

cancel_order is allowed only before payout processing starts. Once any of SendedToModule, SendedToNetwork, NetworkIn, or NetworkConfirmed is set, the payout is in flight and cancellation returns OrderPaymentInProgress. Successful cancellation closes the payout and returns the merchant reserve.

put_transfer_order flow model and field semantics

put_transfer_order supports a two-sided amount model, mirroring the payment-order forward / reverse behavior.

Field semantics

• currency — merchant debit / order currency. Required. The payout currency comes from the terminal.
• terminalId — optional on create. Omit for open orders (phase 1); required for one-shot dispatch and reverse (payoutAmount) pricing. The terminal must allow withdrawals and TransferOrder operations.
• orderAmount / payoutAmount — the two conversion sides. Provide exactly one:
  • orderAmount (order side, forward) — merchant fixes what it is debited; the recipient gets orderAmount * rate in the terminal currency.
  • payoutAmount (payout side, reverse) — merchant fixes what the recipient receives; the merchant is debited payoutAmount / rate in currency.
• amount — legacy single field. Accepted only when neither orderAmount nor payoutAmount is set (mapped to orderAmount).
• recipient — the recipient requisite (address / PAN / IBAN / phone).
• partnerInfo — payer / client identifier. Required for merchant calls.
• meta — opaque payout JSON validated against the terminal's req:<key> capability tags; dotted keys are supported. Falls back to tag when empty.
• tag — legacy free-form memo / network metadata used when meta is empty.
• externalId — merchant-side order id (optional).

Cross-currency rate and FX markup

For a cross-currency payout, the rate is the mid-rate captured at creation with the terminal currency's payment_spread applied with the outgoing sign:

rate = mid × (1 − payment_spread)      (terminal currency)
payout = orderAmount × rate            (forward)
orderAmount = payoutAmount ÷ rate      (reverse)

This is the mirror of a payment order's mid × (1 + payment_spread): the same per-currency coefficient favors the platform in both directions. payment_spread = 0 means the mid-rate with no markup. Same-currency payouts use rate 1. Cross-currency orders get a short TTL because the captured rate goes stale against the market.

Payout rails

Rail	Marker	Behavior
Crypto	transfer_order_crypto	Uses the terminal's configured hot address and is dispatched on-chain.
Bank / card / wire	transfer_order_bank	Sent to the configured provider integration with recipient, amount, and metadata.
Internal (P2P collapse)	transfer_order_internal	Created with an existing txGroup (private create_transfer_order); loopback, not dispatched to the network.

Validation notes

• terminalId is optional for open orders; required for one-shot and reverse pricing. A missing or ineligible terminal when required returns NoTransferTerminals.
• Both or neither of orderAmount / payoutAmount set (after legacy amount mapping) is rejected (TransferOrderAmountSideAmbiguous).
• Cross-currency requires AllowCrossPayment on the order currency (or a multicurrency terminal), otherwise CurrencyNotAvailableForTransferOrder.
• Requisite shape is validated (InvalidTransferRequisites): recipient length, tag length, and no spaces in crypto addresses. The integrating service owns P2P matching and eligibility.
• The merchant free balance must cover amount + fee, otherwise LowBalance.

Related operator pages

Page	Role
/TrexAdmin/Tariffs	Tariff rules for TransferOrder. network selects the terminal; UseNetFee uses its current network fee.
/TrexAdmin/TokenNetworks	Terminal records: can_withdraw + AllowTransferOrder flags, type_contract, default_hot_address (crypto), network_fee / network_percent_fee.
/TrexAdmin/Currencies	payment_spread — the FX markup, applied with the outgoing sign for payouts; AllowCrossPayment for cross-currency payouts.
/TrexAdmin/Transacts	Detailed transaction state. Use this when GatewayOrders does not show enough state-bit detail.

Related

• Payment orders (admin)
• Fees and tariffs
• Transaction states