Lock por usuário e tipo

A BlendFi limita cada cliente final a uma conversão aberta por tipo (pix_onramp ou pix_offramp) por vez. Tentar criar uma segunda conversão onramp para o mesmo cliente final enquanto a primeira está aberta retorna erro.

A regra

Para qualquer (user_id, transaction_type), no máximo uma conversão pode estar nos estados abertos: awaiting_deposit (e, no offramp, também partially_funded e standby).

A regra é cross-direction permissiva: o mesmo cliente final pode ter uma onramp aberta e uma offramp aberta simultaneamente, mas não duas do mesmo tipo.

Por que essa regra existe

Cada conversão onramp tem um QR Pix dedicado, com um identificador único de transação Pix (pix_tx_id) registrado no provedor. Permitir duas conversões onramp abertas para o mesmo cliente final criaria QRs concorrentes que poderiam ser pagos fora de ordem ou ambos. A regra elimina a ambiguidade na origem.

Quando o lock libera

O lock é liberado assim que a conversão entra em estado terminal:

• completed, failed, expired, canceled.

O erro que você recebe

Tentar POST /v1/quotes/:id/accept para um user_id que já tem uma conversão onramp aberta retorna um erro com código estável (a especificação completa vai na referência da API). O request_id no erro permite rastrear a chamada no suporte.

Tratamento sugerido

Quando você recebe o erro de lock:

1. Cheque se a conversão aberta é deste mesmo fluxo. Se for o mesmo cliente final tentando re-confirmar uma operação que ainda está válida, leve a UX de volta ao QR Pix da conversão existente.
2. Se a conversão aberta é antiga e o cliente final desistiu, cancele a anterior (se ainda em awaiting_deposit) ou aguarde a janela de 15 minutos expirar (expired). A nova chamada de aceite passa em seguida.

Próximos passos

• Cancelamento: como liberar o lock antes do pagamento chegar.