Anúncio, transação e checkout

Quase tudo na Lootfy gira em torno de três objetos que se sucedem: um anúncio, uma transação e um checkout. Entender como um vira o outro é o mapa mental que sustenta o resto da integração. Esta página explica cada um em linguagem acessível e depois desce ao detalhe técnico de quem vai implementar.

Em uma frase: o vendedor publica um anúncio no mercado do jogo, alguém compra uma quantidade e nasce uma transação, e essa transação tem uma página web de pagamento — o checkout — endereçada por um código opaco. O preço nunca viaja na compra: ele já é registro da Lootfy desde o anúncio.

O anúncio (listing)

O anúncio é o item colocado à venda no mercado do jogo, registrado na Lootfy no exato instante em que o vendedor o publica. Ele carrega o item, a descrição (atributos), a quantidade anunciada, o valor unitário e o personagem vendedor. É o anúncio que torna o preço um registro nosso — e não um dado que chega junto com a compra. Esse é o detalhe que dá segurança ao modelo: quando um comprador aparece, a Lootfy já sabe quanto custa, porque o vendedor declarou isso ao anunciar.

O registro do anúncio acontece pela operação de registrar anúncio (POST /v1/api/market/listings) ✅ disponível, transportada pelo client do jogo com um envelope assinado pelo seu servidor. O passo a passo de integração está em Registrar e sincronizar anúncios.

Quantidade e estoque por anúncio

Um item de mercado não é uma instância única: é uma oferta com estoque. O vendedor publica N unidades e cada comprador leva uma fatia. Dois compradores comprando ao mesmo tempo não estão em disputa — os dois podem ser atendidos, desde que haja estoque. O anúncio é a chave pela qual a Lootfy guarda a contabilidade desse estoque, identificado pelo itemRef que o seu servidor fornece. Como a Lootfy estima o que ainda há disponível — e por que essa estimativa só serve para recusar, nunca para autorizar — é o assunto de Estoque estimado.

Atributos: a prova do que foi prometido

Todo anúncio carrega uma descrição em texto livre, com até 255 caracteres. Ela é a prova do que foi prometido ao comprador: os atributos do item exatamente como o client do jogo os montou. Desde 2026-08-20 esse campo é uma string — não é mais um mapa de chave-valor.

Não invente estrutura no texto de atributos

O texto de atributos é livre e vem montado pelo client do jogo. Renderize-o como um parágrafo e não invente um separador para quebrá-lo em pares chave-valor: o formato não é garantido e varia de jogo para jogo. Trate-o como prosa que descreve o item.

As três pré-condições do vendedor

Um anúncio só nasce se o vendedor cumprir as três condições ao mesmo tempo. É o último instante em que ainda dá para impedir que um item apareça no mercado sem um destino para o dinheiro.

Conta Lootfy

O vendedor precisa ter uma conta na plataforma.

Personagem vinculado

O personagem que anuncia precisa estar vinculado a essa conta. Ver vincular um personagem.

Recebedor aprovado

O vendedor precisa ter um recebedor aprovado no provedor de pagamento — é o que o torna, de fato, um vendedor. Ver custódia, split e carteira.

Se algum dos três faltar, o registro do anúncio recusa e diz qual deles falta. A condição do recebedor é, além disso, revalidada na criação da transação: ela pode ter sido recusada ou aposentada no intervalo entre anunciar e vender.

A transação

A transação é a venda de uma quantidade escolhida pelo comprador dentro de um anúncio. Ela nasce sempre no seu servidor, nunca é criada manualmente pela Lootfy. Quando um comprador escolhe no mercado a quantidade que quer, o seu servidor emite uma oferta de compra assinada e o client do jogo a transporta até a API pela operação de criar transação (POST /v1/api/transactions) ✅ disponível. A Lootfy valida a assinatura, calcula o total, cria a transação e devolve um transaction_id e a URL de checkout.

O ponto crucial está no que a oferta de compra carrega — e no que ela não carrega.

A oferta de compra não carrega preço

O envelope da compra transporta apenas três coisas: itemRef (o anúncio), quantity (a quantidade escolhida) e buyerCharacterRef (o personagem comprador). Preço, item e atributos não viajam. Eles já são registro da Lootfy desde o anúncio, e é a Lootfy quem calcula o total, multiplicando o valor unitário do anúncio pela quantidade. Aceitar preço de fora seria confiar num dado que passou pela máquina do jogador — e a máquina do jogador nunca é autoridade.

Todos os valores monetários são inteiros, em centavos. Um item de R$ 12,50 tem valor unitário 1250.

Por que o total é calculado pela plataforma

O client do jogo roda na máquina do jogador, que é um ambiente hostil. A assinatura do seu servidor prova quem assinou, não que o conteúdo assinado é verdade. Se o preço viajasse na compra e o client pudesse influenciá-lo, uma oferta de “1 centavo” tecnicamente válida passaria em toda checagem. Ao manter o preço como registro nosso, declarado no anúncio, esse vetor simplesmente não existe. A autoridade sobre item, quantidade e preço é sempre do servidor, e a compra só precisa dizer o mínimo que apenas o servidor sabe: qual personagem está comprando.

A criação da transação também é idempotente: o jti do envelope assinado é a chave. Uma segunda chegada do mesmo jti — um retry de rede, por exemplo — devolve a mesma transação e o mesmo handle de checkout, nunca cria uma segunda. Esse comportamento e sua contraparte de segurança estão em segurança: assinatura e idempotência.

O checkout

O checkout é a página web onde o comprador confere o que está comprando e paga via Pix. Quando a transação nasce, a Lootfy devolve a URL dessa página. O comprador a abre no navegador, autenticado na conta dona daquele personagem, revê item, atributos, quantidade e valor, e paga.

O que endereça o checkout não é o id da transação — é um handle opaco de 32 bytes.

handle ≠ id

A transação tem um transaction_id interno e um handle de checkout, e eles são coisas diferentes de propósito. O handle é um código opaco de 32 bytes, sem relação adivinhável com o id: ele existe justamente para que a URL de pagamento não exponha nem seja enumerável a partir do identificador da transação. É pelo handle que a página de checkout é endereçada.

O checkout é privado: exige a sessão da conta dona do personagem comprador. Como é a tela da própria Lootfy, o seu servidor não a constrói nem a consulta — ele só produz a URL e recebe o resultado do pagamento pelo webhook. O que acontece nessa página, do seu ponto de vista, está em Checkout e pagamento.

Como um vira o outro

1. Anúncio — o vendedor publica no mercado do jogo. O servidor assina, o client transporta (registrar anúncio), a Lootfy registra o anúncio com item, atributos, quantidade e valor unitário. Preço passa a ser registro nosso.

2. Transação — o comprador escolhe uma quantidade. O servidor assina a oferta de compra (só itemRef + quantity + buyerCharacterRef), o client transporta (criar transação), a Lootfy calcula o total e cria a transação.

3. Checkout — a Lootfy devolve a URL com o handle opaco. O comprador abre, autentica, confere e paga via Pix.

A partir do pagamento, a transação entra no seu ciclo de vida — pago, entregue, concluído — que é o assunto da próxima página.

Próximo: entrega e ciclo de vida O que acontece com a transação depois do pagamento, no modelo de dois eixos de status.