Ciclo de vida da transação

Uma transação BlendFi movimenta dinheiro em três passos: seu usuário final paga BRL via Pix, a BlendFi compra o equivalente em USDT numa corretora regulada, e o USDT é liquidado on-chain na carteira que você indicou. Este guia mostra cada estado pelo qual a transação passa, quando o dinheiro vira irreversível e o que fazer em cada parada.

O caminho feliz

cotação ──► transação criada ──► pending_payment
                                       │
                                       ▼  (Pix recebido)
                                 payment_received
                                       │
                                       ▼  (corretora preencheu)
                                  buying_crypto
                                       │
                                       ▼  (envio on-chain)
                                  sending_crypto
                                       │
                                       ▼  (minerado)
                                   completed

Cada seta é um evento determinístico. Não tem polling do seu lado — webhooks anunciam cada transição. No sandbox, você dirige esses eventos sozinho com os test helpers.

Três conceitos

Catálogo de estados

Limites de segurança do dinheiro

Andando pelo caminho feliz

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"
}

Modos de falha

Toda falha terminal vem com um failure_reason. As quatro que você realmente vai encontrar:

Se você ver um estado failed sem failure_reason, trate como internal_error — abra um ticket com o ID da transação.

Dirigindo a máquina de estados no sandbox

O sandbox não aceita pagamentos Pix de verdade nem fala com uma corretora real. Em vez disso, ele oferece endpoints test_helpers que mapeiam 1:1 para transições reais de estado, então sua integração vê a mesma sequência de eventos que veria em produção.

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

# Caminho feliz
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

Variantes de falha que você pode simular:

Use isso para validar suas retentativas, exibição de erros e tratamento de estorno antes de tocar em produção.

Webhooks vs polling

Para confiabilidade nível parceiro, registre uma URL de webhook. A gente faz POST de cada transição de estado nela com o corpo completo da transação e um cabeçalho assinado que você pode verificar.

Se um webhook estiver indisponível, a BlendFi tenta de novo com backoff exponencial (1m → 1h → 6h → 24h). Você também pode chamar GET /v1/transactions/{id} a qualquer momento para ler o estado canônico — não tem penalidade de rate-limit para polling de "já terminou?" dentro de limites razoáveis.

O que ler em seguida

FAQ

Quanto tempo as cotações duram? TTL padrão é 30 segundos. O expires_at exato vem na resposta da cotação — não hardcode 30s, leia o campo.

E se o usuário final pagar atrasado, depois da expiração do Pix? A transação já está expired. O banco do Pix devolve o pagamento atrasado. A gente não cria uma transação nova automaticamente.

Posso cancelar uma transação pending_payment antes do usuário pagar? Pode. POST /v1/transactions/{id}/cancel (com chave de idempotência) move ela para cancelled. Depois que o Pix chega, cancelar exige fluxo de estorno.

E se a rede on-chain estiver congestionada e a transferência demorar horas? O estado fica em sending_crypto. A gente retenta com gas mais alto se a transação original ficar travada. Não damos timeout em failed por congestionamento — só por revert explícito ou erro de RPC.

Preenchimentos parciais são possíveis na corretora? Não. A gente só aceita preenchimentos all-or-nothing. Um preenchimento parcial é tratado como rejeição e a transação vai para failed com failure_reason: exchange_rejected.

Por que existe um payment_received separado e um buying_crypto, em vez de ir direto de um para o outro? Os dois eventos têm latências diferentes. Pix geralmente liquida em menos de 10 segundos; a ordem na corretora pode levar até um minuto em dias movimentados. Expor separados deixa sua UI mostrar "recebemos seu pagamento, agora convertendo…" — parceiros nos dizem que os usuários finais preferem isso a um spinner ambíguo.