Standby e liquidação manual
O que dispara standby, o que `/liquidate` faz, por que a taxa muda, prazo de 7 dias.
Standby é o ponto operacional mais importante do offramp. É o estado em que a conversão está "parada com dinheiro retido", esperando uma decisão sua. Esta página cobre os motivos de standby, como sair via /liquidate, e o desfecho abandoned se você não agir em 7 dias.
O que dispara standby
Qualquer um destes cenários coloca a conversão em standby:
standby_reason | O que aconteceu |
|---|---|
under_funded | O depósito on-chain confirmou com received_amount < expected_source_amount. |
over_funded | O depósito on-chain confirmou com received_amount > expected_source_amount. |
window_expired | A janela de 15 minutos passou com received_amount > 0 mas ainda em awaiting_deposit. |
duplicate_deposit | Mais de um depósito on-chain foi detectado para a mesma conversão. |
wrong_address | Um depósito chegou em um endereço que não corresponde ao emitido para esta conversão. |
late_post_window | Um depósito chegou depois do fechamento da janela, mas ainda foi aceito para resolução. |
Em todos os três, o depósito ficou em custódia da BlendFi e a conversão não vai avançar sozinha. A política é deliberada: qualquer divergência exige uma decisão explícita do parceiro, e a operação não roda em automatico com valor diferente do contratado.
O que você vê
Webhook conversion.standby com payload contendo standby_reason, received_amount, e expected_source_amount. A conversão na resposta de GET /v1/conversions/:id mostra status='standby', standby_at (quando entrou), standby_expires_at (standby_at + 7 dias).
A decisão: liquidar ou esperar
Você tem três caminhos:
- Liquidar pelo valor efetivamente recebido via
POST /v1/conversions/:id/liquidate. A BlendFi cota uma nova taxa server-side, executa a liquidação peloreceived_amount, e a conversão termina emcompleted(caminho feliz) oufailed(erro de execução). - Não fazer nada por até 7 dias. A conversão segue em standby; depósitos tardios continuam sendo creditados em
received_amountmas não promovem a conversão. Após 7 dias, ela viraabandoned(veja Conversão abandonada). - Combinar 1 e 2: segurar enquanto avalia, depois liquidar a qualquer momento dentro do prazo de 7 dias.
O que /liquidate faz
POST /v1/conversions/:id/liquidate é válido apenas em standby. A chamada, em uma única transação:
- Cota uma nova taxa server-side sobre o
received_amountatual (não sobreexpected_source_amount). A nova cotação é registrada comoquote(consumed)e referenciada pela conversão vialiquidation_quote_id. - Ajusta a reserva de limite para o valor efetivo da operação.
- Cria o registro interno de execução e dispara a liquidação do Pix.
- Transita a conversão para
liquidated(transitório); a liquidação subsequente leva paracompletedoufailed.
A resposta carrega a conversão com liquidation_quote_id populado, status liquidated, e os campos de execução já em curso.
A taxa em `/liquidate` é nova, não a original
A taxa aplicada na liquidação manual é cotada no momento da chamada, não a exchange_rate da cotação original. O cliente final pode receber um valor de BRL diferente do mostrado no aceite, especialmente se o ativo se moveu entre o aceite e a sua decisão de liquidar. Considere isso ao desenhar a UX.
Por que a taxa muda
A cotação original valeu por 5 minutos no momento de criação. A janela de depósito durou 15 minutos no aceite. Quando você liquida em standby, o tempo decorrido pode ser horas ou dias. Aplicar a taxa antiga jogaria o risco de mercado integralmente sobre a BlendFi. A política é simétrica: o parceiro que não agiu dentro da janela combinada paga a taxa do momento em que efetivamente decide executar.
Erros comuns no /liquidate
- Conversão fora de
standby: erro de validação. A operação só é aceita em standby. - Limite insuficiente para o
received_amountatualizado: erro de validação. A reserva ajustada não cabe no limite vigente do cliente final.
A taxonomia completa vai na referência da API quando publicada.
TTL de 7 dias e abandoned
standby_expires_at = standby_at + 7 dias. Se você não chamar /liquidate dentro desse prazo, a conversão transita para abandoned. A resolução de abandoned é manual e fora da plataforma. Veja Conversão abandonada.
Sem webhooks de lembrete durante os 7 dias
A BlendFi não envia webhooks de aviso durante a janela de 7 dias. O acompanhamento do prazo é responsabilidade da sua integração. Considere uma rotina de varredura sobre GET /v1/conversions?status=standby se a operação for sensível ao prazo.
Reference em breve
A documentação detalhada de POST /v1/conversions/:id/liquidate vai aparecer aqui em conjunto com a disponibilidade da API.
Próximos passos
- Cancelamento: como sair quando ainda não chegou depósito.
- Conversão abandonada: o que acontece após os 7 dias.