Criar e acompanhar transações

Quando um comprador escolhe um anúncio no jogo, o seu servidor assina uma oferta de compra e a plataforma cria uma transação. A transação é o pedido: ela nasce aguardando pagamento, ganha uma URL de checkout que o comprador abre no navegador, e a partir daí evolui por dois eixos de estado. Esta página cobre criar a transação (POST /v1/api/transactions) e consultá-la (GET /v1/api/transactions/{transactionId}).

Para o dono de servidor: a oferta de compra é magra de propósito. Ela diz apenas “este personagem quer esta quantidade deste anúncio” — o preço a Lootfy já conhece, do anúncio. Assim, nada que venha da máquina do jogador consegue alterar o valor cobrado.

Criar a transação ✅ disponível

Esta é a segunda rota signature-only: é transportada pelo client do jogo, então leva só a assinatura JWS, sem API key.

POST /v1/api/transactions
X-Lootfy-Signature: <protegido>..<assinatura>
Content-Type: application/json

{ "itemRef": "srv-offer-9931", "quantity": 2, "buyerCharacterRef": "char-123" }

// 200
{ "data": {
    "transactionId": 42,
    "paymentStatus": "AGUARDANDO",
    "deliveryStatus": null,
    "checkoutUrl": "https://api.lootfy.gg/checkout/uwMT4PfQ2B-TjbWXMukbLJOzcaQO",
    "quantity": 2,
    "unitAmountCents": 7000,
    "totalAmountCents": 14000,
    "expiresAt": "2026-09-14T12:30:00.000Z"
} }

O corpo carrega só três campos, e é intencional: o anúncio (itemRef), a quantidade e o personagem comprador. O preço não viaja. A plataforma multiplica o unitAmountCents do anúncio pela quantidade e devolve unitAmountCents, totalAmountCents e a checkoutUrl.

Abra a checkoutUrl no navegador do jogador. O prazo do pedido é o expiresAt (padrão 30 minutos); vencido, o jogador refaz a compra no jogo.

Os dois eixos de status

A transação carrega dois campos de estado, não um. O paymentStatus diz onde está o pagamento (AGUARDANDO | PENDENTE | PAGO | EXPIRADO | CANCELADO | ESTORNADO); o deliveryStatus diz onde está a entrega (AGUARDANDO_SERVIDOR | ENTREGUE | FALHOU | EM_DISPUTA), ou null enquanto o pagamento não foi confirmado — não há o que entregar antes de pagar. Recém-criada, a transação nasce AGUARDANDO / null. Os estados completos estão em Estados da transação.

jti é chave de idempotência aqui

Como em registrar anúncio, esta rota é transportada pelo client, então o jti é chave de idempotência: a segunda chegada do mesmo jti devolve a mesma transação e o mesmo handle, nunca uma segunda cobrança. É o que torna seguro o retry de rede da máquina do jogador. Detalhe em Assinatura JWS na prática.

Quando a criação é recusada

A plataforma revalida tudo no momento da compra — nada é herdado do anúncio. A transação é recusada, com 400 e a message já em pt-BR, quando:

• a assinatura é inválida ou o exp está vencido;
• o anúncio não existe, não está ativo, ou não é daquele servidor;
• o personagem comprador não está vinculado a uma conta Lootfy;
• o comprador ou o vendedor está banido;
• o recebedor do vendedor não está aprovado no PSP no instante da compra — revalidado, não herdado do anúncio;
• a quantidade excede o disponível estimado do anúncio (estimativa velha não recusa);
• o total fica abaixo do valor mínimo daquele servidor (padrão R$ 0,50). O mínimo incide sobre o total, não sobre o unitário: item barato continua vendável em quantidade.

O estoque estimado não é promessa de entrega

A checagem de quantidade recusa uma compra obviamente grande demais, mas não reserva nada — a plataforma não gerencia estoque. Quem arbitra quem leva o item, quando a moeda do jogo consumiu a mesma listagem, é o seu servidor na entrega. Uma compra que passou aqui ainda pode falhar na entrega e virar estorno; é caminho previsto, não exceção. Ver Estoque estimado.

Consultar a transação ✅ disponível

Consulta idempotente do estado atual do pedido. É uma rota service (API key + JWS).

GET /v1/api/transactions/42
X-Service-Api-Key: <sua-api-key>
X-Lootfy-Signature: <protegido>..<assinatura>

// 200
{ "data": {
    "transactionId": 42,
    "paymentStatus": "PAGO",
    "deliveryStatus": "AGUARDANDO_SERVIDOR",
    "itemRef": "srv-offer-9931",
    "gameItemId": "bow-9",
    "quantity": 2,
    "unitAmountCents": 7000,
    "totalAmountCents": 14000,
    "expiresAt": "2026-09-14T12:30:00.000Z",
    "createdAt": "2026-09-14T12:00:00.000Z",
    "updatedAt": "2026-09-14T12:05:00.000Z"
} }

Esta é a rota que resolve a única corrida que o desenho admite: use-a antes de transferir o item quando a ordem de transferência (webhook transfer_order) chegou com atraso, ou quando você não tem certeza de que a transação ainda vale. É a fonte confiável do estado no momento da consulta. Detalhe dessa corrida em Webhook e entrega.

Como é uma rota service, o jti é nonce — gere um novo a cada consulta.

O que não existe: cancelar transação (planejado)

O contrato previa uma rota para o servidor cancelar um pedido ainda não pago. Ela não foi implementada, e não bloqueia o ciclo. Não há como você cancelar do seu lado um pedido pendente; ele expira sozinho pelo prazo (expiresAt, 30 minutos por padrão). Um pedido vencido deixa de ser pagável, e o comprador simplesmente refaz a compra no jogo. Não há ação sua a tomar.

Próximo: checkout e pagamento O que acontece quando o comprador abre a checkoutUrl e paga o Pix.