Statuses

Order status is never a single field. The GET order endpoints return three related blocks.

sequenceDiagram
    participant Buyer as Buyer
    participant Api as Partner_API
    participant Partner as Partner

    Note over Buyer,Partner: Milestone 1 — payment
    Buyer->>Buyer: Pays crypto / PIX
    Partner->>Api: GET /orders/{orderId}
    Api-->>Partner: payment.status Paid

    Note over Buyer,Partner: Milestone 2 — settlement
    Partner->>Api: GET /orders/{orderId}
    Api-->>Partner: settlement.status Settled

    opt Automatic PIX-out enabled
        Note over Partner,Api: Milestone 3 — payout
        Partner->>Api: GET /orders/{orderId}
        Api-->>Partner: settlement.payout.status Completed
    end

Milestone 1 — Payment (buyer paid)

`payment.status`	Meaning
`Awaiting`	Waiting for the buyer deposit / payment
`Paid`	Buyer paid; crypto recognized — safe to close the checkout UI
`Expired`	Payment window expired without a successful payment
`Failed`	Payment failed

Also returned when known: paidAt, crypto currency / blockchain / amount, expiresAt.

Milestone 2 — Settlement (BRZ on your Ultra account)

`settlement.status`	Meaning
`Pending`	Not yet settled to BRZ
`Settled`	BRZ credited to your Ultra account — typical trigger to release delivery
`Failed`	Settlement failed

settlement.tradeId mirrors the trade id from /payment when an OTC trade exists.

Milestone 3 — Payout (automatic PIX to your bank)

Only relevant when automatic withdrawal is enabled for your account.

`settlement.payout.status`	Meaning
`NotApplicable`	No automatic PIX-out for this order
`Pending`	Automatic withdrawal in progress (or about to start after settle)
`Completed`	PIX-out to your bank completed
`Failed`	Reserved; not mapped in the current API

Conservative partners may wait for payout.status = Completed before releasing goods.

Withdrawal status

`status`	Meaning
`Pending`	Accepted / queued
`Processing`	In flight at the payment rail
`Completed`	PIX settled
`Failed`	Failed
`Cancelled`	Cancelled
`Rejected`	Rejected (e.g. clear Ultra reject)

Do not treat payment.status = Paid as “funds in your account”. Wait for settlement.status = Settled (or payout completed, if that is your policy).