Conversão
Entidade central do onramp. Representa a operação do aceite da cotação até a liquidação on-chain. Lista de estados.
Conversão (conversion) é a entidade central do onramp. Ela existe a partir do aceite da cotação e atravessa o ciclo até a liquidação on-chain ou um desfecho terminal alternativo. É o recurso que você lê (GET /v1/conversions/:id) e aciona (/cancel).
Por que conversão é separada da cotação
Cotação e conversão respondem a perguntas diferentes:
- Cotação responde: "qual a taxa agora?". Preço congelado, descartável, sem efeito colateral.
- Conversão responde: "qual operação está em andamento, em que estado?". Operação executável, com QR Pix, janela, reserva de limite e máquina de estados.
Separar evita que cotações descartadas poluam o histórico de operações reais e mantém a máquina de estados enxuta.
Diagrama de estados
Estados, um a um
| Estado | O que significa | O que você está esperando | Ações disponíveis |
|---|---|---|---|
awaiting_deposit | Conversão criada, QR Pix emitido, janela de 15 minutos rodando | O cliente final pagar o Pix | cancel |
funded | Pagamento Pix confirmado dentro da janela | A liquidação on-chain avançar automaticamente | (nenhuma) |
completed | USDT entregue no endereço de destino. Terminal | (terminal) | (nenhuma) |
failed | Erro irrecuperável após funded. Veja failure_reason. Terminal | (terminal) | (nenhuma) |
expired | Janela passou sem pagamento. Reserva liberada. Terminal | (terminal) | (nenhuma) |
canceled | Você cancelou em awaiting_deposit. Reserva liberada. Terminal | (terminal) | (nenhuma) |
Onramp não tem standby
Diferente do offramp, o onramp não tem standby, liquidated nem abandoned. O Pix é atômico: ou paga o valor exato dentro da janela, ou não paga. Não há divergência de valor pra resolver.
Campos chave
A conversão expõe (entre outros):
id,quote_id,status,transaction_type(pix_onramp).expected_source_amount(o BRL esperado),received_amount(o BRL efetivamente recebido).pix_qr_code,pix_tx_id,deposit_window_expires_at.destination_wallet_address,destination_wallet_network.- Campos de execução populados após a liquidação: hash da transação USDT, timestamps,
failure_reason.
A lista completa vai na referência da API.
Webhooks por transição
| Transição | Evento |
|---|---|
(criação) → awaiting_deposit | conversion.created |
funded → completed | conversion.completed |
funded → failed | conversion.failed |
awaiting_deposit → expired | conversion.expired |
awaiting_deposit → canceled | conversion.canceled |
Não há webhook intermediário para funded. O evento de interesse é o desfecho (completed, failed, expired, canceled).
Próximos passos
- Lock por usuário e tipo: a regra de uma conversão aberta por cliente final.
- Recebendo o pagamento: o que acontece após o cliente final pagar.