Entrega e ciclo de vida

Depois que o comprador paga, a transação percorre um ciclo de vida até se concluir — ou até falhar e ser estornada. Esta página explica esse ciclo em linguagem acessível e depois detalha o modelo de status que a Lootfy expõe hoje. A ideia central é simples: pagar não é receber, e receber é o que libera o dinheiro. Quem confirma que o item foi entregue é sempre o seu servidor, nunca um clique do comprador.

Dois eixos de status

Uma transação tem duas perguntas independentes: o comprador pagou? e o item foi entregue?. Desde 2026-09-09 a Lootfy responde a cada uma em um eixo próprio, em vez de misturar as duas num único estado linear. São eles:

paymentStatus

O eixo do dinheiro: AGUARDANDO, PENDENTE, PAGO, EXPIRADO, CANCELADO, ESTORNADO.

deliveryStatus

O eixo da entrega: AGUARDANDO_SERVIDOR, ENTREGUE, FALHOU, EM_DISPUTA — ou null antes do pagamento, quando ainda não há o que entregar.

Há ainda um carimbo, completedAt: o instante em que o valor da transação passou a ser sacável. Ele fica vazio até esse momento e, quando preenchido, é uma data ISO-8601 em UTC.

O que significa CONCLUIDA

Uma transação está concluída — no sentido de que o dinheiro do vendedor já pode ser sacado — quando deliveryStatus é ENTREGUE e completedAt não é nulo. Os dois juntos, nunca só um. Entregar o item marca deliveryStatus; tornar o valor sacável marca completedAt, e é esse segundo passo que fecha a transação.

Por que separar os eixos? Porque o antigo enum linear único misturava pagamento, entrega e liberação do dinheiro numa coisa só, e isso escondia estados legítimos — por exemplo, uma transação paga mas ainda não entregue, que é exatamente o estado normal enquanto o seu servidor processa a ordem de transferência.

O caminho feliz

1. Antes de pagar. A transação nasce com paymentStatus: AGUARDANDO e deliveryStatus: null. O checkout está disponível pela URL, mas nenhuma cobrança foi emitida.

2. Cobrança emitida. O comprador confirma no checkout e a cobrança Pix é emitida: paymentStatus: PENDENTE. O gatilho é a emissão da cobrança, não o pagamento — a Lootfy não tem como saber quando o comprador abriu o app do banco.

3. Pago. O provedor de pagamento confirma o Pix: paymentStatus: PAGO. O dinheiro já está dividido entre as partes, porém retido — creditado, mas não sacável. Nesse instante a Lootfy dispara a ordem de transferência ao seu servidor (evento transfer_order, webhook de entrega).

4. Entregue. O seu servidor entrega o item no jogo e confirma pela API — confirmar entrega, POST /v1/api/transactions/{transactionId}/delivery: deliveryStatus: ENTREGUE. Essa confirmação é a fonte da verdade da entrega.

5. Concluída. O valor de cada parte passa a sacável e completedAt é carimbado. Nenhum dinheiro se move nesse instante — o que muda é a elegibilidade ao saque.

Regras que sustentam o ciclo

A entrega é tudo ou nada

O comprador comprou 5 e o seu servidor só tem 3 no momento da entrega. A regra é dura: o servidor não entrega 3. Ele entrega a quantidade inteira ou reporta falha. Não existe entrega parcial de quantidade, e por consequência não existe estorno parcial — o valor bruto ou vale inteiro ou volta inteiro. O comprador recebe o que comprou ou o dinheiro de volta, nunca um meio-negócio que ninguém pediu.

Nada é sacável antes da entrega confirmada

O split é creditado no pagamento — é o que o Pix permite, porque a regra de divisão é fixada na criação da cobrança. Mas o valor fica retido até a entrega: o recebedor é criado sem transferência automática e o ledger marca o valor como não sacável. Só na conclusão (ENTREGUE com completedAt preenchido) a fatia de cada parte se torna sacável. Isso é o que dá segurança ao negócio: o comprador só perde o dinheiro se receber o item, e o vendedor só pode sacar se entregar.

Concluir exige confirmação explícita do servidor

A Lootfy nunca torna um valor sacável automaticamente depois de PAGO. A conclusão exige a confirmação de entrega vinda do seu servidor, pela operação de confirmar entrega. A fonte da verdade da entrega é o servidor — quem detém o item e o estoque —, jamais um clique do comprador dizendo “recebi”.

Quando a entrega falha

O seu servidor reporta falha pela operação de reportar falha de entrega (POST /v1/api/transactions/{transactionId}/delivery-failure) ✅ disponível, e o motivo decide o desfecho. Há dois, e é de propósito: do lado da Lootfy só existem dois comportamentos possíveis, estornar agora ou tentar de novo.

Motivo	O que significa	Desfecho
OUT_OF_STOCK	O item não existe mais para entregar: a moeda do próprio jogo drenou a listagem.	deliveryStatus: FALHOU e estorno automático — devolução Pix integral ao comprador, paymentStatus: ESTORNADO.
TEMPORARY	A entrega ainda pode acontecer (servidor reiniciando, receptor indisponível, erro passageiro).	A transação permanece em PAGO; a ordem de transferência é reenfileirada com backoff. Nada estorna.

O TEMPORARY não tem teto de retentativas, e isso é intencional: um servidor que volta ao ar horas depois deve conseguir entregar. A rede de segurança contra a retentativa eterna não é um limite de tentativas — é o timeout de entrega, descrito a seguir.

Servidor inalcançável não é falha de entrega

Se o seu servidor está fora do ar e não chega a reportar a falha de entrega, não houve reporte de falha. Esse caso é apenas retentativa do webhook: a transação segue em PAGO, sem registro de tentativa do seu lado, até o seu servidor voltar e receber a ordem.

Disputa e timeout

O modelo prevê que uma transação paga que nunca recebe confirmação nem falha vá, por decurso de prazo, para deliveryStatus: EM_DISPUTA — um estado que congela o valor e exige resolução humana de um admin. O timeout de entrega é o único relógio autorizado a tirar a transação de PAGO.

Estado planejado

O job de timeout ainda não está implementado. Na prática, uma transação paga sem resposta do servidor permanece hoje em PAGO / AGUARDANDO_SERVIDOR indefinidamente, aguardando a ordem de transferência ser processada. EM_DISPUTA existe como conceito e como valor do enum, mas não há hoje produtor que leve uma transação até ele automaticamente. Trate-o como comportamento planejado.

Todo estado terminal notifica o seu servidor

Quando uma transação chega a um estado terminal, a Lootfy avisa o seu servidor pelo webhook de estado terminal (evento transaction_terminal) ✅ disponível, para que ele reconcilie o próprio lado. A Lootfy não gerencia o estoque do jogo; a notificação existe para o seu servidor fechar o ciclo dele. Os estados que disparam esse webhook são EXPIRADA, CANCELADA, ESTORNADA e CONCLUIDA.

Próximo: dinheiro, custódia e split Como o valor é dividido entre vendedor, plataforma e servidor, e por que a Lootfy nunca guarda o dinheiro.