Flows

Receive (swap order)

Typical sequence for accepting a crypto payment that settles to BRZ in your Ultra account:

1. GET /payment-methods — list enabled currency / blockchain pairs.
2. POST /orders — create the order with your externalId (idempotent per partner).
3. POST /orders/{orderId}/preview (optional) — indicative crypto amount only; not binding.
4. POST /orders/{orderId}/payment — binding amount, deposit address / QR. Persist tradeId when present (non-BRZ).
5. GET /orders/{orderId} or GET /orders/by-external-id/{externalId} — poll status (see Statuses).

Idempotency: repeating POST /orders with the same externalId returns the existing order.

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

    Partner->>Api: GET /payment-methods
    Api-->>Partner: currencies and blockchains

    Partner->>Api: POST /orders (externalId)
    Api-->>Partner: orderId

    opt Optional preview
        Partner->>Api: POST /orders/{orderId}/preview
        Api-->>Partner: estimatedCryptoAmount
    end

    Partner->>Api: POST /orders/{orderId}/payment
    Api-->>Partner: QR, address, amount, tradeId?

    Partner->>Buyer: Show QR / deposit address
    Buyer->>Buyer: Pays crypto

    loop Poll 5-10s until Paid
        Partner->>Api: GET /orders/{orderId}
        Api-->>Partner: payment.status
    end

    Note over Partner,Api: After Paid — webhook or slow poll,<br/>then GET until Settled
    Partner->>Api: GET /orders/{orderId}
    Api-->>Partner: settlement.status Settled

Withdraw (PIX out)

Withdrawals always go to your pre-configured PIX key (not supplied in the request body).

1. GET /balance — available Ultra BRZ.
2. POST /withdrawals — amount + externalId (+ optional description). Idempotent on externalId.
3. GET /withdrawals/{id} or GET /withdrawals/by-external-id/{externalId} — poll status.

sequenceDiagram
    participant Partner as Partner
    participant Api as Partner_API

    Partner->>Api: GET /balance
    Api-->>Partner: available BRZ

    Partner->>Api: POST /withdrawals (amount, externalId)
    Api-->>Partner: withdrawalId, status Pending

    loop Until terminal status
        Partner->>Api: GET /withdrawals/{id}
        Api-->>Partner: status Pending|Processing|Completed|...
    end

    Note over Partner,Api: Prefer Ultra webhook,<br/>then reconcile with GET

Suggested client behaviour

• While the buyer is on the checkout screen, poll order status every 5–10 seconds until payment.status leaves Awaiting.
• After payment, prefer Ultra webhooks (see Webhooks) and reconcile with a status GET; use slower polling only as a fallback.
• Prefer Postman (partner-api.postman_collection.json) for authenticated staging calls if browser Try-it-out hits CORS limits.