E-COMMERCE · MARKETPLACE · WALLET

Como receber PIX de múltiplos pagadores e liquidar em stablecoin

Crie uma cobrança por pedido, nunca um QR genérico. Relacione seu external_id ao pedido, informe o CPF/CNPJ do pagador, consulte a faixa disponível antes de mostrar o PIX e confirme pelo webhook. A liquidação pode seguir para uma carteira ou para saldo/subconta, conforme o produto.
1 cobrança por pedidoCPF/CNPJ do pagadorexternal_idwebhookUSDT · USDC

Modelo de dados mínimo

checkout_order
  id                 // identificador interno
  lunium_external_id // estável e único
  lunium_cashin_id   // devolvido pela API
  payer_tax_hash     // política interna; não envie para analytics
  amount_cents
  status
  expected_release_at
  created_at

Fluxo por pedido

Valide o pagador

Normalize CPF/CNPJ no servidor e consulte GET /cashin/limits?payer_tax=. A régua é individual por documento.

Faça a prévia

Valide valor, ativo, rede e carteira em POST /cashin/preview. Não mostre promessa baseada em cotação calculada localmente.

Crie com identificador único

Envie um external_id derivado do pedido. Em timeout, repita o mesmo payload e identificador.

Mostre QR e expectativa

Se a API indicar retenção, informe antes do pagamento que a liberação ocorrerá depois. Não chame isso de falha.

Confirme e concilie

Webhook atualiza o pedido. Consulta de status e histórico de entregas recuperam qualquer lacuna operacional.

Duas arquiteturas possíveis

Liquidação direta

Cada cobrança informa payout_address; a stablecoin segue para a carteira configurada para aquele pedido.

Saldo e subcontas

Com destino: saldo e customer_ref, o crédito é separado por cliente e usado depois nos trilhos permitidos.

Erros que custam dinheiro

QR reutilizado: perde a relação um pedido ↔ uma cobrança e dificulta identificar valor, pagador e devolução.
Retry com novo external_id: transforma dúvida de rede em uma segunda cobrança.
Limite fixo no código: fica desatualizado. Leia /keys/me e /cashin/limits.
Estado persistido: salve os identificadores antes de renderizar o QR e antes de confirmar o pedido no seu sistema.

Checklist de homologação

Conciliação

Pedido interno, external_id e cashin_id ligados e pesquisáveis.

Privacidade

CPF/CNPJ não vai para analytics, URL, ferramenta de sessão ou log de aplicação.

Experiência

O comprador vê valor, prazo, expiração e eventual retenção antes de pagar.

Suporte

request_id e identificadores técnicos bastam; nunca envie chave da API.

Valide o seu checkout antes de migrar clientes

No cash-in sandbox, valide autenticação, catálogo, limites, prévia e webhook sem dinheiro. O QR pagável e os estados reais da cobrança exigem chave de produção e um primeiro teste controlado.

Testar integraçãoFalar do meu caso