Orders, Wallet & Transactions

All endpoints on this page are read-only. Use them to poll async operation results, check balances, and retrieve transaction history.

`GET /orders` — list orders

Ability: orders.read

Query	Type	Description
`page` / `per_page`	int	Pagination (`per_page` default 50)
`status`	string	Status filter (see Order status)
`type`	string	Type filter (see Order type)

Each order row:

Field	Type	Notes
`uuid`	uuid
`type`	string	See Order type
`status`	string	See Order status
`failure_reason`	string?	Null unless failed — see Failure reason
`held_amount` / `currency`	string
`created_at`	datetime

`GET /orders/{uuid}` — get one order

Ability: orders.read

Response: 200 order detail (same fields as the list, used to poll async results) / 404 order.not_found

Polling pattern: call this endpoint every 2–5 seconds until status becomes completed or failed.

`GET /wallet` — wallet balance

Ability: wallet.read

Success 200:

{
  "data": {
    "workspace_id": 12,
    "wallets": [
      {
        "currency": "USD",
        "balance": "880.00",
        "held_balance": "106.00",
        "available": "774.00",
        "frozen_at": null,
        "frozen_reason": null,
        "last_reconciled_at": "2026-06-08T00:00:00+00:00"
      }
    ]
  }
}

wallets is an array of per-currency balances. All amounts are decimal strings. available = balance − held_balance.

`GET /transactions` — wallet ledger

Ability: transactions.read

Query	Type	Description
`page` / `per_page`	int	Pagination (`per_page` default 50)
`reason`	string	Filter by ledger reason code (see Ledger reason)
`reference_type`	string	Filter by reference type (e.g. `Card`, `Ticket`, `Subscription`)
`reference_uuid`	uuid	Filter by reference UUID
`from` / `to`	datetime	Time window (ISO 8601)

Each ledger row:

Field	Type	Notes
`id`	int
`txn_group_id`	string	Groups the double-entry pair
`reason_code`	string	Ledger reason — see Ledger reason
`direction`	int	`1` = Debit, `2` = Credit (integer, not a string)
`direction_label`	string	`"Debit"` / `"Credit"`
`amount` / `currency`	string	Amount is always positive; side given by `direction`
`account_code`	string?
`account_card_uuid`	uuid?	UUID of the related card, if any
`reference_type`	string?	Type of the related object (e.g. `Card`, `Ticket`)
`reference_uuid`	uuid?	UUID of the related object — use to deep-link to card detail, ticket, etc.
`description`	string?
`created_at`	datetime

⚠️ direction is returned as an integer (1/2), not a snake_case string. This is the one exception to the general convention. Always check direction_label for a human-readable label.

Enum reference

Order status

Value	Meaning
`pending`	Created, not yet processing
`processing`	Processing with the supplier
`awaiting_platform`	Awaiting platform intervention (admin retry / async fallback)
`completed`	Completed (terminal ✓)
`failed`	Failed (terminal ✗)

Order type

Value	Meaning
`issue_card`	Issue a card
`topup_card`	Top up a card
`close_card`	Close a card
`freeze`	Freeze a card
`unfreeze`	Unfreeze a card

Order failure reason

⚠️ These API strings differ slightly from internal storage — the API returns supplier5xx / business4xx (no underscore before the digits).

Value	Meaning
`supplier5xx`	Supplier returned a 5xx (transient; auto-retried)
`timeout`	Request timed out (transient; auto-retried)
`network`	Network error (transient; auto-retried)
`signature`	Signature verification issue (transient; auto-retried)
`business4xx`	Supplier business rejection (terminal; needs admin)
`not_found`	Supplier reports not found (terminal; needs admin)
`preempted_by_risk`	Preempted by the risk engine
`admin_refund_close`	Admin refund-closed the order
`async_issue_failed`	Asynchronous issuance failed

Ledger reason code

Value	Meaning
`card_issue_held`	First top-up at issuance — funds parked in held
`card_topup_held`	Subsequent top-up — funds parked in held
`held_capture`	Held → final destination (card held + platform revenue)
`held_release`	Held → workspace balance (supplier failed)
`held_release_admin`	Held → workspace balance via admin queue
`card_issue_fee`	Card-issue fee → platform revenue
`card_topup_fee`	Card top-up fee → platform revenue
`card_close_refund`	Card closure: card held → workspace balance
`usdt_deposit`	USDT deposit → workspace balance
`usdt_deposit_fee`	USDT inflow channel fee → platform revenue
`withdrawal_held`	Withdrawal hold: balance → held
`withdrawal_completed`	Withdrawal paid out: held → pool + revenue
`withdrawal_canceled`	Owner cancelled withdrawal: held → balance
`withdrawal_rejected`	Admin rejected withdrawal: held → balance
`card_spend`	Card spend settled — held → platform (card debit leg)
`card_spend_refund`	Card spend refund — platform → workspace
`card_spend_reversal`	Card spend reversal — platform → workspace
`card_post_close_clawback`	Post-close clawback — workspace → platform (late charge after card closed)
`card_post_close_refund`	Post-close refund — platform → workspace
`card_reconcile_adjustment`	Manual reconciliation adjustment (admin only)
`subscription_charge`	Subscription charge → platform revenue
`risk_penalty`	Risk-engine penalty fee per declined transaction (may push wallet negative)
`reversal`	Reversal / red-letter correction (admin only)

Ledger direction

`direction` (int)	`direction_label`	Meaning
`1`	`"Debit"`	Debit side (+Asset / +Expense)
`2`	`"Credit"`	Credit side (−Asset / −Expense)

Schema: Order

Field	Type	Notes
`uuid`	uuid	Order identifier
`type`	string	See Order type
`status`	string	See Order status
`related_card_uuid`	uuid?	UUID of the related card, if any
`held_amount`	string	Held amount, e.g. `"106.00"`
`currency`	string	e.g. `"USD"`
`created_at`	datetime