A API de liquidação PIX ↔ cripto que a WantsPay integra

1 Visão geral

Uma única API cobre os dois sentidos do fluxo e a custódia entre eles. Todos os valores em reais trafegam em centavos (amount_cents); quantidades de cripto são strings decimais.

2 Autenticação

Toda requisição autenticada envia a sua chave no header X-API-Key. Requisições com corpo usam Content-Type: application/json.

curl --fail-with-body https://api.luniumpay.com/keys/me \
  -H "X-API-Key: $LUNIUM_API_KEY"

Verificar a chave e o saldo

3 Ambientes & chaves

Existe um ambiente de sandbox (determinístico, sem dinheiro real) e o de produção. Distinga-os pelo prefixo da chave e mantenha-os totalmente separados.

Criar chave de sandbox

curl --fail-with-body https://api.luniumpay.com/keys/sandbox \
  -H 'Content-Type: application/json' \
  -d '{"name":"Minha integração de teste"}'

Criar chave de produção

curl --fail-with-body https://api.luniumpay.com/keys \
  -H 'Content-Type: application/json' \
  -d '{"name":"Integração de produção","email":"operacao@wantspay.pro"}'

A resposta traz api_key, limits e uma monitor_url (painel privado de acompanhamento operacional). Guarde a api_key como LUNIUM_API_KEY no ambiente do servidor.

4 Comece agora

Do zero à primeira cobrança em quatro passos.

curl --fail-with-body https://api.luniumpay.com/cashin/charge \
  -H "X-API-Key: $LUNIUM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "amount_cents": 5000,
    "payer_tax_number": "00000000191",
    "destino": "saldo",
    "customer_ref": "cliente-42",
    "external_id": "deposito-cliente42-001"
  }'

5 Cash-in · PIX → cripto / custódia

Uma única cobrança (POST /cashin/charge) atende dois destinos, controlados pelo campo destino:

{
  "amount_cents": 10000,
  "payer_tax_number": "00000000191",
  "destino": "cripto",
  "asset": "usdt",
  "chain": "polygon",
  "payout_address": "0x1111111111111111111111111111111111111111",
  "external_id": "compra-cripto-001",
  "allow_hold": false
}

A resposta traz cashin_id, qr_copypaste, qr_image_url e expires_at. Gerar o QR confirma a criação — não o recebimento.

Acompanhar o status

Antes de cobrar, você pode estimar com POST /cashin/preview e checar o teto do pagador com GET /cashin/limits?payer_tax=CPF. Redes e ativos disponíveis para entrega vêm de GET /cashin/catalog (campo entregavel: true).

6 Cash-out · cripto → PIX

Quando alguém envia cripto de uma carteira externa e você precisa pagar em PIX, o fluxo tem três passos: cotar, aceitar (recebe o endereço de depósito) e acompanhar.

{
  "asset": "USDT",
  "network": "polygon",
  "amount": "10.00",
  "pix_key": "recebedor@example.com",
  "pix_key_type": "email",
  "external_id": "cashout-001"
}

Ciclo de estados

Estados terminais: COMPLETED, MANUAL_REVIEW, REFUNDING_CRYPTO, REFUNDED, EXPIRED, FAILED. Estimativa sem criar ordem: POST /cash-outs/preview.

7 Custódia & saldo

O saldo em reais fica organizado por subconta (customer_ref) sobre a "casa". Consulte, extraia, transfira entre subcontas e saque como cripto.

Sacar saldo como cripto

{
  "amount_cents": 10000,
  "asset": "usdt",
  "chain": "polygon",
  "payout_address": "0x1111111111111111111111111111111111111111",
  "tax_number": "00000000191",
  "customer_ref": "cliente-42",
  "external_id": "saque-cripto-cliente42-001"
}

amount_cents é o valor em reais a debitar, não a quantidade de cripto. Para redes que exigem memo, envie payout_tag. Use max_debited_cents para limitar o débito total (com taxas). Acompanhe por GET /cashin/{id}/status.

8 Payouts · PIX via API

Envie PIX direto a partir do saldo em custódia — sem intermediar cripto. Requer payout.enabled na chave e saldo suficiente (valor + taxas).

{
  "amount_cents": 5000,
  "pix_key": "recebedor@example.com",
  "pix_key_type": "email",
  "tax_number": "00000000191",
  "customer_ref": "cliente-42",
  "external_id": "saque-pix-cliente42-001"
}

Estados: processing → sent / failed / refunded. Quando disponível, o comprovante traz e2e, paid_at, receiver_name e verify_url. As taxas estimadas saem de GET /saldo (saque_taxa_estimada_cents).

9 Catálogo, limites & cotações

Nunca fixe redes, mínimos ou taxas no código — leia-os por API antes de cada operação.

10 Comissão (partner fee)

Você pode embutir uma comissão própria sobre cada operação, definida em basis points (partner_fee_bps; 200 = 2%). Ela é calculada sobre a base após a taxa fixa e creditada num saldo de comissão separado.

{ "partner_fee_bps": 200 }   // 2%

A comissão é apurada após status=paid e settlement_status=sent. Consulte disponivel_cents, min_saque_cents e pode_sacar_agora antes de sacar. Fórmula: floor(base_cents × (10000 − lunium_bps − partner_bps) / 10000).

11 Webhooks

Configure a URL de recepção em PATCH /keys/me. A resposta devolve o webhook_secret uma única vez — guarde com segurança.

{ "webhook_url": "https://wantspay.pro/api/webhook" }

Assinatura (HMAC-SHA256)

Cada entrega traz o header X-Lunium-Signature: t=1700000000,v1=<hmac_hex>. Valide o HMAC-SHA256 de timestamp.raw_body — capture o corpo bruto antes de fazer o parse do JSON.

const crypto = require('crypto');

function verify(header, rawBody, secret) {
  const [, sigPart] = header.split(',');        // "v1=..."
  const t = header.split(',')[0].split('=')[1];
  const v1 = sigPart.split('=')[1];
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(v1), Buffer.from(expected)      // comparação em tempo constante
  );
}

Outros headers: X-Lunium-Event-Id (dedupe por ele), X-Lunium-Delivery-Id e X-Lunium-Attempt (até 12 tentativas em ~7h).

Formato do evento

{
  "event": "cashin.settled",
  "event_id": "evt_exemplo",
  "created_at": "2026-09-17T20:00:00.000Z",
  "data": {
    "cashin_id": "ci_exemplo",
    "destino": "saldo",
    "status": "paid",
    "settlement_status": "sent"
  }
}

12 Idempotência & erros

Envie external_id em toda operação financeira (cash-in, cash-out, payout, transferência). Em retry, reutilize o mesmo external_id com o corpo idêntico.

Códigos de erro

O corpo de erro inclui erro, acao, detail, request_id e agent_guidance. Ao pedir suporte, informe ambiente, id da operação, external_id, horário com fuso e request_id — nunca a chave, o segredo do webhook ou o CPF/CNPJ completo.

13 Referência de endpoints

Resumo das rotas mais usadas. Base: https://api.luniumpay.com.

14 Suporte