O checkout precisa consultar o status por polling?

Não. Webhooks são o caminho principal; a consulta de status é o fallback para reconciliação.

Como evitar duas cobranças no retry?

Envie um external_id estável. A mesma requisição retorna a operação original; parâmetros diferentes no mesmo identificador retornam conflito.

API PIX → STABLECOIN · GUIA DE INTEGRAÇÃO

Checkout PIX com API REST e webhook para USDT ou USDC

Q: A chave de produção depende de aprovação manual?

Não. A chave de produção é criada pelo endpoint público POST /keys e aparece uma única vez na resposta.

Sim: o fluxo é direto. Sua aplicação cria a cobrança, mostra o PIX copia e cola, acompanha o pagamento por webhook e recebe a liquidação em USDT ou USDC na carteira indicada. A chave de produção é self-service. Para cash-in, a sandbox valida contrato, catálogo, limites e prévia; o QR PIX pagável exige chave de produção.

API RESTWebhook HMAC SHA-256external_id idempotenteUSDT · USDCPolygon e catálogo vivo

Abrir quickstart Revisar meu caso

Fluxo em cinco passos

Crie a chave

Use POST /keys/sandbox para validar o contrato sem dinheiro ou POST /keys para criar sua chave de produção. A chave em claro aparece uma única vez.

Leia catálogo e limites

Consulte GET /cashin/catalog, GET /keys/me e GET /cashin/limits. Não fixe rede, mínimo, máximo ou faixa de retenção no código.

Faça a prévia

POST /cashin/preview valida ativo, rede, endereço e valor sem criar uma cobrança.

Crie e mostre o PIX

POST /cashin/charge recebe o valor, CPF/CNPJ do pagador, destino e external_id. Mostre o QR somente depois de informar eventual retenção devolvida pela API.

Confirme e reconcilie

Consuma o webhook assinado. Use GET /cashin/{cashin_id}/status como fallback e o mesmo external_id nos retries.

Request mínimo de produção

curl -X POST https://api.luniumpay.com/cashin/charge \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: SUA_CHAVE' \
  -d '{
    "amount_cents": 25000,
    "payer_tax_number": "CPF_OU_CNPJ",
    "asset": "usdt",
    "chain": "polygon",
    "payout_address": "CARTEIRA_DO_CLIENTE",
    "external_id": "pedido-84721"
  }'

O payload é ilustrativo. Consulte o OpenAPI vivo para campos, limites e respostas vigentes antes de implementar.

Estados que o checkout precisa explicar

`pending`

QR criado e ainda não pago. Não gere outro automaticamente.

`delayed`

PIX pago e liberação retida. Não é falha; mostre o prazo devolvido pela API.

`paid`

O PIX foi recebido. Ainda confirme settlement_status; não libere o produto apenas por este estado.

`settled`

A liquidação foi concluída. Aceite também paid somente quando settlement_status estiver sent ou confirmed, conforme o contrato do fluxo.

`expired` / `refunded`

Encerre a tentativa antiga. Se necessário, crie outra com novo identificador comercial.

O que deve estar pronto antes do primeiro PIX real

Idempotência: um external_id por pedido, persistido antes da chamada.

Webhook: valide timestamp e assinatura; responda 2xx somente depois de persistir o evento.

Retenção: consulte o pagador antes de mostrar o QR e informe a expectativa de liberação.

Segredo: nunca envie a chave da API ao navegador, ao log ou a uma ferramenta de analytics.

Perguntas frequentes

A chave de produção depende de aprovação manual?

Não. POST /keys cria a chave de produção de forma self-service. Nome é obrigatório; e-mail, carteira e webhook podem ser definidos ou atualizados conforme o contrato.

Preciso usar polling?

Não como caminho principal. Webhook reduz latência e carga. A consulta de status deve existir para reconciliação e recuperação de eventos.

Como evito cobrança duplicada?

Envie external_id. A repetição idêntica recupera a operação original; mudar parâmetros usando o mesmo identificador retorna conflito.

Teste o contrato antes do checkout real

Comece sem dinheiro, valide os caminhos ruins e troque para uma chave de produção quando o seu tratamento de estados estiver correto.

Começar agora Falar com integração