API PIX para USDT

Para quem é

• Produto que já vende no Brasil e quer o dinheiro em stablecoin em vez de conta bancária.
• Empresa de fora que precisa aceitar PIX sem abrir conta, CNPJ ou adquirente no país.
• Time que quer trocar um on-ramp atual por um com contrato aberto, sandbox sem cadastro e comprovante verificável.

O problema

Aceitar PIX e ficar com stablecoin normalmente exige três peças que não conversam: uma adquirente para o PIX, uma conta bancária brasileira para o dinheiro parar e uma corretora para converter. Cada uma com seu onboarding, seu limite e sua conciliação — e o dinheiro parado entre elas.

Aqui é uma chamada. O PIX entra, a conversão acontece e a cripto sai para a carteira que você indicou. Não há saldo esperando saque, nem passo manual no meio.

O fluxo, ponta a ponta

1. Você chama POST /cashin/charge com o valor, o ativo, a rede, a sua carteira e o CPF/CNPJ de quem vai pagar.
2. A resposta traz qr_copypaste: é o PIX que você mostra ao cliente. Ele vale 15 minutos.
3. O cliente paga no banco dele. Chega o webhook cashin.paid.
4. A conversão e o envio acontecem sozinhos. Chega cashin.settled com o hash on-chain.
5. Precisou conferir? GET /cashin/{cashin_id}/status traz a linha do tempo carimbada pelo servidor.

Endpoints usados

Exemplo que roda

curl -X POST https://api.luniumpay.com/cashin/charge \
  -H "X-API-Key: $LUNIUM_KEY" -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 25000,
    "asset": "usdt",
    "chain": "polygon",
    "payout_address": "0xSuaCarteira",
    "payer_tax_number": "12345678909",
    "external_id": "pedido-7781"
  }'

const r = await fetch("https://api.luniumpay.com/cashin/charge", {
  method: "POST",
  headers: { "X-API-Key": process.env.LUNIUM_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    amount_cents: 25000,
    asset: "usdt",
    chain: "polygon",
    payout_address: "0xSuaCarteira",
    payer_tax_number: "12345678909",
    external_id: "pedido-7781",
  }),
});
const cobranca = await r.json();
console.log(cobranca.cashin_id, cobranca.qr_copypaste);

import os, requests

r = requests.post(
    "https://api.luniumpay.com/cashin/charge",
    headers={"X-API-Key": os.environ["LUNIUM_KEY"]},
    json={
        "amount_cents": 25000,
        "asset": "usdt",
        "chain": "polygon",
        "payout_address": "0xSuaCarteira",
        "payer_tax_number": "12345678909",
        "external_id": "pedido-7781",
    },
    timeout=30,
)
cobranca = r.json()
print(cobranca["cashin_id"], cobranca["qr_copypaste"])

Sandbox: teste antes de gastar

Uma chamada, sem cadastro, sem cartão. A chave lun_test_ exercita a superfície inteira sem mover dinheiro nenhum.

curl -X POST https://api.luniumpay.com/keys/sandbox \
  -H "Content-Type: application/json" \
  -d '{"name":"meu-teste"}'

O que o sandbox não prova: liquidação real. Nenhuma cripto se move e nenhum PIX é pago — ele serve para acertar o contrato, não para medir o trilho.

Ativos e redes

Instantâneo (trilho próprio): USDT na Polygon e USDC na Polygon — liquidação em segundos, sem corretora no caminho.

Via corretora: 1.478 ativos em 241 redes na venda (1.668 pares ativo×rede) e 1.795 rotas na compra. O prazo é o número de confirmações que a rede exige, não uma escolha nossa.

Redes de endereço compartilhado (ALGO, ATOM, EOS, HBAR, KAVA, LUNA, TON, XLM, XRP): o depósito precisa levar o memo. Na venda ele vem em deposit_tag no aceite; na compra você manda payout_tag junto do endereço.

O catálogo muda sozinho conforme redes entram e saem. Leia de GET /catalog e GET /cashin/catalog em vez de manter lista no código.

Limites e retenções

A escada é por documento de quem paga, não por conta que recebe: dez pagadores são dez limites independentes. É isso que faz o produto servir a e-commerce e marketplace. Consulte o disponível de um pagador antes de cobrar em GET /cashin/limits?payer_tax=, e leia os limites da sua chave em GET /keys/me — tetos acima do tier são contratados.

Medições, não promessas

Medido em produção, janela de 90 dias, em 07/09/2026:

Fora da Polygon o relógio é o da rede: o prazo é o número de confirmações que a corretora exige, e está em eta no catálogo. Não prometemos “instantâneo” fora do trilho próprio.

Idempotência

Mande external_id em toda operação que move dinheiro. Repetir a mesma chamada devolve a mesma operação, nunca uma segunda; os mesmos parâmetros com id diferente criam duas, e o mesmo id com parâmetros diferentes responde 409 external_id_divergente em vez de adivinhar.

Timeout não é recusa. Se a chamada não respondeu, consulte pelo external_id antes de repetir — a operação pode existir.

Webhooks e reconciliação

Cada transição dispara um evento assinado em HMAC SHA-256 com timestamp (header X-Lunium-Signature, formato t=…,v1=…) — o timestamp é o que impede replay de uma entrega capturada. Confira a assinatura antes de confiar no corpo.

Webhook é o sinal principal; polling é opcional. Quando precisar pesquisar, o status traz a timeline carimbada pelo servidor — desenhe a etapa a partir dela, porque o cronômetro do seu polling mede a sua rede, não a operação.

Não respondeu 2xx? A entrega é retentada com backoff. Você reenvia à mão em POST /webhooks/deliveries/{event_id}/retry e testa a sua URL em POST /webhooks/test.

Quando dá errado

O PIX é pago por um documento diferente do informado: a cobrança é devolvida ao pagador e o status traz refund_reason explicando. Nada é entregue com dono errado.

O provedor de liquidação fica fora: POST /cashin/charge responde 502 provedor_indisponivel com acao: "repetir". Nenhuma cobrança é criada nesse caso — repita a mesma chamada com o mesmo external_id.

O cliente não pagou a tempo: a cobrança vira expired e nada acontece. Gere outra.

Segurança

• webhook assinado — Todo webhook vai assinado em HMAC SHA-256 com timestamp (header X-Lunium-Signature, formato t=…,v1=…), o que impede replay de uma entrega capturada.
• idempotencia — external_id em cash-in, cash-out e payout: repetir a mesma chamada devolve a MESMA operação, nunca uma segunda. Parâmetros diferentes no mesmo external_id respondem 409.
• egress validado — A URL de webhook é resolvida e validada antes de cada entrega: endereço interno, metadata de nuvem e redirect para rede privada são recusados, e a conexão é fixada no IP validado.
• retencao fail closed — A retenção é verificada na liquidação e repetida na reivindicação SQL: nenhum caminho (worker, consulta de status, fila) consegue liquidar antes da hora.
• payout duravel — O saque grava a operação e debita o saldo na MESMA transação, antes de qualquer chamada ao provedor: não existe débito sem ordem para reconciliar.
• verificacao aberta — GET /v1/verificar/{e2e} confere um PIX liquidado sem chave nenhuma — a contraparte não precisa confiar na nossa palavra.

A verificação aberta é a que mais importa numa negociação: a sua contraparte confere o PIX sozinha, sem chave e sem depender da nossa palavra.

Tempo até a primeira integração

Do zero ao primeiro QR: uma chamada para a chave de sandbox e outra para a cobrança. Os integradores que chegaram por busca fizeram isso em minutos, sem falar com ninguém.

Para produção você precisa de uma chave de produção e de uma URL de webhook. O resto do código não muda: o sandbox usa o mesmo contrato, os mesmos campos e os mesmos erros.

Perguntas que os integradores fazem