> 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/basics/how-it-works.md).

# How it works

This section explains the runtime behavior around the API, especially the parts you rely on operationally: webhooks, order progression, and production readiness.

## How the Unigox flow works

Every product on this API shares the same four broad stages:

1. One-time setup
2. Your user onboarding
3. Per-order execution
4. Monitoring and reconciliation

What changes between products is stage 3 — who pays whom, and which side you confirm. The API reference pages provide payload definitions. This page explains how those pieces behave together.

## Off-ramp order lifecycle

Your customer sells crypto and receives fiat. The normal lifecycle is:

1. Quote
2. Initiate offramp
3. Authorize your crypto transfer
4. Wait for payment proof and review from counterparty
5. You confirm that fiat was received
6. Completed

Important status checkpoints:

* `awaiting_crypto_transfer_authorization`
* `crypto_received`
* `fiat_payment_started`
* `fiat_payment_review_started`
* `awaiting_fiat_received_confirmation`
* `completed`

Alternative terminal paths can include:

* `cancelled`
* `failed`
* `dispute_started`

For the actual order actions and state fields, see [Orders](https://developers.unigox.com/api-reference/orders). For the full phased flow, see the [Off-Ramp Partner Playbook](https://developers.unigox.com/tutorials/off-ramp-playbook).

## On-ramp order lifecycle

Your customer buys crypto and pays fiat. The direction reverses: a vendor funds escrow first, your customer pays that vendor, and you confirm the payment was sent.

1. Quote
2. Initiate onramp
3. Vendor funds escrow
4. Your customer pays the vendor's fiat payment details
5. You confirm payment sent
6. Completed

Important status checkpoints:

* `awaiting_vendor_escrow_funding`
* `awaiting_fiat_transfer`
* `fiat_transfer_pending`
* `completed`

Once the order reaches `awaiting_fiat_transfer`, read the vendor's payment details from `GET /api/v1/partner/orders/{order_id}` and forward them to your customer. On the `payment_request` flow you also submit payer details before confirming.

For the full phased flow, see the [On-Ramp Partner Playbook](https://developers.unigox.com/tutorials/on-ramp-playbook).

## Third-party payouts

A variant of off-ramp: your KYC-verified customer sends money to someone else. The customer is the sender, and a separate recipient is paid.

Two things differ from a normal off-ramp:

* **You pre-fund.** Payouts draw down your own partner wallet balance, not your customer's — so an empty balance stops every payout, not just the next one.
* **The recipient is a first-class record.** You register a recipient identity and a validated payout destination before quoting, and every order is screened on relationship, purpose and velocity.

See [Third-party payouts](https://developers.unigox.com/tutorials/third-party-payouts).

## Fiat accounts

An optional product: issue dedicated fiat accounts (IBANs) to your own end customers, then read their balances, ledger and incoming payments.

Every account is reached through the customer that holds it, under `/api/v1/partner/users/{user_uuid}/…`, so there is no second identity to keep in step. Enablement is Unigox-side — until the `retail` product is active on your partner the write endpoints answer `403` and `GET /retail/config` reports `enabled: false`.

See [Fiat accounts](https://developers.unigox.com/tutorials/fiat-accounts).

## Moving to production

Before switching to production:

1. Verify webhook signatures end-to-end.
2. Confirm retries and idempotency behave correctly.
3. Run the happy path and at least one failure or cancellation path.
4. Make sure your reconciliation logic can fall back to polling when needed.