Estados da transação

Uma transação da Lootfy percorre dois caminhos independentes: o do pagamento — o comprador pagou? — e o da entrega — o servidor entregou o item? Desde 2026-09-09 esses dois caminhos são campos separados, e não um único status. Entender por que são dois é entender o desenho inteiro: pagar e entregar são responsabilidades de atores diferentes (o comprador e o PSP de um lado, o servidor do outro), acontecem em momentos diferentes e podem falhar por motivos diferentes. Um valor único misturaria os três eixos e apagaria estado — foi exatamente o que motivou a separação.

Para o dono de servidor: pense em dois semáforos, não um. O primeiro diz se o dinheiro chegou; o segundo, se o item saiu. Uma venda só está de fato concluída quando os dois estão no verde e o relógio de liberação marcou.

O texto da message nunca é a fonte do estado

Para saber onde uma transação está, leia os campos paymentStatus, deliveryStatus e completedAt. Nunca deduza estado a partir do texto de uma message — ela é para o humano ler e pode mudar sem aviso.

Os três campos

Uma transação carrega dois enums e um timestamp:

• paymentStatus — onde está o pagamento.
• deliveryStatus — onde está a entrega. É null enquanto o pagamento não foi confirmado: antes de pagar não há o que entregar.
• completedAt — o timestamp de liberação (ISO-8601 UTC), ou null. É o terceiro eixo, o que distingue “item entregue” de “venda liberada”.

O antigo valor CONCLUIDA deixou de existir como estado. Ele agora é uma conjunção que o cliente deriva:

CONCLUIDA  ≡  deliveryStatus === 'ENTREGUE'  &&  completedAt != null

Eixo do pagamento — paymentStatus

Valor	Significado
AGUARDANDO	Transação criada, o comprador ainda não pagou. É onde ela nasce.
PENDENTE	A cobrança Pix foi emitida; aguardando a confirmação do pagamento.
PAGO	Pagamento confirmado. A partir daqui existe entrega — deliveryStatus deixa de ser null.
EXPIRADO	O prazo do pedido venceu sem pagamento.
CANCELADO	A transação foi cancelada.
ESTORNADO	O valor pago foi devolvido ao comprador.

Eixo da entrega — deliveryStatus

Valor	Significado
null	Ainda não há entrega — o pagamento não foi confirmado.
AGUARDANDO_SERVIDOR	Pago; a Lootfy aguarda o servidor transferir o item.
ENTREGUE	O servidor confirmou a entrega (POST /v1/api/transactions/{transactionId}/delivery). Com completedAt preenchido, é a venda CONCLUIDA.
FALHOU	O servidor reportou que não conseguiu entregar. OUT_OF_STOCK no reporte de falha de entrega (POST /v1/api/transactions/{transactionId}/delivery-failure) leva a este estado e dispara estorno.
EM_DISPUTA	A entrega não resolveu no prazo e caiu em disputa. Ver a nota abaixo.

EM_DISPUTA por timeout ainda não é automático

O valor EM_DISPUTA existe no contrato, mas o relógio que leva uma entrega parada a ele por timeout ainda não foi construído — não há worker. Na prática, hoje, uma transação cujo servidor nunca responde fica em PAGO / AGUARDANDO_SERVIDOR indefinidamente. Não construa lógica assumindo a transição automática por timeout. Ver Disponível vs planejado.

As transições principais

No eixo do pagamento, o caminho feliz é AGUARDANDO → PENDENTE → PAGO: a transação nasce em AGUARDANDO, vai a PENDENTE quando a cobrança Pix é emitida no checkout e a PAGO quando o provedor de pagamento confirma. Fora do caminho feliz, de AGUARDANDO ela pode ir a EXPIRADO (prazo vencido) ou CANCELADO; e de PAGO pode ir a ESTORNADO quando o valor é devolvido.

No eixo da entrega, tudo começa quando o pagamento é confirmado: no PAGO, o deliveryStatus sai de null para AGUARDANDO_SERVIDOR. Dali, o servidor confirma a entrega e vai a ENTREGUE, ou reporta falha de entrega. A falha tem dois sabores e eles decidem o rumo: OUT_OF_STOCK leva a FALHOU e estorna a transação; TEMPORARY mantém em AGUARDANDO_SERVIDOR e devolve a ordem para a fila, para nova tentativa. O EM_DISPUTA é o destino previsto de uma entrega que não resolve — hoje só alcançável por resolução manual, não por timeout.

Quando a entrega chega a ENTREGUE e o timestamp de liberação é gravado, a venda é CONCLUIDA. Todo estado terminal — CONCLUIDA, ESTORNADA, EXPIRADA, CANCELADA — dispara o webhook de estado terminal (evento transaction_terminal), para o servidor destravar o item; o parceiro deriva o terminal do par paymentStatus + deliveryStatus, não de um campo status (que não existe mais).

O que o servidor confirma é a verdade da entrega

A entrega é tudo ou nada: o servidor entrega a quantidade inteira ou reporta falha, e o estorno é total — não existe entrega parcial. Nenhum valor é sacável antes de a entrega chegar a ENTREGUE e a venda ser liberada; até lá o split fica retido, mesmo com o pagamento já confirmado.

Como o seu servidor lê esses estados

Do lado da integração, você acompanha os dois eixos por duas vias: o webhook transaction_terminal, que a plataforma dispara quando a transação chega a um desfecho, e a consulta GET /v1/api/transactions/{transactionId}, que devolve o par paymentStatus + deliveryStatus a qualquer momento. O comprador vê os mesmos estados no checkout web, mas isso é da tela da Lootfy — não é uma superfície que o seu servidor lê.

Endpoints e status As rotas que produzem e leem esses estados: transações, entrega e webhooks.

Disponível vs planejado O que ainda não move sozinho: timeout de entrega, jobs de expiração, disputa.