Transaction lifecycle

A BlendFi transaction moves money in three steps: your end user pays BRL via Pix, BlendFi buys the equivalent USDT on a regulated exchange, and the USDT is settled on-chain to the wallet you specified. This guide shows every state the transaction passes through, when money is irreversible, and what to do at each stop.

The happy path

quote ──► transaction created ──► pending_payment
                                        │
                                        ▼  (Pix received)
                                  payment_received
                                        │
                                        ▼  (exchange filled)
                                   buying_crypto
                                        │
                                        ▼  (on-chain submit)
                                   sending_crypto
                                        │
                                        ▼  (mined)
                                    completed

Each arrow is a deterministic event. There is no polling required from your side — webhook callbacks announce every transition. In sandbox, you drive these events yourself with the test helpers.

Three concepts

State catalogue

Money safety boundaries

Walking the happy path

curl -X POST $BLENDFI_BASE/v1/quotes \
  -H "Authorization: Bearer $BLENDFI_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "user_id": "01J...",
    "source_amount": "100.00",
    "source_currency": "BRL",
    "target_currency": "USDT",
    "destination_wallet_address": "0xabc...",
    "destination_wallet_network": "polygon"
  }'

{
  "id": "01JQ...",
  "rate": "5.42",
  "source_amount": "100.00",
  "target_amount": "18.4502",
  "expires_at": "2026-04-29T13:00:30Z"
}

curl -X POST $BLENDFI_BASE/v1/transactions \
  -H "Authorization: Bearer $BLENDFI_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{"quote_id": "01JQ..."}'

{
  "id": "01JT...",
  "status": "pending_payment",
  "pix_qr_code": "00020126...",
  "pix_copy_paste": "...",
  "expires_at": "2026-04-29T13:30:00Z"
}

{
  "id": "01JT...",
  "status": "payment_received",
  "paid_at": "2026-04-29T13:04:12Z",
  ...
}

{
  "id": "01JT...",
  "status": "completed",
  "usdt_tx_hash": "0xabc123...",
  "completed_at": "2026-04-29T13:08:05Z"
}

Failure modes

Every terminal failure is announced with a failure_reason. The four you'll actually encounter:

If you ever see a failed state without a failure_reason, treat it as internal_error — file a ticket with the transaction ID.

Driving the state machine in sandbox

Sandbox doesn't actually accept Pix payments or talk to a real exchange. Instead, it gives you test_helpers endpoints that map 1:1 to real state transitions, so your integration sees the same event sequence it will see in production.

TXID=01JT...
H='-H "Authorization: Bearer $BLENDFI_KEY"'
I='-H "Idempotency-Key: $(uuidgen)"'

# Drive the happy path
curl -X POST $BLENDFI_BASE/v1/test_helpers/transactions/$TXID/pay $H $I
curl -X POST $BLENDFI_BASE/v1/test_helpers/transactions/$TXID/fill-hedge $H $I
curl -X POST $BLENDFI_BASE/v1/test_helpers/transactions/$TXID/send-crypto $H $I
curl -X POST $BLENDFI_BASE/v1/test_helpers/transactions/$TXID/confirm-crypto $H $I

Failure variants you can simulate:

Use these to validate your retry, error display, and refund handling before you touch production.

Webhooks vs polling

For partner-grade reliability, register a webhook URL. We POST every state transition to it with the full transaction body and a signed header you can verify.

If a webhook is unreachable, BlendFi retries with exponential backoff (1m → 1h → 6h → 24h). You can also call GET /v1/transactions/{id} at any time to read the canonical state — there is no rate-limit penalty for "is it done yet?" polling within reasonable bounds.

What to read next

FAQ

How long do quotes last? Default TTL is 30 seconds. The exact expires_at is in the quote response — don't hard-code 30s, read the field.

What if the end user pays late, after the Pix expiration? The transaction is already expired. The Pix bank reverses the late payment. We do not auto-create a new transaction.

Can I cancel a pending_payment transaction before the user pays? Yes. POST /v1/transactions/{id}/cancel (with an idempotency key) moves it to cancelled. After the Pix arrives, cancellation requires a refund flow.

What happens if the on-chain network is congested and the transfer takes hours? The state stays sending_crypto. We retry with bumped gas if the original transaction is stuck. We don't time out into failed from chain congestion alone — only from explicit revert or RPC error.

Are partial fills possible on the exchange? No. We only accept all-or-nothing fills. A partial fill is treated as a rejection and the transaction moves to failed with failure_reason: exchange_rejected.

Why is there a separate payment_received and buying_crypto instead of going straight from one to the other? The two events have different latency profiles. Pix usually settles in under 10 seconds; the exchange order can take up to a minute on busy days. Exposing them separately lets your UI show "received your payment, now converting…" — partners say their end users prefer this over a single ambiguous spinner.