> For the complete documentation index, see [llms.txt](https://developers.unigox.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.unigox.com/api-reference/orders.md).

# Orders

Order management, status tracking, and lifecycle actions

## Order details

> Get the current status, amounts, and full timeline for a specific order.\
> The \`next\_action\` field indicates what the partner \*\*must\*\* do to advance the order.\
> \`null\` means no action is required from the partner at this stage — the order is waiting\
> for the counterparty (e.g. the buyer to submit fiat payment proof).\
> \
> The \`allowed\_actions\` array lists all API actions the partner \*\*can\*\* perform at the current\
> status. An action can be in \`allowed\_actions\` even when \`next\_action\` is absent — this means\
> the action is optional. For example, on an ordinary off-ramp order \`confirm-fiat-received\` is\
> available at \`crypto\_received\` as a fast-track: if you already know the fiat has arrived (via\
> your own systems), you can confirm immediately without waiting for the buyer's payment proof\
> flow to complete.\
> \
> \*\*That fast-track does not exist on a delayed settlement (T+1) order.\*\* There the crypto\
> leaves escrow before the customer is paid, so at \`crypto\_received\` \`confirm-fiat-received\` is\
> \*\*removed\*\* from \`allowed\_actions\` and the endpoint refuses the order; \`\["settlement-consent",\
> "cancel"]\` take its place and \`next\_action\` is \`sign\_settlement\_consent\`, then\
> \`submit\_source\_of\_funds\` or \`await\_review\` — the latter meaning the order is waiting on us, for\
> any required source-of-funds approval, for the licensed partner's payment check and for crypto\
> release. Branch on \`delayed\_settlement\` — the two orders share a status and differ in everything\
> you may do with it. See the Delayed settlement (T+1) reference.\
> \
> \`allowed\_actions\` is \`\[]\` for a \*\*widget order\*\* — one your customer created through the\
> embedded widget under your \`widgetKey\`. Those orders are attributed to you, and readable\
> here, but the crypto is the end user's, so every action endpoint answers \`404\
> ORDER\_NOT\_FOUND\` for them. \`status\`, \`next\_action\` and the timeline still describe the\
> order; they describe your customer's step, not one for you to take.\
> \
> \*\*A \`cancelled\` order can still owe you money.\*\* An off-ramp order that stopped after its\
> escrow was funded reads \`cancelled\` — the same as one that never funded and the same as one\
> whose refund has already been paid out. The status does not distinguish them and never will.\
> What distinguishes them is \`allowed\_actions\`: \`\["authorize-refund"]\` means the crypto is\
> still in the escrow and your signature is the only thing that can send it back, with\
> \`next\_action: "authorize\_refund"\` and \`action\_required\` naming the endpoint. Check it before\
> writing an order off. The \`order.refund.required\` webhook says the same thing once, if you\
> would rather not poll.\
> \
> \*\*Order flow summary:\*\*\
> \
> \| Status | next\_action | Who acts |\
> \|---|---|---|\
> \| \`created\` | — | Partner (or wait for vendor match) |\
> \| \`awaiting\_crypto\_transfer\_authorization\` | \`authorize\_crypto\_transfer\` | \*\*Partner\*\* |\
> \| \`crypto\_transfer\_authorization\_pending\` | — | System (on-chain confirmation) |\
> \| \`crypto\_received\` | — | \*\*Buyer\*\* submits fiat payment proof |\
> \| \`fiat\_payment\_started\` | — | System reviews proof |\
> \| \`fiat\_payment\_review\_started\` | — | System accepts/rejects proof |\
> \| \`awaiting\_fiat\_received\_confirmation\` | \`confirm\_fiat\_received\` | \*\*Partner\*\* |\
> \| \`completed\` | — | — |\
> \
> A \*\*delayed settlement (T+1)\*\* order replaces the \`crypto\_received\` row — no buyer submits\
> proof, because the fiat is paid after the release, not before:\
> \
> \| Status | next\_action | Who acts |\
> \|---|---|---|\
> \| \`crypto\_received\` | \`sign\_settlement\_consent\` | \*\*Partner\*\* signs the release |\
> \| \`crypto\_received\` | \`submit\_source\_of\_funds\` | \*\*Partner\*\* supplies the source-of-funds case |\
> \| \`crypto\_received\` | \`await\_review\` | \*\*Unigox\*\*: document review, the licensed partner's payment check, or release processing |\
> \| \`crypto\_received\` | — | Held: Unigox holds the order for a check, or a payout failed and a refund is under way |\
> \| \`settlement\_in\_progress\` | — | Payout in flight; the fiat has not arrived |\
> \| \`returned\` | — | The bank sent the payout back; Unigox pays again or refunds the crypto |\
> \
> The "Who acts" column describes an order \*\*you\*\* created. On a widget order the rows\
> reading \*\*Partner\*\* are your customer's step, not yours — \`next\_action\` is populated the\
> same way for both, because it describes where the order stands rather than who may move\
> it. \`allowed\_actions\` is what tells you apart: \`\[]\` on a widget order at every status.\
> Acting on a \`next\_action\` for a widget order returns \`404 ORDER\_NOT\_FOUND\`. A delayed order\
> is never a widget order: the wallet must be yours for anyone on this API to sign the release.\
> \
> \*\*Fiat settlement and confirmation\*\* (ordinary orders; a delayed order never takes a fiat\
> confirmation)\*\*:\*\*\
> \
> You can call \`confirm-fiat-received\` at any time after crypto is in escrow.\
> You do not need to wait for a system notification. If you know through your\
> own systems that the recipient has received the fiat payment, confirm immediately.\
> \
> Some liquidity providers also send automatic settlement confirmations when the\
> recipient receives the fiat. When the order's \`has\_fiat\_settlement\_notification\`\
> is \`true\` (see the quote/order response), the order moves to \`completed\` on its own\
> and you receive the \`status=completed\` webhook — no manual confirm needed. If you\
> already confirmed manually, the auto-confirmation is a no-op; if the auto-confirmation\
> arrives first, your manual confirm call is also a no-op. Both paths are safe. See the\
> Webhooks page → "Settlement notifications" for details.\
> \
> \*\*How to implement:\*\*\
> \- Always implement a \`confirm-fiat-received\` call in your flow.\
> \- Listen for webhooks. If you receive \`status=completed\`, no further action needed.\
> \- If \`next\_action=confirm\_fiat\_received\`, call \`confirm-fiat-received\` when you\
> &#x20; know fiat has been received.\
> \- Do not wait for \`next\_action\` if you already have confirmation from your\
> &#x20; own banking or payment systems.\
> \- On a delayed order do not call \`confirm-fiat-received\`, and treat \`completed\` as\
> &#x20; meaning the fiat actually reached the customer.\
> \
> \*\*Possible statuses:\*\* see \`PartnerOrderStatus\`. Off-ramp: \`created\`, \`awaiting\_liquidity\_provider\`, \`awaiting\_crypto\_transfer\_authorization\`, \`crypto\_transfer\_authorization\_pending\`, \`crypto\_received\`, \`fiat\_payment\_started\`, \`fiat\_payment\_review\_started\`, \`dispute\_started\`, \`awaiting\_fiat\_received\_confirmation\`, \`completed\`, \`cancelled\`, \`failed\`, \`price\_changed\_requote\_needed\`, plus \`settlement\_in\_progress\` and \`returned\` on a delayed order. On-ramp: \`awaiting\_vendor\_escrow\_funding\`, \`awaiting\_fiat\_transfer\`, \`fiat\_transfer\_pending\`, \`send\_out\_pending\`, \`send\_out\_completed\`, \`send\_out\_failed\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management, status tracking, and lifecycle actions"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PartnerOrderResponse":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid","description":"Unique order identifier"},"status":{"$ref":"#/components/schemas/PartnerOrderStatus"},"next_action":{"type":"string","description":"The action the partner **must** perform to advance the order. The key is **absent**\nwhen no action is required at this stage — the order is waiting for the\ncounterparty or for an automated system step — and is never sent as `null`.\n\nPossible values:\n- `authorize_crypto_transfer` — partner must authorize escrow funding\n- `confirm_fiat_received` — partner must confirm they received the fiat payment\n- `request_new_quote` — price changed, partner must request a new quote\n- `update_kyc_address` — address fields are required for EUR/AUD/GBP payouts; see `action_required` for the endpoint and fields to submit\n- `authorize_refund` — the order ended without a payout and its crypto is still in escrow; only your\n  signature can send it back. Note that this appears on an order whose `status` is `cancelled`, which\n  is the one case where a terminal status still needs something from you\n- `deposit_to_user_account` — an on-ramp order with `fiat_funding_source: own_account` is waiting for the\n  customer to transfer the order's fiat amount into the fiat account issued to them. The transfer\n  itself confirms the payment; there is nothing to call. If the money is already on the account,\n  `pay-from-balance` is in `allowed_actions` and pays the order from it\n- `sign_settlement_consent` — a **delayed settlement (T+1)** order remains at `crypto_received`\n  and nobody has signed the release yet\n- `submit_source_of_funds` — consent is stored and a required source-of-funds case is\n  incomplete, including an existing case below the current threshold\n- `await_review` — consent is stored and the order is waiting for Unigox document review,\n  the licensed partner's payment check, or release processing. Do not submit another signature\n- absent — no required action (waiting for buyer or system). On a funded delayed order awaiting release\n  the key is absent when the order is held for review, or a payout of yours failed and a\n  refund is under way\n\nOnce consent_deadline_at has passed, these reads no longer request a consent signature,\neven if the order status has not changed yet.\nThe list (`GET /api/v1/partner/orders`) reads the consent from the order record and can show\n`await_review`, for up to two minutes, for a consent call that was cut off before your signature\nwas stored. After a\ntimeout, read the single order (`GET /api/v1/partner/orders/{order_id}`) before you decide\nwhether to send the signature again. If a lookup behind the T+1 hint fails, both reads fall\nback to `sign_settlement_consent`.\n","enum":["authorize_crypto_transfer","confirm_fiat_received","request_new_quote","update_kyc_address","authorize_refund","deposit_to_user_account","sign_settlement_consent","submit_source_of_funds","await_review"]},"action_required":{"type":"object","nullable":true,"description":"Present when the order needs partner intervention before it can proceed.\nContains machine-readable type, human-readable message, the API endpoint to call,\nand the fields to provide. Null/omitted when no action is needed.\n","required":["type","message"],"properties":{"type":{"type":"string","description":"Machine-readable action identifier"},"message":{"type":"string","description":"Human-readable explanation of what is needed and why"},"endpoint":{"type":"string","description":"API endpoint to call to resolve this action"},"fields":{"type":"array","description":"Fields the partner needs to provide","items":{"type":"object","required":["field","label"],"properties":{"field":{"type":"string","description":"API field name"},"label":{"type":"string","description":"Human-readable description of the field"}}}}}},"allowed_actions":{"type":"array","items":{"type":"string"},"description":"List of API actions the partner **can** perform at the current status. An action\nmay be present here even when `next_action` is absent — meaning it is optional.\n\nNotable case: `confirm-fiat-received` appears at both `crypto_received` and\n`awaiting_fiat_received_confirmation`. At `crypto_received` it is a **fast-track**:\nif you already know the fiat has arrived via your own systems, you can confirm\nimmediately. Otherwise, wait for the buyer's proof flow to complete — the order\nwill reach `awaiting_fiat_received_confirmation` automatically.\n\nStatus-to-actions mapping:\n- `created` → `[\"cancel\"]`\n- `awaiting_liquidity_provider` → `[\"cancel\"]`\n- `awaiting_crypto_transfer_authorization` → `[\"authorize-crypto-transfer\", \"cancel\"]`\n- `crypto_transfer_authorization_pending` → `[]` (the transfer is in flight; cancel is refused)\n- `crypto_received` → `[\"confirm-fiat-received\"]` (optional fast-track)\n- `fiat_payment_started` → `[\"confirm-fiat-received\"]` (optional fast-track after buyer proof submission)\n- `awaiting_fiat_received_confirmation` → `[\"confirm-fiat-received\"]` (required)\n- `fiat_received_confirmed`, `crypto_release_pending`, `completed`, `failed` → `[]`\n- `cancelled` → `[]`, **except** when the order's crypto is still sitting in escrow: then\n  `[\"authorize-refund\"]`. An off-ramp order that stops after funding — expired payment window,\n  declined payment proof, returned bank payment, dispute resolved for the seller — reads as\n  `cancelled` like every other stopped order, and the escrow is a 2-of-3 Safe your key is an\n  owner of. This is the only thing that tells the two apart, so poll it on `cancelled` orders\n  rather than assuming a cancelled order is finished with. `next_action` is\n  `authorize_refund` and `action_required` names the endpoint at the same time.\n\nOn-ramp orders with `fiat_funding_source: own_account` never offer `confirm-payment-sent`: the\ntransfer into the customer's own account is the confirmation. At `awaiting_fiat_transfer` they\noffer `[\"pay-from-balance\"]` instead, until the order's fiat has been collected. A `completed`\norder paid from the balance whose crypto hand-over has not finished also offers\n`[\"pay-from-balance\"]`: calling it again retries the hand-over and never takes the money twice.\n\nOn a funded **delayed settlement (T+1)** order awaiting release whose crypto you hold,\n`confirm-fiat-received` is removed — the endpoint behind it refuses a delayed order — and\n`[\"settlement-consent\", \"cancel\"]` take its place.\n\n`cancel` is available only while the order awaits release; the endpoint is the ordinary\n`POST /api/v1/partner/orders/{order_id}/cancel`.\n\nBoth are withdrawn once the consent is signed, and then answer\n`409 OPERATION_NOT_ALLOWED`. The list reads the consent from the order record, so a list row\ncan already show them withdrawn, for up to two minutes, for a consent call that was cut off\nbefore your signature was\nstored. After a timeout, read the single order (`GET /api/v1/partner/orders/{order_id}`)\nbefore you decide whether to send the signature again.\n\nOn a funded delayed order awaiting release that is **held** — Unigox holds it for a check, or a\npayout failed and a refund is under way — `next_action` is omitted and no consent is accepted.\n`confirm-fiat-received` is absent there too, because that endpoint refuses every delayed\norder. An `authorize-refund` that is genuinely owed still appears.\nCustody outranks the mapping above: on a **widget order** — one your customer created\nthrough the embedded widget under your `widgetKey` — this is `[]` at every status,\nbecause the crypto is the end user's and every action endpoint answers `404\nORDER_NOT_FOUND` for it.\n"},"fiat_funding_source":{"type":"string","enum":["vendor_details","own_account"],"description":"On-ramp orders only. Where the fiat for this order is paid:\n- `vendor_details` — to the vendor's bank account in `vendor_payment_details`; then call\n  `confirm-payment-sent`.\n- `own_account` — into the fiat account you issued to the customer, named by\n  `fiat_account_id`. There are no `vendor_payment_details` and no `confirm-payment-sent`:\n  the transfer landing on the customer's account is matched to the order by amount and the\n  order proceeds on its own.\n\nRead it on every order rather than assuming one or the other.\n"},"fiat_account_id":{"type":"string","format":"uuid","description":"On an `own_account` order: the fiat account the customer transfers into. The same id the\nFiat Accounts endpoints take, so the deposit that funds this order can be found on that\naccount's transactions carrying this order's id.\nOn an off-ramp with `payout_via_own_account: true`: the customer's fiat account the money\ngoes through, when it is one you can address by id; omitted otherwise.\n"},"payout_via_own_account":{"type":"boolean","description":"`true` on an off-ramp paid through the customer's own fiat account: the liquidity provider\npays the customer's account and Unigox then pays the money on to the bank you named, both in\nthe customer's name. EUR and GBP off-ramps to the customer's own `payment_details` are paid\nthis way wherever customer fiat accounts are active for your partner in that currency; when\nthey cannot be, the quote is refused (`FIAT_ACCOUNT_OPENING`, `FIAT_ACCOUNT_REQUIRED`,\n`FIAT_ACCOUNTS_NOT_ENABLED`) unless a liquidity provider that pays banks directly takes the\norder. Omitted on every other order, never `false`. If you do not call\n`confirm-fiat-received`, the order is confirmed once Unigox has matched the money on the\ncustomer's account. That payment into the account does not send\n`fiat_account.deposit.received`.\n"},"own_account_payout_status":{"type":"string","enum":["awaiting_credit","in_progress","sent_to_bank","under_review","held","left_on_account"],"description":"Off-ramp paid through the customer's own fiat account only (`payout_via_own_account: true`):\nwhere the onward payment, from that account to the bank you named, stands. `status` describes\nthe provider's payment into the customer's account, so an order can be `completed` while this\nstill says the money has not reached the bank.\n- `awaiting_credit` — nothing has landed on the customer's account for this order yet.\n- `in_progress` — the money landed; the onward payment is queued, being sent, or being retried.\n- `sent_to_bank` — the money was sent on to the bank you named.\n- `under_review` — the onward payment ended without a clear result; Unigox checks it.\n- `held` — the money is on the customer's account and is not moving on by itself; contact Unigox.\n- `left_on_account` — Unigox decided the money stays on the customer's account.\n\nOmitted on other orders, and when the state cannot be read at that moment.\n"},"crypto_transfer_authorization_seconds_left":{"type":"integer","format":"int64","nullable":true,"description":"Remaining seconds to authorize crypto transfer while order is in\n`awaiting_crypto_transfer_authorization` / `crypto_transfer_authorization_pending`.\n`null` for all other statuses.\n"},"amounts":{"$ref":"#/components/schemas/PartnerOrderAmounts"},"fee_breakdown":{"$ref":"#/components/schemas/FeeBreakdown"},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/TimelineEntry"},"description":"Chronological list of status changes"},"has_fiat_settlement_notification":{"type":"boolean","description":"Whether the matched liquidity provider sends fiat settlement notifications.\nWhen `true`, the order will complete automatically when fiat is delivered.\nWhen `false`, you must call `confirm-fiat-received`. You can call\n`confirm-fiat-received` at any time regardless of this value, except on a delayed\nsettlement (T+1) order, which refuses it. `false` on every order no liquidity provider\nhas accepted yet, T+1 included; a T+1 order reads `true` from its acceptance on.\n"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"order_type":{"type":"string","enum":["offramp","onramp"],"description":"Order type. Present on every order, including one no liquidity provider has accepted yet.\n- `offramp` — sell crypto for fiat\n- `onramp` — buy crypto with fiat\n"},"vendor_payment_details":{"type":"object","nullable":true,"description":"Vendor's payment details for the end-user to send fiat to.\nPresent only for on-ramp orders at `awaiting_fiat_transfer` status and beyond.\n","properties":{"payment_method_name":{"type":"string"},"payment_network_name":{"type":"string"},"details":{"type":"object","description":"Payment method-specific fields (e.g. account_number, phone)"}}},"payment_request":{"type":"boolean","nullable":true,"description":"`true` if the vendor uses payment request flow — the partner must call\n`submit-payer-details` before `confirm-payment-sent`.\n"},"send_out_tx_hash":{"type":"string","nullable":true,"description":"Destination-chain transaction hash after a send-out completes.\nPresent only for on-ramp orders with `send_out_completed` status.\n"},"payment_deadline_at":{"type":"string","format":"date-time","nullable":true,"description":"On-ramp only: the moment the order can be cancelled for want of the customer's fiat.\nTell the customer to pay before it. The order is cancelled shortly after it (`cancelled`,\n\"Payment window expired\"): on your next read of the order, and an `own_account` order\nwithin about 20 minutes even if nobody reads it. A transfer that arrives after this moment but before the cancellation may\nstill complete the order; that is possible, not guaranteed. One that arrives after the\ncancellation stays on the customer's account and can be used with `pay-from-balance` on a\nnew order. Extended along with the window.\nSet while the order is `awaiting_fiat_transfer`, `null` otherwise — and always `null`\non an off-ramp, and on an order held for manual handling (it does not expire). UTC.\n"},"recipient_context":{"allOf":[{"$ref":"#/components/schemas/PartnerRecipientContext"}],"nullable":true,"description":"Immutable third-party recipient context; absent for self-payout and on-ramp."},"compliance":{"allOf":[{"$ref":"#/components/schemas/PartnerComplianceCase"}],"nullable":true,"description":"Current durable compliance-case state for a third-party payout."},"delayed_settlement":{"type":"boolean","description":"Whether this order settles **T+1**: the crypto leaves escrow before the fiat is paid.\nYour release signature authorises it to leave and Unigox performs the release; the fiat\nis expected within `settlement_hours` of it (a target, not a deadline). Present on every\norder, on-ramp included, along\nwith the other T+1 fields below. T+1 timestamps and the window are null on instant\norders. The current numeric source-of-funds threshold is still returned.\n\nProvisional until a licensed partner accepts the order. While an order quoted T+1 waits for\none, it follows the offer the order is currently offered to, so it can change: it reads\n`false` between offers and on an instant offer. Once such an order stops waiting without\nbeing accepted (you cancelled it, or no licensed partner accepted it), it keeps `true`,\nwith `settlement_hours` `null`. Fixed from acceptance.\n"},"settlement_hours":{"type":"integer","nullable":true,"description":"The expected payout window, counted from the release — not from the order. It is the licensed partner's target for the bank payment, not a guaranteed deadline: nothing happens automatically when it passes. Rounded to the nearest whole hour and never below `1`. `null` on an instant order."},"consent_deadline_at":{"type":"string","format":"date-time","nullable":true,"description":"Funding time plus the consent window. After expiry, release is blocked and the expiry\nprocess starts the refund flow. Set while awaiting release, `null` otherwise.\n"},"payout_deadline_at":{"type":"string","format":"date-time","nullable":true,"description":"Release time plus the expected window; `settlement_hours` is that window rounded to whole\nhours. When the payment is expected by, not a deadline: the order does not change and no\nevent is sent when it passes. `null` until the crypto has left escrow.\n"},"delayed_settlement_crypto_sent_to_provider_at":{"type":"string","format":"date-time","nullable":true,"description":"The crypto left the licensed partner's wallet for the payout provider. Set at the latest when Unigox authorizes the bank payment. No refund of the crypto is possible while it is set. Cleared when Unigox withdraws a record made by mistake, which it can do only while no payment has been authorized, sent, paid or returned, and when it refunds the crypto after a returned payment."},"delayed_settlement_fiat_payout_authorized_by_admin_at":{"type":"string","format":"date-time","nullable":true,"description":"Unigox authorized the licensed partner to send the bank payment. Never set before `delayed_settlement_crypto_sent_to_provider_at`: the authorization sets that one too when it is still `null`. Cleared by a bank return, and when the payout provider cancels the payment before sending it; Unigox then authorizes a new attempt."},"delayed_settlement_fiat_payout_submitted_by_provider_at":{"type":"string","format":"date-time","nullable":true,"description":"Submission of the bank payment was recorded; recipient payment is not yet confirmed."},"delayed_settlement_fiat_paid_to_customer_at":{"type":"string","format":"date-time","nullable":true,"description":"The fiat reached the recipient. This is the real completion of a delayed order."},"delayed_settlement_fiat_returned_by_bank_at":{"type":"string","format":"date-time","nullable":true,"description":"The payout went out and the bank sent it back. Set together with clearing the paid, submitted and authorized marks. Mutually exclusive with `delayed_settlement_fiat_paid_to_customer_at`. A payment the payout provider cancelled before sending it is not a return and does not set it."},"delayed_settlement_crypto_refunded_to_customer_at":{"type":"string","format":"date-time","nullable":true,"description":"The crypto went back to the wallet that funded the escrow (yours, on an order whose crypto you hold) instead of being paid out. Reachable while `delayed_settlement_crypto_sent_to_provider_at` is `null`, or after a returned payment when Unigox gives the payout up; that refund clears `delayed_settlement_crypto_sent_to_provider_at`."},"source_of_funds_required":{"type":"boolean","description":"Whether review applies by amount or an existing source-of-funds case. Can stay true after approval or completion; use case status and next_action for required action. False for instant orders. Always present."},"source_of_funds_threshold_usd":{"type":"number","description":"Current configured source-of-funds threshold in USD, not a historical snapshot. Always present, including on instant orders. Current policy is USD 50,000 inclusive."},"settlement_refund_reason":{"type":"string","description":"Why a delayed order ended without a payout. Omitted — not empty — when the order has not\nended that way, or when none of the six applies; an absence means no reason was recorded\nand never stands in for one of them.\n\n- `refunded_after_release` — the crypto had been released to the licensed partner and\n  was sent back: before it reached the payout provider, or after a payment came back and\n  Unigox gave the payout up. No payment reached the customer; the order reads `cancelled`\n- `dossier_rejected` — a reviewer refused the source-of-funds case\n- `consent_window_expired` — the consent was never signed and the window ran out\n- `not_released_in_time` — the consent **was** signed and the window still ran out,\n  because Unigox did not release the crypto in time. This one is ours, not the\n  customer's\n- `cancelled_by_customer` — the order was cancelled on your side before release\n- `cancelled_by_licensed_partner` — the licensed partner declined the order before the\n  release was signed\n\nRead in that order: a refund after the release outranks a refusal, which outranks an\nexpired window, which outranks a cancellation.\n","enum":["refunded_after_release","dossier_rejected","consent_window_expired","not_released_in_time","cancelled_by_customer","cancelled_by_licensed_partner"]}}},"PartnerOrderStatus":{"type":"string","description":"Order status.\n\n**Off-ramp statuses (crypto → fiat):**\n- `created` — order created, quote locked\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_crypto_transfer_authorization` — partner must authorize crypto transfer via EIP-712 signature\n- `crypto_transfer_authorization_pending` — authorization submitted, awaiting on-chain confirmation\n- `crypto_received` — crypto locked in escrow\n- `fiat_payment_started` — buyer submitted fiat payment proof\n- `fiat_payment_review_started` — the proof is under review\n- `dispute_started` — a dispute was raised on the order\n- `awaiting_fiat_received_confirmation` — waiting for partner to confirm fiat receipt\n- `fiat_received_confirmed`, `crypto_release_pending` — timeline vocabulary. They appear in\n  `timeline[].status`; no order reports either as its own `status`, and filtering on them\n  returns nothing\n- `completed` — order fully completed\n- `cancelled` — order cancelled\n- `failed` — terminal error\n- `price_changed_requote_needed` — slippage exceeded at initiation. Like\n  `awaiting_liquidity_provider`, it is reported before a liquidity provider has accepted\n  the order, and `GET /partner/orders?status=` returns the orders that report it\n\n**Delayed settlement (T+1) statuses:**\n\n> Both are unreachable for an ordinary order.\n\n- `settlement_in_progress` — crypto release has started or is confirmed; the order is not\n  yet resolved. This alone does not mean a bank payment has been sent\n- `returned` — the payout went out and the bank sent it back, with no new payout\n  authorization. The crypto is not refunded yet: Unigox arranges another payout attempt, or\n  refunds the crypto and the order reads `cancelled`. A payout the provider cancelled before\n  sending it is not a return\n\nPrecedence on a delayed order, in this order — more than one mark can be set at once:\n\n1. `delayed_settlement_fiat_paid_to_customer_at` set → `completed`\n2. else `delayed_settlement_crypto_refunded_to_customer_at` set → `cancelled`\n3. else `delayed_settlement_fiat_returned_by_bank_at` set **and**\n   `delayed_settlement_fiat_payout_authorized_by_admin_at` `null` → `returned`\n4. else, on a release status → `settlement_in_progress`\n5. before the release, the ordinary mapping applies — a funded delayed order awaiting release is\n   `crypto_received` like any other, and `next_action` is what tells them apart\n\nA return with a fresh authorization on top reads as `settlement_in_progress` (step 4).\n\n**On-ramp statuses (fiat → crypto):**\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_vendor_escrow_funding` — vendor accepted, funding escrow with crypto\n- `awaiting_fiat_transfer` — crypto locked in escrow; the partner pays the vendor and confirms payment sent (`fiat_funding_source: vendor_details`), or the customer transfers into their own fiat account (`own_account`)\n- `fiat_transfer_pending` — fiat payment confirmed, awaiting vendor confirmation of receipt\n- `completed` — vendor confirmed fiat received, crypto released to end-user wallet\n- `cancelled` — order cancelled\n- `failed` — escrow error\n\n**On-ramp send-out statuses (optional post-trade cross-chain transfer):**\n\n> After an on-ramp order reaches `completed`, the partner may optionally initiate a\n> **send-out** — a cross-chain transfer of the received crypto to a destination network\n> (e.g. XAI → Arbitrum). This is an additional flow and does not affect the core trade lifecycle.\n> The `completed` status reflects that the trade itself is done; send-out statuses track\n> the subsequent cross-chain transfer only.\n\n- `send_out_pending` — send-out initiated, cross-chain transfer in progress\n- `send_out_completed` — cross-chain transfer successfully delivered to destination\n- `send_out_failed` — cross-chain transfer failed; the on-ramp trade itself remains completed\n","enum":["created","awaiting_liquidity_provider","awaiting_crypto_transfer_authorization","crypto_transfer_authorization_pending","crypto_received","fiat_payment_started","fiat_payment_review_started","dispute_started","awaiting_fiat_received_confirmation","fiat_received_confirmed","crypto_release_pending","awaiting_vendor_escrow_funding","awaiting_fiat_transfer","fiat_transfer_pending","completed","cancelled","failed","price_changed_requote_needed","settlement_in_progress","returned","send_out_pending","send_out_completed","send_out_failed"]},"PartnerOrderAmounts":{"type":"object","properties":{"crypto_amount":{"type":"string","description":"Total crypto amount (standard units) — the fee-exclusive gross: the buy/sell amount plus the\nplatform fee. Partner-fee-exclusive, except for a crypto-anchored onramp order (originally\nquoted with `crypto_amount`): there the amount was sized up so the delivered amount stays\nexact after the partner fee is withheld, so this field includes the markup. A crypto-anchored\nofframp order carves both fees out of the pinned deposit instead, so this field and\n`fee_breakdown.platform_fee` both shrink relative to a no-markup request, even though the\nmarkup itself stays out of this field. Every other case is unaffected — the markup is\nreported separately in `fee_breakdown.partner_fee`.\n\nOn-ramp — what the end user receives: `crypto_amount − fee_breakdown.platform_fee −\nfee_breakdown.partner_fee` for a fiat-anchored order, or exactly this `crypto_amount` for a\ncrypto-anchored order (both fees are withheld at bridge send-out without changing this\nfield). Off-ramp — what the partner funds at transfer authorization:\n`crypto_amount + fee_breakdown.partner_fee`.\n"},"fiat_amount":{"type":"string","description":"Fiat amount the user receives"},"crypto_currency":{"type":"string","description":"Cryptocurrency code"},"fiat_currency":{"type":"string","description":"Fiat currency code"},"rate":{"type":"string","description":"Crypto-to-fiat exchange rate"}}},"FeeBreakdown":{"type":"object","description":"Transparent breakdown of all fee components (amounts in crypto)","properties":{"platform_fee":{"type":"string","description":"Platform fee in crypto"},"platform_fee_pct":{"type":"number","format":"double","description":"Platform fee as a percentage"},"partner_fee":{"type":"string","description":"Your markup in crypto, computed from the `partner_fee_pct` you declared on the\nquote/estimate request, on the same base as the platform fee. `0` when no markup was declared.\n"},"partner_fee_pct":{"type":"number","format":"double","description":"Your markup percentage as declared on the request (`1` means 1%); `0` when none."},"total_fee":{"type":"string","description":"Total fee in crypto (platform_fee + partner_fee)"},"fiat_rail_fee":{"type":"string","description":"What the payout rail itself charges, in the order's **fiat** currency — every field above\nis in crypto. It is the gap between `rate × crypto_amount` and the money that actually\nmoves on the bank or wallet rail, and it is already reflected in `fiat_amount`.\n\nDeliberately **not** summed into `total_fee`: that is a crypto figure, and adding a fiat\namount to it would produce a number that means nothing. Reconciling a payout, add this to\n`fiat_amount` to get the gross the rate implies.\n\nAlways present; `\"0.00\"` on a rail that charges nothing.\n"},"fiat_rail_fee_currency":{"type":"string","description":"The currency `fiat_rail_fee` is denominated in, so a breakdown read on its own is never ambiguous about which of the order's two currencies a fee is in. Omitted when there is no rail fee to denominate."},"payout_base_rate":{"type":"string","description":"Optional on payout estimates and quotes. The conversion rate before the licensed partner's costs and margin, in fiat per crypto, when that licensed partner publishes it, for instant and T+1 offers. It lets you show the recipient amount and one combined fee without charging the fee twice: divide `fiat_amount` by this rate and round half up to the crypto's precision; the rest of `crypto_amount` is the combined fee. A separate partner markup stays separate. Omitted when the rate is not known or is out of date; its absence does not mean there is no margin. This is not the all-in rate; that is `rate`."}}},"TimelineEntry":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/PartnerOrderStatus"},"timestamp":{"type":"string","format":"date-time","description":"When this status was reached"},"description":{"type":"string","description":"Human-readable description of the status change.\n\nOn a **delayed settlement (T+1)** order the release entry reads\n`Crypto released to the liquidity provider, ahead of the payout` under\n`settlement_in_progress`, not `Order completed`: the crypto leaving escrow is the middle of\nthat order's story, not its end. Seven more entries follow it —\n`Crypto transferred to the payout provider`, `Fiat payout authorized`,\n`Fiat payout submitted by the provider` and\n`Fiat payout cancelled by the provider before it was sent` (all `settlement_in_progress`),\n`Fiat paid to the customer` (`completed`), `Fiat returned by the bank` (`returned`) and\n`Crypto refunded to the customer` (`cancelled`). An ordinary order's timeline is unchanged,\nentry for entry.\n\nConsecutive entries are collapsed by status; on a delayed order they are collapsed by status\n**and** description, so the intermediate facts that all carry `settlement_in_progress` each\nkeep their own line.\n\nOnce a payment has come back, or the payout provider cancelled it before sending it, and a\nnew attempt followed, every attempt stays on the timeline and the approval, sending, paid,\nreturn and cancellation entries end in `(attempt N)`, for example\n`Fiat payout authorized (attempt 2)` or `Fiat paid to the customer (attempt 2)`. With a\nsingle attempt there is no suffix. `Crypto transferred to the payout provider` is read from\nthe order's timestamp and leaves the timeline when that timestamp is cleared.\n"}}},"PartnerRecipientContext":{"type":"object","required":["sender_id","recipient_id","recipient_destination_id","sender_recipient_relationship","purpose_of_payment","screening_status"],"properties":{"sender_id":{"type":"string","format":"uuid"},"recipient_id":{"type":"string","format":"uuid"},"recipient_destination_id":{"type":"string","format":"uuid"},"sender_recipient_relationship":{"type":"string"},"purpose_of_payment":{"type":"string"},"purpose_details":{"type":"string"},"screening_status":{"type":"string"}}},"PartnerComplianceCase":{"type":"object","required":["case_id","status","risk_decision","requires_review"],"description":"The compliance record for a third-party payout. In v1 the controls run BEFORE the order is\ncreated, so a payout that fails one is rejected with an error rather than returned as a held\norder — see the error codes in the Third-party payouts guide.\n","properties":{"case_id":{"type":"string","format":"uuid","description":"Identifier of the compliance record — the payout's `quote_id`, so a partner and a Unigox\noperator refer to the same record.\n"},"status":{"type":"string","enum":["authorized"],"description":"v1 emits `authorized`; a rejected payout returns an error instead."},"risk_decision":{"type":"string","enum":["allow"],"description":"v1 emits `allow`; a blocking decision surfaces as an error, not a status."},"requires_review":{"type":"boolean","description":"Always false in v1. Operator review happens Unigox-side over the same record."}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/orders/{order_id}":{"get":{"tags":["Orders"],"summary":"Order details","description":"Get the current status, amounts, and full timeline for a specific order.\nThe `next_action` field indicates what the partner **must** do to advance the order.\n`null` means no action is required from the partner at this stage — the order is waiting\nfor the counterparty (e.g. the buyer to submit fiat payment proof).\n\nThe `allowed_actions` array lists all API actions the partner **can** perform at the current\nstatus. An action can be in `allowed_actions` even when `next_action` is absent — this means\nthe action is optional. For example, on an ordinary off-ramp order `confirm-fiat-received` is\navailable at `crypto_received` as a fast-track: if you already know the fiat has arrived (via\nyour own systems), you can confirm immediately without waiting for the buyer's payment proof\nflow to complete.\n\n**That fast-track does not exist on a delayed settlement (T+1) order.** There the crypto\nleaves escrow before the customer is paid, so at `crypto_received` `confirm-fiat-received` is\n**removed** from `allowed_actions` and the endpoint refuses the order; `[\"settlement-consent\",\n\"cancel\"]` take its place and `next_action` is `sign_settlement_consent`, then\n`submit_source_of_funds` or `await_review` — the latter meaning the order is waiting on us, for\nany required source-of-funds approval, for the licensed partner's payment check and for crypto\nrelease. Branch on `delayed_settlement` — the two orders share a status and differ in everything\nyou may do with it. See the Delayed settlement (T+1) reference.\n\n`allowed_actions` is `[]` for a **widget order** — one your customer created through the\nembedded widget under your `widgetKey`. Those orders are attributed to you, and readable\nhere, but the crypto is the end user's, so every action endpoint answers `404\nORDER_NOT_FOUND` for them. `status`, `next_action` and the timeline still describe the\norder; they describe your customer's step, not one for you to take.\n\n**A `cancelled` order can still owe you money.** An off-ramp order that stopped after its\nescrow was funded reads `cancelled` — the same as one that never funded and the same as one\nwhose refund has already been paid out. The status does not distinguish them and never will.\nWhat distinguishes them is `allowed_actions`: `[\"authorize-refund\"]` means the crypto is\nstill in the escrow and your signature is the only thing that can send it back, with\n`next_action: \"authorize_refund\"` and `action_required` naming the endpoint. Check it before\nwriting an order off. The `order.refund.required` webhook says the same thing once, if you\nwould rather not poll.\n\n**Order flow summary:**\n\n| Status | next_action | Who acts |\n|---|---|---|\n| `created` | — | Partner (or wait for vendor match) |\n| `awaiting_crypto_transfer_authorization` | `authorize_crypto_transfer` | **Partner** |\n| `crypto_transfer_authorization_pending` | — | System (on-chain confirmation) |\n| `crypto_received` | — | **Buyer** submits fiat payment proof |\n| `fiat_payment_started` | — | System reviews proof |\n| `fiat_payment_review_started` | — | System accepts/rejects proof |\n| `awaiting_fiat_received_confirmation` | `confirm_fiat_received` | **Partner** |\n| `completed` | — | — |\n\nA **delayed settlement (T+1)** order replaces the `crypto_received` row — no buyer submits\nproof, because the fiat is paid after the release, not before:\n\n| Status | next_action | Who acts |\n|---|---|---|\n| `crypto_received` | `sign_settlement_consent` | **Partner** signs the release |\n| `crypto_received` | `submit_source_of_funds` | **Partner** supplies the source-of-funds case |\n| `crypto_received` | `await_review` | **Unigox**: document review, the licensed partner's payment check, or release processing |\n| `crypto_received` | — | Held: Unigox holds the order for a check, or a payout failed and a refund is under way |\n| `settlement_in_progress` | — | Payout in flight; the fiat has not arrived |\n| `returned` | — | The bank sent the payout back; Unigox pays again or refunds the crypto |\n\nThe \"Who acts\" column describes an order **you** created. On a widget order the rows\nreading **Partner** are your customer's step, not yours — `next_action` is populated the\nsame way for both, because it describes where the order stands rather than who may move\nit. `allowed_actions` is what tells you apart: `[]` on a widget order at every status.\nActing on a `next_action` for a widget order returns `404 ORDER_NOT_FOUND`. A delayed order\nis never a widget order: the wallet must be yours for anyone on this API to sign the release.\n\n**Fiat settlement and confirmation** (ordinary orders; a delayed order never takes a fiat\nconfirmation)**:**\n\nYou can call `confirm-fiat-received` at any time after crypto is in escrow.\nYou do not need to wait for a system notification. If you know through your\nown systems that the recipient has received the fiat payment, confirm immediately.\n\nSome liquidity providers also send automatic settlement confirmations when the\nrecipient receives the fiat. When the order's `has_fiat_settlement_notification`\nis `true` (see the quote/order response), the order moves to `completed` on its own\nand you receive the `status=completed` webhook — no manual confirm needed. If you\nalready confirmed manually, the auto-confirmation is a no-op; if the auto-confirmation\narrives first, your manual confirm call is also a no-op. Both paths are safe. See the\nWebhooks page → \"Settlement notifications\" for details.\n\n**How to implement:**\n- Always implement a `confirm-fiat-received` call in your flow.\n- Listen for webhooks. If you receive `status=completed`, no further action needed.\n- If `next_action=confirm_fiat_received`, call `confirm-fiat-received` when you\n  know fiat has been received.\n- Do not wait for `next_action` if you already have confirmation from your\n  own banking or payment systems.\n- On a delayed order do not call `confirm-fiat-received`, and treat `completed` as\n  meaning the fiat actually reached the customer.\n\n**Possible statuses:** see `PartnerOrderStatus`. Off-ramp: `created`, `awaiting_liquidity_provider`, `awaiting_crypto_transfer_authorization`, `crypto_transfer_authorization_pending`, `crypto_received`, `fiat_payment_started`, `fiat_payment_review_started`, `dispute_started`, `awaiting_fiat_received_confirmation`, `completed`, `cancelled`, `failed`, `price_changed_requote_needed`, plus `settlement_in_progress` and `returned` on a delayed order. On-ramp: `awaiting_vendor_escrow_funding`, `awaiting_fiat_transfer`, `fiat_transfer_pending`, `send_out_pending`, `send_out_completed`, `send_out_failed`.\n","operationId":"getOrder","parameters":[{"name":"order_id","in":"path","required":true,"description":"Order UUID returned by the initiate endpoint","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Order retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PartnerOrderResponse"}}}]}}}},"401":{"description":"Unauthorized — invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"404":{"description":"Order not found or does not belong to this partner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## Get transfer authorization parameters

> Returns pre-filled parameters required to build and sign the EIP-712 forward request.\
> Use this endpoint first, then sign locally and send the signature to\
> \`/api/v1/partner/orders/{order\_id}/authorize-crypto-transfer\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management, status tracking, and lifecycle actions"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/orders/{order_id}/transfer-authorization-parameters":{"get":{"tags":["SDK","Orders"],"summary":"Get transfer authorization parameters","description":"Returns pre-filled parameters required to build and sign the EIP-712 forward request.\nUse this endpoint first, then sign locally and send the signature to\n`/api/v1/partner/orders/{order_id}/authorize-crypto-transfer`.\n","operationId":"getTransferAuthorizationParameters","parameters":[{"name":"order_id","in":"path","required":true,"description":"Order UUID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Transfer authorization parameters returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"network_preset":{"type":"string"},"chain_id":{"type":"string"},"rpc_url":{"type":"string","description":"JSON-RPC URL for the target chain"},"token_address":{"type":"string"},"forwarder_address":{"type":"string"},"recipient_address":{"type":"string","description":"Escrow address to receive the crypto"},"sender_address":{"type":"string","description":"Address that must sign the request: your partner wallet for a `partner_wallet`\ncustomer, the customer's linked address for an `external_wallet` customer.\n"},"amount_atomic":{"type":"string"},"amount_human":{"type":"string"},"crypto_currency":{"type":"string"},"crypto_decimals":{"type":"integer"},"recommended_gas_limit":{"type":"string"},"recommended_ttl_seconds":{"type":"integer"},"transfer_data":{"type":"string","description":"Pre-encoded ERC20 transfer(address,uint256) calldata (hex with 0x prefix)"},"forwarder_nonce":{"type":"string","description":"Current forwarder nonce for the sender address (used in EIP-712 signing)"},"authorization_path":{"type":"string"}}}}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"No order with this id belongs to your partner account."},"409":{"description":"The order exists but is not at a stage where it can be funded. A new order starts at `awaiting_liquidity_provider` with no escrow yet, so this is the normal answer until a provider accepts — poll `GET /orders/{order_id}` until `next_action` becomes `authorize_crypto_transfer`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## Authorize crypto transfer

> Submit signed EIP-712 \`forward\_request\` to authorize transfer of order crypto to escrow.\
> \
> \*\*Security note:\*\* Your private key is never sent to the API. The SDK uses it locally to\
> construct and sign the EIP-712 ForwardRequest on your machine. Only the resulting signature\
> and the unsigned forward\_request fields are submitted. You can verify this by reading the\
> SDK source code.\
> \
> Recommended: use SDK helper files (only 4 arguments needed):\
> \- Python: \`<https://github.com/Unigox/sdk\\_python/blob/main/partner\\_authorize\\_crypto\\_transfer\\_sdk.py\\`\\>
> \- JavaScript: \`<https://github.com/Unigox/sdk\\_javascript/blob/main/partner\\_authorize\\_crypto\\_transfer\\_sdk.js\\`\\>
> \
> The SDK automatically fetches all required parameters (chain, token, forwarder, escrow\
> address, RPC URL) from the \`transfer-authorization-parameters\` endpoint.\
> \
> SDK helper options:\
> \- End-to-end one call: \`authorize\_crypto\_transfer(...)\` / \`authorizeCryptoTransfer(...)\`\
> \- Build unsigned request only: \`build\_forward\_request(...)\` / \`buildForwardRequest(...)\`\
> \- Sign existing request only: \`sign\_forward\_request(...)\` / \`signForwardRequest(...)\`\
> \- Build full request body \`{forward\_request, signature}\`:\
> &#x20; \`build\_authorize\_crypto\_transfer\_payload(...)\` / \`buildAuthorizeCryptoTransferPayload(...)\`\
> \
> Manual implementation: call \`GET /transfer-authorization-parameters\` first, then build\
> the EIP-712 typed data and sign with your partner wallet private key locally.\
> \
> \*\*Non-custodial customers\*\* (\`wallet\_type: external\_wallet\`): the request must be signed by the\
> customer's linked address (\`sender\_address\`), in your app, where the customer's key is. A request\
> whose \`from\` is not that address, or that does not move exactly this order's amount to this\
> order's escrow, is refused with \`400 INVALID\_REQUEST\` naming the field. A short balance answers\
> \`422 INSUFFICIENT\_BALANCE\` and nothing is relayed.\
> \
> \*\*Signature check.\*\* Unigox recovers the signer before relaying. A signature not made by \`from\`,\
> a \`deadline\` in the past, or a \`nonce\` that is not the signer's current forwarder nonce is refused\
> with \`400 INVALID\_REQUEST\`, and nothing is relayed. Fetch new parameters and sign again. If an\
> earlier request for this order failed without moving funds, a new signed request is accepted.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management, status tracking, and lifecycle actions"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/orders/{order_id}/authorize-crypto-transfer":{"post":{"tags":["SDK","Orders"],"summary":"Authorize crypto transfer","description":"Submit signed EIP-712 `forward_request` to authorize transfer of order crypto to escrow.\n\n**Security note:** Your private key is never sent to the API. The SDK uses it locally to\nconstruct and sign the EIP-712 ForwardRequest on your machine. Only the resulting signature\nand the unsigned forward_request fields are submitted. You can verify this by reading the\nSDK source code.\n\nRecommended: use SDK helper files (only 4 arguments needed):\n- Python: `https://github.com/Unigox/sdk_python/blob/main/partner_authorize_crypto_transfer_sdk.py`\n- JavaScript: `https://github.com/Unigox/sdk_javascript/blob/main/partner_authorize_crypto_transfer_sdk.js`\n\nThe SDK automatically fetches all required parameters (chain, token, forwarder, escrow\naddress, RPC URL) from the `transfer-authorization-parameters` endpoint.\n\nSDK helper options:\n- End-to-end one call: `authorize_crypto_transfer(...)` / `authorizeCryptoTransfer(...)`\n- Build unsigned request only: `build_forward_request(...)` / `buildForwardRequest(...)`\n- Sign existing request only: `sign_forward_request(...)` / `signForwardRequest(...)`\n- Build full request body `{forward_request, signature}`:\n  `build_authorize_crypto_transfer_payload(...)` / `buildAuthorizeCryptoTransferPayload(...)`\n\nManual implementation: call `GET /transfer-authorization-parameters` first, then build\nthe EIP-712 typed data and sign with your partner wallet private key locally.\n\n**Non-custodial customers** (`wallet_type: external_wallet`): the request must be signed by the\ncustomer's linked address (`sender_address`), in your app, where the customer's key is. A request\nwhose `from` is not that address, or that does not move exactly this order's amount to this\norder's escrow, is refused with `400 INVALID_REQUEST` naming the field. A short balance answers\n`422 INSUFFICIENT_BALANCE` and nothing is relayed.\n\n**Signature check.** Unigox recovers the signer before relaying. A signature not made by `from`,\na `deadline` in the past, or a `nonce` that is not the signer's current forwarder nonce is refused\nwith `400 INVALID_REQUEST`, and nothing is relayed. Fetch new parameters and sign again. If an\nearlier request for this order failed without moving funds, a new signed request is accepted.\n","operationId":"authorizeCryptoTransfer","parameters":[{"name":"order_id","in":"path","required":true,"description":"Order UUID","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["forward_request","signature"],"properties":{"forward_request":{"type":"object","description":"Signed EIP-712 ForwardRequest payload"},"signature":{"type":"string","description":"65-byte EIP-712 signature of `forward_request` by `forward_request.from`, hex-encoded. `0x` prefix recommended; a signature without it is accepted."}}}}}},"responses":{"200":{"description":"Crypto authorization accepted"},"400":{"description":"`INVALID_REQUEST` — the request does not match the order (`from`, token, amount, escrow), the\nsignature does not recover to `from`, the `deadline` has passed, or the `nonce` is not the\ncurrent forwarder nonce. Nothing is relayed; fetch new parameters and sign again.\n"},"401":{"description":"Unauthorized"},"404":{"description":"Order not found"},"409":{"description":"Order is not in the correct status for crypto authorization"},"422":{"description":"Insufficient token balance — the funding address (your partner wallet, or the\n`external_wallet` customer's linked address) does not hold enough tokens to fund the\nescrow. Nothing is relayed.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"502":{"description":"`TRANSACTOR_ERROR` — the transaction could not be submitted, although the request passed every check. Retry."}}}}}}
```

## Get refund authorization parameters

> Returns the EIP-712 Safe transaction to sign in order to send a funded escrow back to the\
> seller. This is the way out of an off-ramp order that stopped before settlement — the payment\
> window expired, a payment proof was declined, the bank returned the payment, or a dispute was\
> resolved for the seller. In every one of those the crypto is still sitting in escrow and owes\
> its way back.\
> \
> Use this endpoint first, sign the returned typed data locally with the key that owns\
> \`signer\_address\`, then send the signature to\
> \`/api/v1/partner/orders/{order\_id}/authorize-refund\`.\
> \
> \*\*Who signs.\*\* The escrow is a 2-of-3 Safe whose owners are the buyer side, the seller side\
> and Unigox. For a \`partner\_wallet\` customer the seller-side owner is \*your\* wallet — the\
> customer never holds a key. For an \`external\_wallet\` customer it is the customer's linked\
> address, and the customer signs; the refund then lands on the customer's own address.\
> \`signer\_address\` names the key either way; sign with that key and no other, or the Safe\
> rejects the transaction.\
> \
> \*\*Where the money goes is not yours to choose.\*\* The recipient is read from the escrow's\
> seller address on the server. \`recipient\_address\` is returned so you can verify it before\
> signing; there is no parameter that changes it.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management, status tracking, and lifecycle actions"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/orders/{order_id}/refund-authorization-parameters":{"get":{"tags":["SDK","Orders"],"summary":"Get refund authorization parameters","description":"Returns the EIP-712 Safe transaction to sign in order to send a funded escrow back to the\nseller. This is the way out of an off-ramp order that stopped before settlement — the payment\nwindow expired, a payment proof was declined, the bank returned the payment, or a dispute was\nresolved for the seller. In every one of those the crypto is still sitting in escrow and owes\nits way back.\n\nUse this endpoint first, sign the returned typed data locally with the key that owns\n`signer_address`, then send the signature to\n`/api/v1/partner/orders/{order_id}/authorize-refund`.\n\n**Who signs.** The escrow is a 2-of-3 Safe whose owners are the buyer side, the seller side\nand Unigox. For a `partner_wallet` customer the seller-side owner is *your* wallet — the\ncustomer never holds a key. For an `external_wallet` customer it is the customer's linked\naddress, and the customer signs; the refund then lands on the customer's own address.\n`signer_address` names the key either way; sign with that key and no other, or the Safe\nrejects the transaction.\n\n**Where the money goes is not yours to choose.** The recipient is read from the escrow's\nseller address on the server. `recipient_address` is returned so you can verify it before\nsigning; there is no parameter that changes it.\n","operationId":"getRefundAuthorizationParameters","parameters":[{"name":"order_id","in":"path","required":true,"description":"Order UUID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Refund authorization parameters returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"status":{"type":"string","description":"The order's current status"},"escrow_address":{"type":"string","description":"The Safe holding the crypto"},"signer_address":{"type":"string","description":"The escrow's seller-side owner — the address whose key must produce the signature. On an order opened for your end customer this is your wallet."},"recipient_address":{"type":"string","description":"Where the refund lands. Server-derived and identical to `signer_address` on a partner order; returned for verification, not as an input."},"amount_human":{"type":"string","description":"Amount to be refunded, in whole units"},"crypto_currency":{"type":"string"},"crypto_decimals":{"type":"integer"},"direction":{"type":"string","description":"Always `to_seller`. Refunds have no other direction."},"safe_params":{"type":"object","description":"The Safe transaction fields to sign","properties":{"to":{"type":"string","description":"Token contract address"},"value":{"type":"string"},"data":{"type":"string","description":"Encoded ERC20 transfer calldata"},"operation":{"type":"integer"},"safeTxGas":{"type":"string"},"baseGas":{"type":"string"},"gasPrice":{"type":"string"},"gasToken":{"type":"string"},"refundReceiver":{"type":"string"},"nonce":{"type":"string","description":"Safe nonce"}}},"domain":{"type":"object","description":"EIP-712 domain","properties":{"chainId":{"type":"integer"},"verifyingContract":{"type":"string"}}},"types":{"type":"object","description":"EIP-712 type definitions (`SafeTx`)"},"authorization_path":{"type":"string","description":"The endpoint to POST the signature to"}}}}}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"No order with this id belongs to your partner account."},"409":{"description":"The order does not owe a refund. Either it has already been refunded or released, its status is one where the crypto is not owed back (`INVALID_STATUS`), or it is held for review and no automatic refund may run against it (`OPERATION_NOT_ALLOWED`) — the message says which. A held order is settled by our operations team, not by retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## Authorize refund

> Submit the signature produced from \`GET /refund-authorization-parameters\` to send the escrow\
> back to the seller. Unigox adds the second of the two signatures the Safe requires and\
> executes the transaction.\
> \
> \*\*Security note:\*\* your private key is never sent to the API. Sign the typed data locally and\
> submit only the resulting signature.\
> \
> The recipient is fixed server-side to the escrow's seller address. A signature is an\
> authorization to move the money back, never an instruction about where it goes.\
> \
> Safe to retry: the on-chain Safe executes a given transaction at most once, so a duplicate\
> call after a successful refund is refused on status rather than paying twice.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management, status tracking, and lifecycle actions"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/orders/{order_id}/authorize-refund":{"post":{"tags":["SDK","Orders"],"summary":"Authorize refund","description":"Submit the signature produced from `GET /refund-authorization-parameters` to send the escrow\nback to the seller. Unigox adds the second of the two signatures the Safe requires and\nexecutes the transaction.\n\n**Security note:** your private key is never sent to the API. Sign the typed data locally and\nsubmit only the resulting signature.\n\nThe recipient is fixed server-side to the escrow's seller address. A signature is an\nauthorization to move the money back, never an instruction about where it goes.\n\nSafe to retry: the on-chain Safe executes a given transaction at most once, so a duplicate\ncall after a successful refund is refused on status rather than paying twice.\n","operationId":"authorizeRefund","parameters":[{"name":"order_id","in":"path","required":true,"description":"Order UUID","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["signature"],"properties":{"signature":{"type":"string","description":"Hex-encoded signature over the returned `safe_params`"},"signed_data":{"type":"string","description":"The exact payload that was signed. Optional — the server rebuilds it from the order and uses its own copy for verification."}}}}}},"responses":{"200":{"description":"Refund accepted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"status":{"type":"string","description":"The status the order landed in after the refund"},"tx_hash":{"type":"string","description":"On-chain transaction hash. Absent when the refund still needs another signature or is executing — poll `GET /orders/{order_id}`."}}}}}]}}}},"400":{"description":"Missing or malformed signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"401":{"description":"Unauthorized"},"404":{"description":"No order with this id belongs to your partner account."},"409":{"description":"The order does not owe a refund — already refunded, already released, or in a status where the crypto is not owed back (`INVALID_STATUS`); or it is held for review and no automatic refund may run against it (`OPERATION_NOT_ALLOWED`), in which case retrying will not clear it and our operations team settles the order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"502":{"description":"The refund could not be executed on-chain — most often a signature from a key that does not own the escrow. Verify you signed with `signer_address` and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## Confirm fiat received

> Confirm that the recipient has received the fiat payment for an off-ramp order.\
> This triggers the crypto release from escrow.\
> \
> Call this endpoint as soon as you know fiat has been received. You do not need\
> to wait for a system prompt. If you have confirmation from your own banking or\
> payment systems, confirm immediately.\
> \
> Call it while the order offers \`confirm-fiat-received\` in \`allowed\_actions\`. Once the\
> order has moved past that point (it was already confirmed, or it completed through the\
> liquidity provider's own settlement confirmation), the call answers\
> \`409 INVALID\_STATUS\` and changes nothing: read the order instead.\
> \
> Not for delayed settlement (T+1) orders. On such an order, whatever its status, this\
> answers \`409 INVALID\_STATUS\` ("this order settles T+1: the payout is confirmed by the\
> provider, not with confirm-fiat-received").<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management, status tracking, and lifecycle actions"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/orders/{order_id}/confirm-fiat-received":{"post":{"tags":["Orders"],"summary":"Confirm fiat received","description":"Confirm that the recipient has received the fiat payment for an off-ramp order.\nThis triggers the crypto release from escrow.\n\nCall this endpoint as soon as you know fiat has been received. You do not need\nto wait for a system prompt. If you have confirmation from your own banking or\npayment systems, confirm immediately.\n\nCall it while the order offers `confirm-fiat-received` in `allowed_actions`. Once the\norder has moved past that point (it was already confirmed, or it completed through the\nliquidity provider's own settlement confirmation), the call answers\n`409 INVALID_STATUS` and changes nothing: read the order instead.\n\nNot for delayed settlement (T+1) orders. On such an order, whatever its status, this\nanswers `409 INVALID_STATUS` (\"this order settles T+1: the payout is confirmed by the\nprovider, not with confirm-fiat-received\").\n","operationId":"confirmFiatReceived","parameters":[{"name":"order_id","in":"path","required":true,"description":"Order UUID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Fiat receipt confirmed successfully"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Order not found"},"409":{"description":"`INVALID_STATUS` — nothing was changed. The order's status does not allow the confirmation (it is not funded yet, or it has already moved past it); the order is under review; or it is a delayed settlement (T+1) order, which refuses this call at every status. Read the order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## Cancel order

> Cancel an order if cancellation is allowed at the current status.\
> Check \`allowed\_actions\` on the order response — \`cancel\` is available when cancellation is permitted.\
> \
> Once \`authorize-crypto-transfer\` has submitted the escrow funding, an off-ramp cannot be\
> cancelled while that transfer may still execute: the call answers \`409 OPERATION\_NOT\_ALLOWED\`.\
> It can be cancelled again only if the submitted transfer failed without reaching the chain.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management, status tracking, and lifecycle actions"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PartnerOrderResponse":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid","description":"Unique order identifier"},"status":{"$ref":"#/components/schemas/PartnerOrderStatus"},"next_action":{"type":"string","description":"The action the partner **must** perform to advance the order. The key is **absent**\nwhen no action is required at this stage — the order is waiting for the\ncounterparty or for an automated system step — and is never sent as `null`.\n\nPossible values:\n- `authorize_crypto_transfer` — partner must authorize escrow funding\n- `confirm_fiat_received` — partner must confirm they received the fiat payment\n- `request_new_quote` — price changed, partner must request a new quote\n- `update_kyc_address` — address fields are required for EUR/AUD/GBP payouts; see `action_required` for the endpoint and fields to submit\n- `authorize_refund` — the order ended without a payout and its crypto is still in escrow; only your\n  signature can send it back. Note that this appears on an order whose `status` is `cancelled`, which\n  is the one case where a terminal status still needs something from you\n- `deposit_to_user_account` — an on-ramp order with `fiat_funding_source: own_account` is waiting for the\n  customer to transfer the order's fiat amount into the fiat account issued to them. The transfer\n  itself confirms the payment; there is nothing to call. If the money is already on the account,\n  `pay-from-balance` is in `allowed_actions` and pays the order from it\n- `sign_settlement_consent` — a **delayed settlement (T+1)** order remains at `crypto_received`\n  and nobody has signed the release yet\n- `submit_source_of_funds` — consent is stored and a required source-of-funds case is\n  incomplete, including an existing case below the current threshold\n- `await_review` — consent is stored and the order is waiting for Unigox document review,\n  the licensed partner's payment check, or release processing. Do not submit another signature\n- absent — no required action (waiting for buyer or system). On a funded delayed order awaiting release\n  the key is absent when the order is held for review, or a payout of yours failed and a\n  refund is under way\n\nOnce consent_deadline_at has passed, these reads no longer request a consent signature,\neven if the order status has not changed yet.\nThe list (`GET /api/v1/partner/orders`) reads the consent from the order record and can show\n`await_review`, for up to two minutes, for a consent call that was cut off before your signature\nwas stored. After a\ntimeout, read the single order (`GET /api/v1/partner/orders/{order_id}`) before you decide\nwhether to send the signature again. If a lookup behind the T+1 hint fails, both reads fall\nback to `sign_settlement_consent`.\n","enum":["authorize_crypto_transfer","confirm_fiat_received","request_new_quote","update_kyc_address","authorize_refund","deposit_to_user_account","sign_settlement_consent","submit_source_of_funds","await_review"]},"action_required":{"type":"object","nullable":true,"description":"Present when the order needs partner intervention before it can proceed.\nContains machine-readable type, human-readable message, the API endpoint to call,\nand the fields to provide. Null/omitted when no action is needed.\n","required":["type","message"],"properties":{"type":{"type":"string","description":"Machine-readable action identifier"},"message":{"type":"string","description":"Human-readable explanation of what is needed and why"},"endpoint":{"type":"string","description":"API endpoint to call to resolve this action"},"fields":{"type":"array","description":"Fields the partner needs to provide","items":{"type":"object","required":["field","label"],"properties":{"field":{"type":"string","description":"API field name"},"label":{"type":"string","description":"Human-readable description of the field"}}}}}},"allowed_actions":{"type":"array","items":{"type":"string"},"description":"List of API actions the partner **can** perform at the current status. An action\nmay be present here even when `next_action` is absent — meaning it is optional.\n\nNotable case: `confirm-fiat-received` appears at both `crypto_received` and\n`awaiting_fiat_received_confirmation`. At `crypto_received` it is a **fast-track**:\nif you already know the fiat has arrived via your own systems, you can confirm\nimmediately. Otherwise, wait for the buyer's proof flow to complete — the order\nwill reach `awaiting_fiat_received_confirmation` automatically.\n\nStatus-to-actions mapping:\n- `created` → `[\"cancel\"]`\n- `awaiting_liquidity_provider` → `[\"cancel\"]`\n- `awaiting_crypto_transfer_authorization` → `[\"authorize-crypto-transfer\", \"cancel\"]`\n- `crypto_transfer_authorization_pending` → `[]` (the transfer is in flight; cancel is refused)\n- `crypto_received` → `[\"confirm-fiat-received\"]` (optional fast-track)\n- `fiat_payment_started` → `[\"confirm-fiat-received\"]` (optional fast-track after buyer proof submission)\n- `awaiting_fiat_received_confirmation` → `[\"confirm-fiat-received\"]` (required)\n- `fiat_received_confirmed`, `crypto_release_pending`, `completed`, `failed` → `[]`\n- `cancelled` → `[]`, **except** when the order's crypto is still sitting in escrow: then\n  `[\"authorize-refund\"]`. An off-ramp order that stops after funding — expired payment window,\n  declined payment proof, returned bank payment, dispute resolved for the seller — reads as\n  `cancelled` like every other stopped order, and the escrow is a 2-of-3 Safe your key is an\n  owner of. This is the only thing that tells the two apart, so poll it on `cancelled` orders\n  rather than assuming a cancelled order is finished with. `next_action` is\n  `authorize_refund` and `action_required` names the endpoint at the same time.\n\nOn-ramp orders with `fiat_funding_source: own_account` never offer `confirm-payment-sent`: the\ntransfer into the customer's own account is the confirmation. At `awaiting_fiat_transfer` they\noffer `[\"pay-from-balance\"]` instead, until the order's fiat has been collected. A `completed`\norder paid from the balance whose crypto hand-over has not finished also offers\n`[\"pay-from-balance\"]`: calling it again retries the hand-over and never takes the money twice.\n\nOn a funded **delayed settlement (T+1)** order awaiting release whose crypto you hold,\n`confirm-fiat-received` is removed — the endpoint behind it refuses a delayed order — and\n`[\"settlement-consent\", \"cancel\"]` take its place.\n\n`cancel` is available only while the order awaits release; the endpoint is the ordinary\n`POST /api/v1/partner/orders/{order_id}/cancel`.\n\nBoth are withdrawn once the consent is signed, and then answer\n`409 OPERATION_NOT_ALLOWED`. The list reads the consent from the order record, so a list row\ncan already show them withdrawn, for up to two minutes, for a consent call that was cut off\nbefore your signature was\nstored. After a timeout, read the single order (`GET /api/v1/partner/orders/{order_id}`)\nbefore you decide whether to send the signature again.\n\nOn a funded delayed order awaiting release that is **held** — Unigox holds it for a check, or a\npayout failed and a refund is under way — `next_action` is omitted and no consent is accepted.\n`confirm-fiat-received` is absent there too, because that endpoint refuses every delayed\norder. An `authorize-refund` that is genuinely owed still appears.\nCustody outranks the mapping above: on a **widget order** — one your customer created\nthrough the embedded widget under your `widgetKey` — this is `[]` at every status,\nbecause the crypto is the end user's and every action endpoint answers `404\nORDER_NOT_FOUND` for it.\n"},"fiat_funding_source":{"type":"string","enum":["vendor_details","own_account"],"description":"On-ramp orders only. Where the fiat for this order is paid:\n- `vendor_details` — to the vendor's bank account in `vendor_payment_details`; then call\n  `confirm-payment-sent`.\n- `own_account` — into the fiat account you issued to the customer, named by\n  `fiat_account_id`. There are no `vendor_payment_details` and no `confirm-payment-sent`:\n  the transfer landing on the customer's account is matched to the order by amount and the\n  order proceeds on its own.\n\nRead it on every order rather than assuming one or the other.\n"},"fiat_account_id":{"type":"string","format":"uuid","description":"On an `own_account` order: the fiat account the customer transfers into. The same id the\nFiat Accounts endpoints take, so the deposit that funds this order can be found on that\naccount's transactions carrying this order's id.\nOn an off-ramp with `payout_via_own_account: true`: the customer's fiat account the money\ngoes through, when it is one you can address by id; omitted otherwise.\n"},"payout_via_own_account":{"type":"boolean","description":"`true` on an off-ramp paid through the customer's own fiat account: the liquidity provider\npays the customer's account and Unigox then pays the money on to the bank you named, both in\nthe customer's name. EUR and GBP off-ramps to the customer's own `payment_details` are paid\nthis way wherever customer fiat accounts are active for your partner in that currency; when\nthey cannot be, the quote is refused (`FIAT_ACCOUNT_OPENING`, `FIAT_ACCOUNT_REQUIRED`,\n`FIAT_ACCOUNTS_NOT_ENABLED`) unless a liquidity provider that pays banks directly takes the\norder. Omitted on every other order, never `false`. If you do not call\n`confirm-fiat-received`, the order is confirmed once Unigox has matched the money on the\ncustomer's account. That payment into the account does not send\n`fiat_account.deposit.received`.\n"},"own_account_payout_status":{"type":"string","enum":["awaiting_credit","in_progress","sent_to_bank","under_review","held","left_on_account"],"description":"Off-ramp paid through the customer's own fiat account only (`payout_via_own_account: true`):\nwhere the onward payment, from that account to the bank you named, stands. `status` describes\nthe provider's payment into the customer's account, so an order can be `completed` while this\nstill says the money has not reached the bank.\n- `awaiting_credit` — nothing has landed on the customer's account for this order yet.\n- `in_progress` — the money landed; the onward payment is queued, being sent, or being retried.\n- `sent_to_bank` — the money was sent on to the bank you named.\n- `under_review` — the onward payment ended without a clear result; Unigox checks it.\n- `held` — the money is on the customer's account and is not moving on by itself; contact Unigox.\n- `left_on_account` — Unigox decided the money stays on the customer's account.\n\nOmitted on other orders, and when the state cannot be read at that moment.\n"},"crypto_transfer_authorization_seconds_left":{"type":"integer","format":"int64","nullable":true,"description":"Remaining seconds to authorize crypto transfer while order is in\n`awaiting_crypto_transfer_authorization` / `crypto_transfer_authorization_pending`.\n`null` for all other statuses.\n"},"amounts":{"$ref":"#/components/schemas/PartnerOrderAmounts"},"fee_breakdown":{"$ref":"#/components/schemas/FeeBreakdown"},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/TimelineEntry"},"description":"Chronological list of status changes"},"has_fiat_settlement_notification":{"type":"boolean","description":"Whether the matched liquidity provider sends fiat settlement notifications.\nWhen `true`, the order will complete automatically when fiat is delivered.\nWhen `false`, you must call `confirm-fiat-received`. You can call\n`confirm-fiat-received` at any time regardless of this value, except on a delayed\nsettlement (T+1) order, which refuses it. `false` on every order no liquidity provider\nhas accepted yet, T+1 included; a T+1 order reads `true` from its acceptance on.\n"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"order_type":{"type":"string","enum":["offramp","onramp"],"description":"Order type. Present on every order, including one no liquidity provider has accepted yet.\n- `offramp` — sell crypto for fiat\n- `onramp` — buy crypto with fiat\n"},"vendor_payment_details":{"type":"object","nullable":true,"description":"Vendor's payment details for the end-user to send fiat to.\nPresent only for on-ramp orders at `awaiting_fiat_transfer` status and beyond.\n","properties":{"payment_method_name":{"type":"string"},"payment_network_name":{"type":"string"},"details":{"type":"object","description":"Payment method-specific fields (e.g. account_number, phone)"}}},"payment_request":{"type":"boolean","nullable":true,"description":"`true` if the vendor uses payment request flow — the partner must call\n`submit-payer-details` before `confirm-payment-sent`.\n"},"send_out_tx_hash":{"type":"string","nullable":true,"description":"Destination-chain transaction hash after a send-out completes.\nPresent only for on-ramp orders with `send_out_completed` status.\n"},"payment_deadline_at":{"type":"string","format":"date-time","nullable":true,"description":"On-ramp only: the moment the order can be cancelled for want of the customer's fiat.\nTell the customer to pay before it. The order is cancelled shortly after it (`cancelled`,\n\"Payment window expired\"): on your next read of the order, and an `own_account` order\nwithin about 20 minutes even if nobody reads it. A transfer that arrives after this moment but before the cancellation may\nstill complete the order; that is possible, not guaranteed. One that arrives after the\ncancellation stays on the customer's account and can be used with `pay-from-balance` on a\nnew order. Extended along with the window.\nSet while the order is `awaiting_fiat_transfer`, `null` otherwise — and always `null`\non an off-ramp, and on an order held for manual handling (it does not expire). UTC.\n"},"recipient_context":{"allOf":[{"$ref":"#/components/schemas/PartnerRecipientContext"}],"nullable":true,"description":"Immutable third-party recipient context; absent for self-payout and on-ramp."},"compliance":{"allOf":[{"$ref":"#/components/schemas/PartnerComplianceCase"}],"nullable":true,"description":"Current durable compliance-case state for a third-party payout."},"delayed_settlement":{"type":"boolean","description":"Whether this order settles **T+1**: the crypto leaves escrow before the fiat is paid.\nYour release signature authorises it to leave and Unigox performs the release; the fiat\nis expected within `settlement_hours` of it (a target, not a deadline). Present on every\norder, on-ramp included, along\nwith the other T+1 fields below. T+1 timestamps and the window are null on instant\norders. The current numeric source-of-funds threshold is still returned.\n\nProvisional until a licensed partner accepts the order. While an order quoted T+1 waits for\none, it follows the offer the order is currently offered to, so it can change: it reads\n`false` between offers and on an instant offer. Once such an order stops waiting without\nbeing accepted (you cancelled it, or no licensed partner accepted it), it keeps `true`,\nwith `settlement_hours` `null`. Fixed from acceptance.\n"},"settlement_hours":{"type":"integer","nullable":true,"description":"The expected payout window, counted from the release — not from the order. It is the licensed partner's target for the bank payment, not a guaranteed deadline: nothing happens automatically when it passes. Rounded to the nearest whole hour and never below `1`. `null` on an instant order."},"consent_deadline_at":{"type":"string","format":"date-time","nullable":true,"description":"Funding time plus the consent window. After expiry, release is blocked and the expiry\nprocess starts the refund flow. Set while awaiting release, `null` otherwise.\n"},"payout_deadline_at":{"type":"string","format":"date-time","nullable":true,"description":"Release time plus the expected window; `settlement_hours` is that window rounded to whole\nhours. When the payment is expected by, not a deadline: the order does not change and no\nevent is sent when it passes. `null` until the crypto has left escrow.\n"},"delayed_settlement_crypto_sent_to_provider_at":{"type":"string","format":"date-time","nullable":true,"description":"The crypto left the licensed partner's wallet for the payout provider. Set at the latest when Unigox authorizes the bank payment. No refund of the crypto is possible while it is set. Cleared when Unigox withdraws a record made by mistake, which it can do only while no payment has been authorized, sent, paid or returned, and when it refunds the crypto after a returned payment."},"delayed_settlement_fiat_payout_authorized_by_admin_at":{"type":"string","format":"date-time","nullable":true,"description":"Unigox authorized the licensed partner to send the bank payment. Never set before `delayed_settlement_crypto_sent_to_provider_at`: the authorization sets that one too when it is still `null`. Cleared by a bank return, and when the payout provider cancels the payment before sending it; Unigox then authorizes a new attempt."},"delayed_settlement_fiat_payout_submitted_by_provider_at":{"type":"string","format":"date-time","nullable":true,"description":"Submission of the bank payment was recorded; recipient payment is not yet confirmed."},"delayed_settlement_fiat_paid_to_customer_at":{"type":"string","format":"date-time","nullable":true,"description":"The fiat reached the recipient. This is the real completion of a delayed order."},"delayed_settlement_fiat_returned_by_bank_at":{"type":"string","format":"date-time","nullable":true,"description":"The payout went out and the bank sent it back. Set together with clearing the paid, submitted and authorized marks. Mutually exclusive with `delayed_settlement_fiat_paid_to_customer_at`. A payment the payout provider cancelled before sending it is not a return and does not set it."},"delayed_settlement_crypto_refunded_to_customer_at":{"type":"string","format":"date-time","nullable":true,"description":"The crypto went back to the wallet that funded the escrow (yours, on an order whose crypto you hold) instead of being paid out. Reachable while `delayed_settlement_crypto_sent_to_provider_at` is `null`, or after a returned payment when Unigox gives the payout up; that refund clears `delayed_settlement_crypto_sent_to_provider_at`."},"source_of_funds_required":{"type":"boolean","description":"Whether review applies by amount or an existing source-of-funds case. Can stay true after approval or completion; use case status and next_action for required action. False for instant orders. Always present."},"source_of_funds_threshold_usd":{"type":"number","description":"Current configured source-of-funds threshold in USD, not a historical snapshot. Always present, including on instant orders. Current policy is USD 50,000 inclusive."},"settlement_refund_reason":{"type":"string","description":"Why a delayed order ended without a payout. Omitted — not empty — when the order has not\nended that way, or when none of the six applies; an absence means no reason was recorded\nand never stands in for one of them.\n\n- `refunded_after_release` — the crypto had been released to the licensed partner and\n  was sent back: before it reached the payout provider, or after a payment came back and\n  Unigox gave the payout up. No payment reached the customer; the order reads `cancelled`\n- `dossier_rejected` — a reviewer refused the source-of-funds case\n- `consent_window_expired` — the consent was never signed and the window ran out\n- `not_released_in_time` — the consent **was** signed and the window still ran out,\n  because Unigox did not release the crypto in time. This one is ours, not the\n  customer's\n- `cancelled_by_customer` — the order was cancelled on your side before release\n- `cancelled_by_licensed_partner` — the licensed partner declined the order before the\n  release was signed\n\nRead in that order: a refund after the release outranks a refusal, which outranks an\nexpired window, which outranks a cancellation.\n","enum":["refunded_after_release","dossier_rejected","consent_window_expired","not_released_in_time","cancelled_by_customer","cancelled_by_licensed_partner"]}}},"PartnerOrderStatus":{"type":"string","description":"Order status.\n\n**Off-ramp statuses (crypto → fiat):**\n- `created` — order created, quote locked\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_crypto_transfer_authorization` — partner must authorize crypto transfer via EIP-712 signature\n- `crypto_transfer_authorization_pending` — authorization submitted, awaiting on-chain confirmation\n- `crypto_received` — crypto locked in escrow\n- `fiat_payment_started` — buyer submitted fiat payment proof\n- `fiat_payment_review_started` — the proof is under review\n- `dispute_started` — a dispute was raised on the order\n- `awaiting_fiat_received_confirmation` — waiting for partner to confirm fiat receipt\n- `fiat_received_confirmed`, `crypto_release_pending` — timeline vocabulary. They appear in\n  `timeline[].status`; no order reports either as its own `status`, and filtering on them\n  returns nothing\n- `completed` — order fully completed\n- `cancelled` — order cancelled\n- `failed` — terminal error\n- `price_changed_requote_needed` — slippage exceeded at initiation. Like\n  `awaiting_liquidity_provider`, it is reported before a liquidity provider has accepted\n  the order, and `GET /partner/orders?status=` returns the orders that report it\n\n**Delayed settlement (T+1) statuses:**\n\n> Both are unreachable for an ordinary order.\n\n- `settlement_in_progress` — crypto release has started or is confirmed; the order is not\n  yet resolved. This alone does not mean a bank payment has been sent\n- `returned` — the payout went out and the bank sent it back, with no new payout\n  authorization. The crypto is not refunded yet: Unigox arranges another payout attempt, or\n  refunds the crypto and the order reads `cancelled`. A payout the provider cancelled before\n  sending it is not a return\n\nPrecedence on a delayed order, in this order — more than one mark can be set at once:\n\n1. `delayed_settlement_fiat_paid_to_customer_at` set → `completed`\n2. else `delayed_settlement_crypto_refunded_to_customer_at` set → `cancelled`\n3. else `delayed_settlement_fiat_returned_by_bank_at` set **and**\n   `delayed_settlement_fiat_payout_authorized_by_admin_at` `null` → `returned`\n4. else, on a release status → `settlement_in_progress`\n5. before the release, the ordinary mapping applies — a funded delayed order awaiting release is\n   `crypto_received` like any other, and `next_action` is what tells them apart\n\nA return with a fresh authorization on top reads as `settlement_in_progress` (step 4).\n\n**On-ramp statuses (fiat → crypto):**\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_vendor_escrow_funding` — vendor accepted, funding escrow with crypto\n- `awaiting_fiat_transfer` — crypto locked in escrow; the partner pays the vendor and confirms payment sent (`fiat_funding_source: vendor_details`), or the customer transfers into their own fiat account (`own_account`)\n- `fiat_transfer_pending` — fiat payment confirmed, awaiting vendor confirmation of receipt\n- `completed` — vendor confirmed fiat received, crypto released to end-user wallet\n- `cancelled` — order cancelled\n- `failed` — escrow error\n\n**On-ramp send-out statuses (optional post-trade cross-chain transfer):**\n\n> After an on-ramp order reaches `completed`, the partner may optionally initiate a\n> **send-out** — a cross-chain transfer of the received crypto to a destination network\n> (e.g. XAI → Arbitrum). This is an additional flow and does not affect the core trade lifecycle.\n> The `completed` status reflects that the trade itself is done; send-out statuses track\n> the subsequent cross-chain transfer only.\n\n- `send_out_pending` — send-out initiated, cross-chain transfer in progress\n- `send_out_completed` — cross-chain transfer successfully delivered to destination\n- `send_out_failed` — cross-chain transfer failed; the on-ramp trade itself remains completed\n","enum":["created","awaiting_liquidity_provider","awaiting_crypto_transfer_authorization","crypto_transfer_authorization_pending","crypto_received","fiat_payment_started","fiat_payment_review_started","dispute_started","awaiting_fiat_received_confirmation","fiat_received_confirmed","crypto_release_pending","awaiting_vendor_escrow_funding","awaiting_fiat_transfer","fiat_transfer_pending","completed","cancelled","failed","price_changed_requote_needed","settlement_in_progress","returned","send_out_pending","send_out_completed","send_out_failed"]},"PartnerOrderAmounts":{"type":"object","properties":{"crypto_amount":{"type":"string","description":"Total crypto amount (standard units) — the fee-exclusive gross: the buy/sell amount plus the\nplatform fee. Partner-fee-exclusive, except for a crypto-anchored onramp order (originally\nquoted with `crypto_amount`): there the amount was sized up so the delivered amount stays\nexact after the partner fee is withheld, so this field includes the markup. A crypto-anchored\nofframp order carves both fees out of the pinned deposit instead, so this field and\n`fee_breakdown.platform_fee` both shrink relative to a no-markup request, even though the\nmarkup itself stays out of this field. Every other case is unaffected — the markup is\nreported separately in `fee_breakdown.partner_fee`.\n\nOn-ramp — what the end user receives: `crypto_amount − fee_breakdown.platform_fee −\nfee_breakdown.partner_fee` for a fiat-anchored order, or exactly this `crypto_amount` for a\ncrypto-anchored order (both fees are withheld at bridge send-out without changing this\nfield). Off-ramp — what the partner funds at transfer authorization:\n`crypto_amount + fee_breakdown.partner_fee`.\n"},"fiat_amount":{"type":"string","description":"Fiat amount the user receives"},"crypto_currency":{"type":"string","description":"Cryptocurrency code"},"fiat_currency":{"type":"string","description":"Fiat currency code"},"rate":{"type":"string","description":"Crypto-to-fiat exchange rate"}}},"FeeBreakdown":{"type":"object","description":"Transparent breakdown of all fee components (amounts in crypto)","properties":{"platform_fee":{"type":"string","description":"Platform fee in crypto"},"platform_fee_pct":{"type":"number","format":"double","description":"Platform fee as a percentage"},"partner_fee":{"type":"string","description":"Your markup in crypto, computed from the `partner_fee_pct` you declared on the\nquote/estimate request, on the same base as the platform fee. `0` when no markup was declared.\n"},"partner_fee_pct":{"type":"number","format":"double","description":"Your markup percentage as declared on the request (`1` means 1%); `0` when none."},"total_fee":{"type":"string","description":"Total fee in crypto (platform_fee + partner_fee)"},"fiat_rail_fee":{"type":"string","description":"What the payout rail itself charges, in the order's **fiat** currency — every field above\nis in crypto. It is the gap between `rate × crypto_amount` and the money that actually\nmoves on the bank or wallet rail, and it is already reflected in `fiat_amount`.\n\nDeliberately **not** summed into `total_fee`: that is a crypto figure, and adding a fiat\namount to it would produce a number that means nothing. Reconciling a payout, add this to\n`fiat_amount` to get the gross the rate implies.\n\nAlways present; `\"0.00\"` on a rail that charges nothing.\n"},"fiat_rail_fee_currency":{"type":"string","description":"The currency `fiat_rail_fee` is denominated in, so a breakdown read on its own is never ambiguous about which of the order's two currencies a fee is in. Omitted when there is no rail fee to denominate."},"payout_base_rate":{"type":"string","description":"Optional on payout estimates and quotes. The conversion rate before the licensed partner's costs and margin, in fiat per crypto, when that licensed partner publishes it, for instant and T+1 offers. It lets you show the recipient amount and one combined fee without charging the fee twice: divide `fiat_amount` by this rate and round half up to the crypto's precision; the rest of `crypto_amount` is the combined fee. A separate partner markup stays separate. Omitted when the rate is not known or is out of date; its absence does not mean there is no margin. This is not the all-in rate; that is `rate`."}}},"TimelineEntry":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/PartnerOrderStatus"},"timestamp":{"type":"string","format":"date-time","description":"When this status was reached"},"description":{"type":"string","description":"Human-readable description of the status change.\n\nOn a **delayed settlement (T+1)** order the release entry reads\n`Crypto released to the liquidity provider, ahead of the payout` under\n`settlement_in_progress`, not `Order completed`: the crypto leaving escrow is the middle of\nthat order's story, not its end. Seven more entries follow it —\n`Crypto transferred to the payout provider`, `Fiat payout authorized`,\n`Fiat payout submitted by the provider` and\n`Fiat payout cancelled by the provider before it was sent` (all `settlement_in_progress`),\n`Fiat paid to the customer` (`completed`), `Fiat returned by the bank` (`returned`) and\n`Crypto refunded to the customer` (`cancelled`). An ordinary order's timeline is unchanged,\nentry for entry.\n\nConsecutive entries are collapsed by status; on a delayed order they are collapsed by status\n**and** description, so the intermediate facts that all carry `settlement_in_progress` each\nkeep their own line.\n\nOnce a payment has come back, or the payout provider cancelled it before sending it, and a\nnew attempt followed, every attempt stays on the timeline and the approval, sending, paid,\nreturn and cancellation entries end in `(attempt N)`, for example\n`Fiat payout authorized (attempt 2)` or `Fiat paid to the customer (attempt 2)`. With a\nsingle attempt there is no suffix. `Crypto transferred to the payout provider` is read from\nthe order's timestamp and leaves the timeline when that timestamp is cleared.\n"}}},"PartnerRecipientContext":{"type":"object","required":["sender_id","recipient_id","recipient_destination_id","sender_recipient_relationship","purpose_of_payment","screening_status"],"properties":{"sender_id":{"type":"string","format":"uuid"},"recipient_id":{"type":"string","format":"uuid"},"recipient_destination_id":{"type":"string","format":"uuid"},"sender_recipient_relationship":{"type":"string"},"purpose_of_payment":{"type":"string"},"purpose_details":{"type":"string"},"screening_status":{"type":"string"}}},"PartnerComplianceCase":{"type":"object","required":["case_id","status","risk_decision","requires_review"],"description":"The compliance record for a third-party payout. In v1 the controls run BEFORE the order is\ncreated, so a payout that fails one is rejected with an error rather than returned as a held\norder — see the error codes in the Third-party payouts guide.\n","properties":{"case_id":{"type":"string","format":"uuid","description":"Identifier of the compliance record — the payout's `quote_id`, so a partner and a Unigox\noperator refer to the same record.\n"},"status":{"type":"string","enum":["authorized"],"description":"v1 emits `authorized`; a rejected payout returns an error instead."},"risk_decision":{"type":"string","enum":["allow"],"description":"v1 emits `allow`; a blocking decision surfaces as an error, not a status."},"requires_review":{"type":"boolean","description":"Always false in v1. Operator review happens Unigox-side over the same record."}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/orders/{order_id}/cancel":{"post":{"tags":["Orders"],"summary":"Cancel order","description":"Cancel an order if cancellation is allowed at the current status.\nCheck `allowed_actions` on the order response — `cancel` is available when cancellation is permitted.\n\nOnce `authorize-crypto-transfer` has submitted the escrow funding, an off-ramp cannot be\ncancelled while that transfer may still execute: the call answers `409 OPERATION_NOT_ALLOWED`.\nIt can be cancelled again only if the submitted transfer failed without reaching the chain.\n","operationId":"cancelOrder","parameters":[{"name":"order_id","in":"path","required":true,"description":"Order UUID","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"description":"Optional. Send no body, or a JSON object. A body that is present must be valid JSON, otherwise the call answers `400`.","content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Free-text reason. On an order a liquidity provider has already accepted, the reason is kept with the cancellation for Unigox support, and `cancelled by partner` is recorded when it is omitted or empty. On an order still waiting for a liquidity provider to accept it, the reason is not recorded. It is never returned on the order."}}}}}},"responses":{"200":{"description":"Order cancelled successfully. Returns the order as it reads after the cancellation.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PartnerOrderResponse"}}}]}}}},"400":{"description":"`INVALID_REQUEST` — malformed `order_id`, or a request body that is present but not JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"401":{"description":"Unauthorized — invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"404":{"description":"Order not found"},"409":{"description":"`OPERATION_NOT_ALLOWED` — cancellation not allowed at the current status, including a delayed settlement (T+1) order whose consent is signed or whose crypto transfer is already submitted. Read the order: `allowed_actions` says whether `cancel` is still offered. On a delayed order a consent call that is still running, or one cut off before its signature was stored, also refuses the cancel, for up to two minutes after that call while `allowed_actions` still offers `cancel`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR` — the cancellation could not be completed. Read the order before retrying: its `status` and `allowed_actions` say whether it was cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## List orders

> Get a paginated list of orders with optional filtering by status.\
> Each order includes \`allowed\_actions\` indicating which API actions are available.\
> \
> The list also contains \*\*widget orders\*\* — orders your customers created through the\
> embedded Unigox widget under your \`widgetKey\`. Those are attributed to you for reporting\
> and markup, but the crypto belongs to the end user, so they are \*\*notify-only\*\*: they\
> appear here and in your webhook stream, and every action endpoint answers \`404\
> ORDER\_NOT\_FOUND\` for them.\
> \
> The guarantee runs one way only. A widget order is always \`\[]\`, and any action listed is\
> one the endpoint will accept — but \`\[]\` does NOT mean an order is a widget order. Your own\
> orders are also \`\[]\` whenever their status carries no action for you, including the\
> mid-flight \`crypto\_transfer\_authorization\_pending\`. Reading an empty array as "this is a\
> customer's order" would misclassify your own live orders and stop you tracking them.\
> \
> Keep acting only on order ids your own \`initiate\` call returned. That rule still holds as\
> defence in depth, and it is the one that does not depend on reading a field correctly.\
> \
> To read a specific widget order, the embedded widget's \`onTradeStarted\` and\
> \`onTradeCompleted\` callbacks carry \`orderId\` — the same \`order\_id\` used here and in your\
> webhooks. Its sibling \`tradeId\` is a Unigox-internal numeric id and is \*\*not\*\* accepted by\
> this API: \`GET /partner/orders/{order\_id}\` validates the path segment as a UUID and answers\
> \`400 invalid order\_id format\` for it.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management, status tracking, and lifecycle actions"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"PartnerOrderStatus":{"type":"string","description":"Order status.\n\n**Off-ramp statuses (crypto → fiat):**\n- `created` — order created, quote locked\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_crypto_transfer_authorization` — partner must authorize crypto transfer via EIP-712 signature\n- `crypto_transfer_authorization_pending` — authorization submitted, awaiting on-chain confirmation\n- `crypto_received` — crypto locked in escrow\n- `fiat_payment_started` — buyer submitted fiat payment proof\n- `fiat_payment_review_started` — the proof is under review\n- `dispute_started` — a dispute was raised on the order\n- `awaiting_fiat_received_confirmation` — waiting for partner to confirm fiat receipt\n- `fiat_received_confirmed`, `crypto_release_pending` — timeline vocabulary. They appear in\n  `timeline[].status`; no order reports either as its own `status`, and filtering on them\n  returns nothing\n- `completed` — order fully completed\n- `cancelled` — order cancelled\n- `failed` — terminal error\n- `price_changed_requote_needed` — slippage exceeded at initiation. Like\n  `awaiting_liquidity_provider`, it is reported before a liquidity provider has accepted\n  the order, and `GET /partner/orders?status=` returns the orders that report it\n\n**Delayed settlement (T+1) statuses:**\n\n> Both are unreachable for an ordinary order.\n\n- `settlement_in_progress` — crypto release has started or is confirmed; the order is not\n  yet resolved. This alone does not mean a bank payment has been sent\n- `returned` — the payout went out and the bank sent it back, with no new payout\n  authorization. The crypto is not refunded yet: Unigox arranges another payout attempt, or\n  refunds the crypto and the order reads `cancelled`. A payout the provider cancelled before\n  sending it is not a return\n\nPrecedence on a delayed order, in this order — more than one mark can be set at once:\n\n1. `delayed_settlement_fiat_paid_to_customer_at` set → `completed`\n2. else `delayed_settlement_crypto_refunded_to_customer_at` set → `cancelled`\n3. else `delayed_settlement_fiat_returned_by_bank_at` set **and**\n   `delayed_settlement_fiat_payout_authorized_by_admin_at` `null` → `returned`\n4. else, on a release status → `settlement_in_progress`\n5. before the release, the ordinary mapping applies — a funded delayed order awaiting release is\n   `crypto_received` like any other, and `next_action` is what tells them apart\n\nA return with a fresh authorization on top reads as `settlement_in_progress` (step 4).\n\n**On-ramp statuses (fiat → crypto):**\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_vendor_escrow_funding` — vendor accepted, funding escrow with crypto\n- `awaiting_fiat_transfer` — crypto locked in escrow; the partner pays the vendor and confirms payment sent (`fiat_funding_source: vendor_details`), or the customer transfers into their own fiat account (`own_account`)\n- `fiat_transfer_pending` — fiat payment confirmed, awaiting vendor confirmation of receipt\n- `completed` — vendor confirmed fiat received, crypto released to end-user wallet\n- `cancelled` — order cancelled\n- `failed` — escrow error\n\n**On-ramp send-out statuses (optional post-trade cross-chain transfer):**\n\n> After an on-ramp order reaches `completed`, the partner may optionally initiate a\n> **send-out** — a cross-chain transfer of the received crypto to a destination network\n> (e.g. XAI → Arbitrum). This is an additional flow and does not affect the core trade lifecycle.\n> The `completed` status reflects that the trade itself is done; send-out statuses track\n> the subsequent cross-chain transfer only.\n\n- `send_out_pending` — send-out initiated, cross-chain transfer in progress\n- `send_out_completed` — cross-chain transfer successfully delivered to destination\n- `send_out_failed` — cross-chain transfer failed; the on-ramp trade itself remains completed\n","enum":["created","awaiting_liquidity_provider","awaiting_crypto_transfer_authorization","crypto_transfer_authorization_pending","crypto_received","fiat_payment_started","fiat_payment_review_started","dispute_started","awaiting_fiat_received_confirmation","fiat_received_confirmed","crypto_release_pending","awaiting_vendor_escrow_funding","awaiting_fiat_transfer","fiat_transfer_pending","completed","cancelled","failed","price_changed_requote_needed","settlement_in_progress","returned","send_out_pending","send_out_completed","send_out_failed"]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PartnerOrderResponse":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid","description":"Unique order identifier"},"status":{"$ref":"#/components/schemas/PartnerOrderStatus"},"next_action":{"type":"string","description":"The action the partner **must** perform to advance the order. The key is **absent**\nwhen no action is required at this stage — the order is waiting for the\ncounterparty or for an automated system step — and is never sent as `null`.\n\nPossible values:\n- `authorize_crypto_transfer` — partner must authorize escrow funding\n- `confirm_fiat_received` — partner must confirm they received the fiat payment\n- `request_new_quote` — price changed, partner must request a new quote\n- `update_kyc_address` — address fields are required for EUR/AUD/GBP payouts; see `action_required` for the endpoint and fields to submit\n- `authorize_refund` — the order ended without a payout and its crypto is still in escrow; only your\n  signature can send it back. Note that this appears on an order whose `status` is `cancelled`, which\n  is the one case where a terminal status still needs something from you\n- `deposit_to_user_account` — an on-ramp order with `fiat_funding_source: own_account` is waiting for the\n  customer to transfer the order's fiat amount into the fiat account issued to them. The transfer\n  itself confirms the payment; there is nothing to call. If the money is already on the account,\n  `pay-from-balance` is in `allowed_actions` and pays the order from it\n- `sign_settlement_consent` — a **delayed settlement (T+1)** order remains at `crypto_received`\n  and nobody has signed the release yet\n- `submit_source_of_funds` — consent is stored and a required source-of-funds case is\n  incomplete, including an existing case below the current threshold\n- `await_review` — consent is stored and the order is waiting for Unigox document review,\n  the licensed partner's payment check, or release processing. Do not submit another signature\n- absent — no required action (waiting for buyer or system). On a funded delayed order awaiting release\n  the key is absent when the order is held for review, or a payout of yours failed and a\n  refund is under way\n\nOnce consent_deadline_at has passed, these reads no longer request a consent signature,\neven if the order status has not changed yet.\nThe list (`GET /api/v1/partner/orders`) reads the consent from the order record and can show\n`await_review`, for up to two minutes, for a consent call that was cut off before your signature\nwas stored. After a\ntimeout, read the single order (`GET /api/v1/partner/orders/{order_id}`) before you decide\nwhether to send the signature again. If a lookup behind the T+1 hint fails, both reads fall\nback to `sign_settlement_consent`.\n","enum":["authorize_crypto_transfer","confirm_fiat_received","request_new_quote","update_kyc_address","authorize_refund","deposit_to_user_account","sign_settlement_consent","submit_source_of_funds","await_review"]},"action_required":{"type":"object","nullable":true,"description":"Present when the order needs partner intervention before it can proceed.\nContains machine-readable type, human-readable message, the API endpoint to call,\nand the fields to provide. Null/omitted when no action is needed.\n","required":["type","message"],"properties":{"type":{"type":"string","description":"Machine-readable action identifier"},"message":{"type":"string","description":"Human-readable explanation of what is needed and why"},"endpoint":{"type":"string","description":"API endpoint to call to resolve this action"},"fields":{"type":"array","description":"Fields the partner needs to provide","items":{"type":"object","required":["field","label"],"properties":{"field":{"type":"string","description":"API field name"},"label":{"type":"string","description":"Human-readable description of the field"}}}}}},"allowed_actions":{"type":"array","items":{"type":"string"},"description":"List of API actions the partner **can** perform at the current status. An action\nmay be present here even when `next_action` is absent — meaning it is optional.\n\nNotable case: `confirm-fiat-received` appears at both `crypto_received` and\n`awaiting_fiat_received_confirmation`. At `crypto_received` it is a **fast-track**:\nif you already know the fiat has arrived via your own systems, you can confirm\nimmediately. Otherwise, wait for the buyer's proof flow to complete — the order\nwill reach `awaiting_fiat_received_confirmation` automatically.\n\nStatus-to-actions mapping:\n- `created` → `[\"cancel\"]`\n- `awaiting_liquidity_provider` → `[\"cancel\"]`\n- `awaiting_crypto_transfer_authorization` → `[\"authorize-crypto-transfer\", \"cancel\"]`\n- `crypto_transfer_authorization_pending` → `[]` (the transfer is in flight; cancel is refused)\n- `crypto_received` → `[\"confirm-fiat-received\"]` (optional fast-track)\n- `fiat_payment_started` → `[\"confirm-fiat-received\"]` (optional fast-track after buyer proof submission)\n- `awaiting_fiat_received_confirmation` → `[\"confirm-fiat-received\"]` (required)\n- `fiat_received_confirmed`, `crypto_release_pending`, `completed`, `failed` → `[]`\n- `cancelled` → `[]`, **except** when the order's crypto is still sitting in escrow: then\n  `[\"authorize-refund\"]`. An off-ramp order that stops after funding — expired payment window,\n  declined payment proof, returned bank payment, dispute resolved for the seller — reads as\n  `cancelled` like every other stopped order, and the escrow is a 2-of-3 Safe your key is an\n  owner of. This is the only thing that tells the two apart, so poll it on `cancelled` orders\n  rather than assuming a cancelled order is finished with. `next_action` is\n  `authorize_refund` and `action_required` names the endpoint at the same time.\n\nOn-ramp orders with `fiat_funding_source: own_account` never offer `confirm-payment-sent`: the\ntransfer into the customer's own account is the confirmation. At `awaiting_fiat_transfer` they\noffer `[\"pay-from-balance\"]` instead, until the order's fiat has been collected. A `completed`\norder paid from the balance whose crypto hand-over has not finished also offers\n`[\"pay-from-balance\"]`: calling it again retries the hand-over and never takes the money twice.\n\nOn a funded **delayed settlement (T+1)** order awaiting release whose crypto you hold,\n`confirm-fiat-received` is removed — the endpoint behind it refuses a delayed order — and\n`[\"settlement-consent\", \"cancel\"]` take its place.\n\n`cancel` is available only while the order awaits release; the endpoint is the ordinary\n`POST /api/v1/partner/orders/{order_id}/cancel`.\n\nBoth are withdrawn once the consent is signed, and then answer\n`409 OPERATION_NOT_ALLOWED`. The list reads the consent from the order record, so a list row\ncan already show them withdrawn, for up to two minutes, for a consent call that was cut off\nbefore your signature was\nstored. After a timeout, read the single order (`GET /api/v1/partner/orders/{order_id}`)\nbefore you decide whether to send the signature again.\n\nOn a funded delayed order awaiting release that is **held** — Unigox holds it for a check, or a\npayout failed and a refund is under way — `next_action` is omitted and no consent is accepted.\n`confirm-fiat-received` is absent there too, because that endpoint refuses every delayed\norder. An `authorize-refund` that is genuinely owed still appears.\nCustody outranks the mapping above: on a **widget order** — one your customer created\nthrough the embedded widget under your `widgetKey` — this is `[]` at every status,\nbecause the crypto is the end user's and every action endpoint answers `404\nORDER_NOT_FOUND` for it.\n"},"fiat_funding_source":{"type":"string","enum":["vendor_details","own_account"],"description":"On-ramp orders only. Where the fiat for this order is paid:\n- `vendor_details` — to the vendor's bank account in `vendor_payment_details`; then call\n  `confirm-payment-sent`.\n- `own_account` — into the fiat account you issued to the customer, named by\n  `fiat_account_id`. There are no `vendor_payment_details` and no `confirm-payment-sent`:\n  the transfer landing on the customer's account is matched to the order by amount and the\n  order proceeds on its own.\n\nRead it on every order rather than assuming one or the other.\n"},"fiat_account_id":{"type":"string","format":"uuid","description":"On an `own_account` order: the fiat account the customer transfers into. The same id the\nFiat Accounts endpoints take, so the deposit that funds this order can be found on that\naccount's transactions carrying this order's id.\nOn an off-ramp with `payout_via_own_account: true`: the customer's fiat account the money\ngoes through, when it is one you can address by id; omitted otherwise.\n"},"payout_via_own_account":{"type":"boolean","description":"`true` on an off-ramp paid through the customer's own fiat account: the liquidity provider\npays the customer's account and Unigox then pays the money on to the bank you named, both in\nthe customer's name. EUR and GBP off-ramps to the customer's own `payment_details` are paid\nthis way wherever customer fiat accounts are active for your partner in that currency; when\nthey cannot be, the quote is refused (`FIAT_ACCOUNT_OPENING`, `FIAT_ACCOUNT_REQUIRED`,\n`FIAT_ACCOUNTS_NOT_ENABLED`) unless a liquidity provider that pays banks directly takes the\norder. Omitted on every other order, never `false`. If you do not call\n`confirm-fiat-received`, the order is confirmed once Unigox has matched the money on the\ncustomer's account. That payment into the account does not send\n`fiat_account.deposit.received`.\n"},"own_account_payout_status":{"type":"string","enum":["awaiting_credit","in_progress","sent_to_bank","under_review","held","left_on_account"],"description":"Off-ramp paid through the customer's own fiat account only (`payout_via_own_account: true`):\nwhere the onward payment, from that account to the bank you named, stands. `status` describes\nthe provider's payment into the customer's account, so an order can be `completed` while this\nstill says the money has not reached the bank.\n- `awaiting_credit` — nothing has landed on the customer's account for this order yet.\n- `in_progress` — the money landed; the onward payment is queued, being sent, or being retried.\n- `sent_to_bank` — the money was sent on to the bank you named.\n- `under_review` — the onward payment ended without a clear result; Unigox checks it.\n- `held` — the money is on the customer's account and is not moving on by itself; contact Unigox.\n- `left_on_account` — Unigox decided the money stays on the customer's account.\n\nOmitted on other orders, and when the state cannot be read at that moment.\n"},"crypto_transfer_authorization_seconds_left":{"type":"integer","format":"int64","nullable":true,"description":"Remaining seconds to authorize crypto transfer while order is in\n`awaiting_crypto_transfer_authorization` / `crypto_transfer_authorization_pending`.\n`null` for all other statuses.\n"},"amounts":{"$ref":"#/components/schemas/PartnerOrderAmounts"},"fee_breakdown":{"$ref":"#/components/schemas/FeeBreakdown"},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/TimelineEntry"},"description":"Chronological list of status changes"},"has_fiat_settlement_notification":{"type":"boolean","description":"Whether the matched liquidity provider sends fiat settlement notifications.\nWhen `true`, the order will complete automatically when fiat is delivered.\nWhen `false`, you must call `confirm-fiat-received`. You can call\n`confirm-fiat-received` at any time regardless of this value, except on a delayed\nsettlement (T+1) order, which refuses it. `false` on every order no liquidity provider\nhas accepted yet, T+1 included; a T+1 order reads `true` from its acceptance on.\n"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"order_type":{"type":"string","enum":["offramp","onramp"],"description":"Order type. Present on every order, including one no liquidity provider has accepted yet.\n- `offramp` — sell crypto for fiat\n- `onramp` — buy crypto with fiat\n"},"vendor_payment_details":{"type":"object","nullable":true,"description":"Vendor's payment details for the end-user to send fiat to.\nPresent only for on-ramp orders at `awaiting_fiat_transfer` status and beyond.\n","properties":{"payment_method_name":{"type":"string"},"payment_network_name":{"type":"string"},"details":{"type":"object","description":"Payment method-specific fields (e.g. account_number, phone)"}}},"payment_request":{"type":"boolean","nullable":true,"description":"`true` if the vendor uses payment request flow — the partner must call\n`submit-payer-details` before `confirm-payment-sent`.\n"},"send_out_tx_hash":{"type":"string","nullable":true,"description":"Destination-chain transaction hash after a send-out completes.\nPresent only for on-ramp orders with `send_out_completed` status.\n"},"payment_deadline_at":{"type":"string","format":"date-time","nullable":true,"description":"On-ramp only: the moment the order can be cancelled for want of the customer's fiat.\nTell the customer to pay before it. The order is cancelled shortly after it (`cancelled`,\n\"Payment window expired\"): on your next read of the order, and an `own_account` order\nwithin about 20 minutes even if nobody reads it. A transfer that arrives after this moment but before the cancellation may\nstill complete the order; that is possible, not guaranteed. One that arrives after the\ncancellation stays on the customer's account and can be used with `pay-from-balance` on a\nnew order. Extended along with the window.\nSet while the order is `awaiting_fiat_transfer`, `null` otherwise — and always `null`\non an off-ramp, and on an order held for manual handling (it does not expire). UTC.\n"},"recipient_context":{"allOf":[{"$ref":"#/components/schemas/PartnerRecipientContext"}],"nullable":true,"description":"Immutable third-party recipient context; absent for self-payout and on-ramp."},"compliance":{"allOf":[{"$ref":"#/components/schemas/PartnerComplianceCase"}],"nullable":true,"description":"Current durable compliance-case state for a third-party payout."},"delayed_settlement":{"type":"boolean","description":"Whether this order settles **T+1**: the crypto leaves escrow before the fiat is paid.\nYour release signature authorises it to leave and Unigox performs the release; the fiat\nis expected within `settlement_hours` of it (a target, not a deadline). Present on every\norder, on-ramp included, along\nwith the other T+1 fields below. T+1 timestamps and the window are null on instant\norders. The current numeric source-of-funds threshold is still returned.\n\nProvisional until a licensed partner accepts the order. While an order quoted T+1 waits for\none, it follows the offer the order is currently offered to, so it can change: it reads\n`false` between offers and on an instant offer. Once such an order stops waiting without\nbeing accepted (you cancelled it, or no licensed partner accepted it), it keeps `true`,\nwith `settlement_hours` `null`. Fixed from acceptance.\n"},"settlement_hours":{"type":"integer","nullable":true,"description":"The expected payout window, counted from the release — not from the order. It is the licensed partner's target for the bank payment, not a guaranteed deadline: nothing happens automatically when it passes. Rounded to the nearest whole hour and never below `1`. `null` on an instant order."},"consent_deadline_at":{"type":"string","format":"date-time","nullable":true,"description":"Funding time plus the consent window. After expiry, release is blocked and the expiry\nprocess starts the refund flow. Set while awaiting release, `null` otherwise.\n"},"payout_deadline_at":{"type":"string","format":"date-time","nullable":true,"description":"Release time plus the expected window; `settlement_hours` is that window rounded to whole\nhours. When the payment is expected by, not a deadline: the order does not change and no\nevent is sent when it passes. `null` until the crypto has left escrow.\n"},"delayed_settlement_crypto_sent_to_provider_at":{"type":"string","format":"date-time","nullable":true,"description":"The crypto left the licensed partner's wallet for the payout provider. Set at the latest when Unigox authorizes the bank payment. No refund of the crypto is possible while it is set. Cleared when Unigox withdraws a record made by mistake, which it can do only while no payment has been authorized, sent, paid or returned, and when it refunds the crypto after a returned payment."},"delayed_settlement_fiat_payout_authorized_by_admin_at":{"type":"string","format":"date-time","nullable":true,"description":"Unigox authorized the licensed partner to send the bank payment. Never set before `delayed_settlement_crypto_sent_to_provider_at`: the authorization sets that one too when it is still `null`. Cleared by a bank return, and when the payout provider cancels the payment before sending it; Unigox then authorizes a new attempt."},"delayed_settlement_fiat_payout_submitted_by_provider_at":{"type":"string","format":"date-time","nullable":true,"description":"Submission of the bank payment was recorded; recipient payment is not yet confirmed."},"delayed_settlement_fiat_paid_to_customer_at":{"type":"string","format":"date-time","nullable":true,"description":"The fiat reached the recipient. This is the real completion of a delayed order."},"delayed_settlement_fiat_returned_by_bank_at":{"type":"string","format":"date-time","nullable":true,"description":"The payout went out and the bank sent it back. Set together with clearing the paid, submitted and authorized marks. Mutually exclusive with `delayed_settlement_fiat_paid_to_customer_at`. A payment the payout provider cancelled before sending it is not a return and does not set it."},"delayed_settlement_crypto_refunded_to_customer_at":{"type":"string","format":"date-time","nullable":true,"description":"The crypto went back to the wallet that funded the escrow (yours, on an order whose crypto you hold) instead of being paid out. Reachable while `delayed_settlement_crypto_sent_to_provider_at` is `null`, or after a returned payment when Unigox gives the payout up; that refund clears `delayed_settlement_crypto_sent_to_provider_at`."},"source_of_funds_required":{"type":"boolean","description":"Whether review applies by amount or an existing source-of-funds case. Can stay true after approval or completion; use case status and next_action for required action. False for instant orders. Always present."},"source_of_funds_threshold_usd":{"type":"number","description":"Current configured source-of-funds threshold in USD, not a historical snapshot. Always present, including on instant orders. Current policy is USD 50,000 inclusive."},"settlement_refund_reason":{"type":"string","description":"Why a delayed order ended without a payout. Omitted — not empty — when the order has not\nended that way, or when none of the six applies; an absence means no reason was recorded\nand never stands in for one of them.\n\n- `refunded_after_release` — the crypto had been released to the licensed partner and\n  was sent back: before it reached the payout provider, or after a payment came back and\n  Unigox gave the payout up. No payment reached the customer; the order reads `cancelled`\n- `dossier_rejected` — a reviewer refused the source-of-funds case\n- `consent_window_expired` — the consent was never signed and the window ran out\n- `not_released_in_time` — the consent **was** signed and the window still ran out,\n  because Unigox did not release the crypto in time. This one is ours, not the\n  customer's\n- `cancelled_by_customer` — the order was cancelled on your side before release\n- `cancelled_by_licensed_partner` — the licensed partner declined the order before the\n  release was signed\n\nRead in that order: a refund after the release outranks a refusal, which outranks an\nexpired window, which outranks a cancellation.\n","enum":["refunded_after_release","dossier_rejected","consent_window_expired","not_released_in_time","cancelled_by_customer","cancelled_by_licensed_partner"]}}},"PartnerOrderAmounts":{"type":"object","properties":{"crypto_amount":{"type":"string","description":"Total crypto amount (standard units) — the fee-exclusive gross: the buy/sell amount plus the\nplatform fee. Partner-fee-exclusive, except for a crypto-anchored onramp order (originally\nquoted with `crypto_amount`): there the amount was sized up so the delivered amount stays\nexact after the partner fee is withheld, so this field includes the markup. A crypto-anchored\nofframp order carves both fees out of the pinned deposit instead, so this field and\n`fee_breakdown.platform_fee` both shrink relative to a no-markup request, even though the\nmarkup itself stays out of this field. Every other case is unaffected — the markup is\nreported separately in `fee_breakdown.partner_fee`.\n\nOn-ramp — what the end user receives: `crypto_amount − fee_breakdown.platform_fee −\nfee_breakdown.partner_fee` for a fiat-anchored order, or exactly this `crypto_amount` for a\ncrypto-anchored order (both fees are withheld at bridge send-out without changing this\nfield). Off-ramp — what the partner funds at transfer authorization:\n`crypto_amount + fee_breakdown.partner_fee`.\n"},"fiat_amount":{"type":"string","description":"Fiat amount the user receives"},"crypto_currency":{"type":"string","description":"Cryptocurrency code"},"fiat_currency":{"type":"string","description":"Fiat currency code"},"rate":{"type":"string","description":"Crypto-to-fiat exchange rate"}}},"FeeBreakdown":{"type":"object","description":"Transparent breakdown of all fee components (amounts in crypto)","properties":{"platform_fee":{"type":"string","description":"Platform fee in crypto"},"platform_fee_pct":{"type":"number","format":"double","description":"Platform fee as a percentage"},"partner_fee":{"type":"string","description":"Your markup in crypto, computed from the `partner_fee_pct` you declared on the\nquote/estimate request, on the same base as the platform fee. `0` when no markup was declared.\n"},"partner_fee_pct":{"type":"number","format":"double","description":"Your markup percentage as declared on the request (`1` means 1%); `0` when none."},"total_fee":{"type":"string","description":"Total fee in crypto (platform_fee + partner_fee)"},"fiat_rail_fee":{"type":"string","description":"What the payout rail itself charges, in the order's **fiat** currency — every field above\nis in crypto. It is the gap between `rate × crypto_amount` and the money that actually\nmoves on the bank or wallet rail, and it is already reflected in `fiat_amount`.\n\nDeliberately **not** summed into `total_fee`: that is a crypto figure, and adding a fiat\namount to it would produce a number that means nothing. Reconciling a payout, add this to\n`fiat_amount` to get the gross the rate implies.\n\nAlways present; `\"0.00\"` on a rail that charges nothing.\n"},"fiat_rail_fee_currency":{"type":"string","description":"The currency `fiat_rail_fee` is denominated in, so a breakdown read on its own is never ambiguous about which of the order's two currencies a fee is in. Omitted when there is no rail fee to denominate."},"payout_base_rate":{"type":"string","description":"Optional on payout estimates and quotes. The conversion rate before the licensed partner's costs and margin, in fiat per crypto, when that licensed partner publishes it, for instant and T+1 offers. It lets you show the recipient amount and one combined fee without charging the fee twice: divide `fiat_amount` by this rate and round half up to the crypto's precision; the rest of `crypto_amount` is the combined fee. A separate partner markup stays separate. Omitted when the rate is not known or is out of date; its absence does not mean there is no margin. This is not the all-in rate; that is `rate`."}}},"TimelineEntry":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/PartnerOrderStatus"},"timestamp":{"type":"string","format":"date-time","description":"When this status was reached"},"description":{"type":"string","description":"Human-readable description of the status change.\n\nOn a **delayed settlement (T+1)** order the release entry reads\n`Crypto released to the liquidity provider, ahead of the payout` under\n`settlement_in_progress`, not `Order completed`: the crypto leaving escrow is the middle of\nthat order's story, not its end. Seven more entries follow it —\n`Crypto transferred to the payout provider`, `Fiat payout authorized`,\n`Fiat payout submitted by the provider` and\n`Fiat payout cancelled by the provider before it was sent` (all `settlement_in_progress`),\n`Fiat paid to the customer` (`completed`), `Fiat returned by the bank` (`returned`) and\n`Crypto refunded to the customer` (`cancelled`). An ordinary order's timeline is unchanged,\nentry for entry.\n\nConsecutive entries are collapsed by status; on a delayed order they are collapsed by status\n**and** description, so the intermediate facts that all carry `settlement_in_progress` each\nkeep their own line.\n\nOnce a payment has come back, or the payout provider cancelled it before sending it, and a\nnew attempt followed, every attempt stays on the timeline and the approval, sending, paid,\nreturn and cancellation entries end in `(attempt N)`, for example\n`Fiat payout authorized (attempt 2)` or `Fiat paid to the customer (attempt 2)`. With a\nsingle attempt there is no suffix. `Crypto transferred to the payout provider` is read from\nthe order's timestamp and leaves the timeline when that timestamp is cleared.\n"}}},"PartnerRecipientContext":{"type":"object","required":["sender_id","recipient_id","recipient_destination_id","sender_recipient_relationship","purpose_of_payment","screening_status"],"properties":{"sender_id":{"type":"string","format":"uuid"},"recipient_id":{"type":"string","format":"uuid"},"recipient_destination_id":{"type":"string","format":"uuid"},"sender_recipient_relationship":{"type":"string"},"purpose_of_payment":{"type":"string"},"purpose_details":{"type":"string"},"screening_status":{"type":"string"}}},"PartnerComplianceCase":{"type":"object","required":["case_id","status","risk_decision","requires_review"],"description":"The compliance record for a third-party payout. In v1 the controls run BEFORE the order is\ncreated, so a payout that fails one is rejected with an error rather than returned as a held\norder — see the error codes in the Third-party payouts guide.\n","properties":{"case_id":{"type":"string","format":"uuid","description":"Identifier of the compliance record — the payout's `quote_id`, so a partner and a Unigox\noperator refer to the same record.\n"},"status":{"type":"string","enum":["authorized"],"description":"v1 emits `authorized`; a rejected payout returns an error instead."},"risk_decision":{"type":"string","enum":["allow"],"description":"v1 emits `allow`; a blocking decision surfaces as an error, not a status."},"requires_review":{"type":"boolean","description":"Always false in v1. Operator review happens Unigox-side over the same record."}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/orders":{"get":{"tags":["Orders"],"summary":"List orders","description":"Get a paginated list of orders with optional filtering by status.\nEach order includes `allowed_actions` indicating which API actions are available.\n\nThe list also contains **widget orders** — orders your customers created through the\nembedded Unigox widget under your `widgetKey`. Those are attributed to you for reporting\nand markup, but the crypto belongs to the end user, so they are **notify-only**: they\nappear here and in your webhook stream, and every action endpoint answers `404\nORDER_NOT_FOUND` for them.\n\nThe guarantee runs one way only. A widget order is always `[]`, and any action listed is\none the endpoint will accept — but `[]` does NOT mean an order is a widget order. Your own\norders are also `[]` whenever their status carries no action for you, including the\nmid-flight `crypto_transfer_authorization_pending`. Reading an empty array as \"this is a\ncustomer's order\" would misclassify your own live orders and stop you tracking them.\n\nKeep acting only on order ids your own `initiate` call returned. That rule still holds as\ndefence in depth, and it is the one that does not depend on reading a field correctly.\n\nTo read a specific widget order, the embedded widget's `onTradeStarted` and\n`onTradeCompleted` callbacks carry `orderId` — the same `order_id` used here and in your\nwebhooks. Its sibling `tradeId` is a Unigox-internal numeric id and is **not** accepted by\nthis API: `GET /partner/orders/{order_id}` validates the path segment as a UUID and answers\n`400 invalid order_id format` for it.\n","operationId":"listOrders","parameters":[{"name":"status","in":"query","required":false,"description":"Accepts exactly the values of the `PartnerOrderStatus` enum below, on-ramp and off-ramp\nalike. Anything else answers `400 INVALID_REQUEST` — including `awaiting_vendor_acceptance`,\n`awaiting_crypto_submit` and `crypto_submit_pending`, which are internal constants this API\nnever reports and the enum does not carry.\n\nTwo of the accepted values can never match a row and answer an empty `200`:\n`fiat_received_confirmed` and `crypto_release_pending` are shadowed by `completed`, which\nevery internal status behind them reports.\n\n`awaiting_liquidity_provider` and `price_changed_requote_needed` return the orders no\nliquidity provider has accepted yet that report them: an order that is still waiting\nfor acceptance, and one whose price moved past its slippage at initiation. Poll\n`awaiting_liquidity_provider` to follow a new order until it is accepted. The other\nstatuses an unaccepted order can report (`created`, `awaiting_crypto_transfer_authorization`,\n`cancelled`, `failed`) return it under their filters too.\n\nA ramp-specific status implies its trade type, so `status` and `type` need not be paired.\nPassing a `type` that contradicts the status is not an error either — it is simply a\nfilter nothing satisfies, and answers an empty page. `send_out_pending`,\n`send_out_completed` and `send_out_failed` narrow on an on-ramp order's send-out\nsub-state, which lives beside `completed` rather than in the trade status. The same fact\nruns the other way: `status=completed` can return an on-ramp row whose own `status` reads\n`send_out_pending`, `send_out_completed` or `send_out_failed`, because the trade did\ncomplete and the bridge-out is a later step — a failed one stays visible instead of\nhiding as \"completed\".\n\nOn **delayed settlement (T+1)** orders the four release-bearing filters mean:\n\n- `completed` — ordinary released orders, and delayed orders whose fiat actually reached\n  the customer. A released but unpaid delayed order is not here\n- `settlement_in_progress` — delayed, released, and not yet resolved either way. A\n  standing bank return with no new attempt approved yet belongs under `returned`\n- `returned` — the bank sent the payout back and nobody has authorized another attempt\n- `cancelled` — orders that stopped before settlement, as before, **plus** delayed orders\n  whose crypto was refunded after the release\n\nFor these four values a filter returns exactly the orders whose `status` reports that\nvalue. So do `awaiting_crypto_transfer_authorization` and\n`crypto_transfer_authorization_pending`: the two share one internal status and are told\napart by whether the funding transfer was submitted, exactly as the order reports them.\n`crypto_received` is wider on purpose: it returns every off-ramp order whose crypto is in\nescrow while the payment is unfinished, including rows that report\n`fiat_payment_started`, `fiat_payment_review_started` or `dispute_started`.\n","schema":{"$ref":"#/components/schemas/PartnerOrderStatus"}},{"name":"type","in":"query","required":false,"description":"Restrict to one ramp: `onramp` or `offramp`. Omit for both. Any other value is ignored rather than refused, so a typo widens the page instead of failing it.","schema":{"type":"string","enum":["onramp","offramp"]}},{"name":"reference_id","in":"query","required":false,"description":"Return only the orders you created with this `reference_id` on initiate, newest first, at\nmost 100. Use it to find an order when the initiate response was lost. Each entry is the\nsame object `GET /partner/orders/{order_id}` returns.\n\n`reference_id` is not enforced unique, so the answer is a list. Combines with `type`,\n`page` and `limit`. Combined with `status` it answers `400 INVALID_REQUEST`. At most 255\ncharacters.\n","schema":{"type":"string","maxLength":255}},{"name":"page","in":"query","required":false,"description":"Page number (default 1)","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","required":false,"description":"Results per page (default 20, max 100)","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Orders retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/PartnerOrderResponse"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total_count":{"type":"integer"},"total_pages":{"type":"integer"}}}}}}}]}}}},"401":{"description":"Unauthorized — invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## Order stats

> Headline numbers for your whole order history in one call: how many orders you have, how many\
> completed, and the fiat volume and markup earned on the completed ones. This is what the partner\
> dashboard tiles show.\
> \
> Volume and earnings cover \*\*completed\*\* orders only and are reported in \*\*USD\*\*, each order\
> converted at the rate snapshotted when it was created, so the totals are comparable across the\
> fiat currencies you trade in and do not move with today's FX. \`total\_orders\` equals\
> \`pagination.total\_count\` of \`GET /partner/orders\` with no filter.\
> \
> A delayed settlement (T+1) order counts as completed — in \`completed\_orders\`, \`volume\_usd\`\
> and \`earned\_usd\` — only once its payment is recorded paid\
> (\`delayed\_settlement\_fiat\_paid\_to\_customer\_at\`), the rule the \`completed\` filter of\
> \`GET /partner/orders\` applies. Released but unpaid, returned, or refunded after the release,\
> it is not counted.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order management, status tracking, and lifecycle actions"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"PartnerStatsResponse":{"type":"object","properties":{"total_orders":{"type":"integer","description":"Every order you have, including ones no liquidity provider accepted yet."},"completed_orders":{"type":"integer","description":"Orders whose crypto was released or is being released. A delayed settlement (T+1) order counts only once its payment is recorded paid."},"volume_usd":{"type":"number","description":"Fiat volume of completed orders, in USD at each order's snapshotted rate."},"earned_usd":{"type":"number","description":"Your markup captured on completed orders, in USD."}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/stats":{"get":{"tags":["Orders"],"summary":"Order stats","description":"Headline numbers for your whole order history in one call: how many orders you have, how many\ncompleted, and the fiat volume and markup earned on the completed ones. This is what the partner\ndashboard tiles show.\n\nVolume and earnings cover **completed** orders only and are reported in **USD**, each order\nconverted at the rate snapshotted when it was created, so the totals are comparable across the\nfiat currencies you trade in and do not move with today's FX. `total_orders` equals\n`pagination.total_count` of `GET /partner/orders` with no filter.\n\nA delayed settlement (T+1) order counts as completed — in `completed_orders`, `volume_usd`\nand `earned_usd` — only once its payment is recorded paid\n(`delayed_settlement_fiat_paid_to_customer_at`), the rule the `completed` filter of\n`GET /partner/orders` applies. Released but unpaid, returned, or refunded after the release,\nit is not counted.\n","operationId":"getOrderStats","responses":{"200":{"description":"Aggregate order statistics","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/PartnerStatsResponse"}}}}}},"401":{"description":"Unauthorized — invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```
