On-ramp e off-ramp no Brasil, em uma API

Para quem é

• Empresa estrangeira que quer vender, pagar ou receber no Brasil sem montar operação local do zero.
• Exchange, corretora ou broker que precisa de par BRL sem operar banco brasileiro.
• Produto global que já tem PIX na roadmap e não quer três fornecedores para uma coisa só.

O que são on-ramp e off-ramp?

On-ramp é a entrada de moeda tradicional em cripto. Neste fluxo, o cliente paga Pix e a aplicação acompanha a entrega do ativo na rede escolhida. Off-ramp é a saída de cripto para moeda tradicional: após cotação, aceite e depósito confirmado, a operação segue para o pagamento Pix.

Receber Pix em custódia é uma escolha diferente: o saldo fica em reais até uma solicitação de saque. Receber o Pix não significa que o saldo já foi convertido em stablecoin.

O fluxo, ponta a ponta

1. Entrada: POST /cashin/charge cria um QR PIX identificado pelo CPF/CNPJ de quem vai pagar. Após o pagamento, acompanhe eventuais retenções e a entrega de cripto até o estado final.
2. Saída: POST /cash-outs cota, /accept trava e devolve o endereço; você deposita e uma chave PIX recebe reais.
3. Custódia (opcional): com destino: "saldo" o PIX vira saldo em reais por subconta, e você paga com POST /payouts quando quiser.
4. Os dois sentidos usam a mesma chave, o mesmo formato de erro (erro + acao) e o mesmo external_id.
5. Valide a assinatura dos webhooks e use a consulta de status para reconciliar eventos ausentes ou atrasados.

Endpoints usados

Exemplo de requisições — substitua os dados

# entrada: PIX vira stablecoin na sua carteira
curl -X POST https://api.luniumpay.com/cashin/charge -H "X-API-Key: $LUNIUM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":100000,"asset":"usdc","chain":"polygon",
       "payout_address":"0xTesouraria","payer_tax_number":"12345678909",
       "external_id":"in-9001"}'

# saída: stablecoin vira PIX na conta de alguém
curl -X POST https://api.luniumpay.com/cash-outs -H "X-API-Key: $LUNIUM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset":"USDC","network":"polygon","brl_amount":"1000.00",
       "pix_key":"11122233344","pix_key_type":"cpf","external_id":"out-9001"}'

const API = "https://api.luniumpay.com";
const h = { "X-API-Key": process.env.LUNIUM_KEY, "Content-Type": "application/json" };

export const entrada = (cents, carteira, docPagador, id) =>
  fetch(`${API}/cashin/charge`, { method: "POST", headers: h, body: JSON.stringify({
    amount_cents: cents, asset: "usdc", chain: "polygon",
    payout_address: carteira, payer_tax_number: docPagador, external_id: id,
  })}).then((r) => r.json());

export const saida = (brl, chave, tipo, id) =>
  fetch(`${API}/cash-outs`, { method: "POST", headers: h, body: JSON.stringify({
    asset: "USDC", network: "polygon", brl_amount: brl,
    pix_key: chave, pix_key_type: tipo, external_id: id,
  })}).then((r) => r.json());

import os, requests

API, H = "https://api.luniumpay.com", {"X-API-Key": os.environ["LUNIUM_KEY"]}

def entrada(cents, carteira, doc_pagador, ident):
    return requests.post(f"{API}/cashin/charge", headers=H, timeout=30, json={
        "amount_cents": cents, "asset": "usdc", "chain": "polygon",
        "payout_address": carteira, "payer_tax_number": doc_pagador,
        "external_id": ident}).json()

def saida(brl, chave, tipo, ident):
    return requests.post(f"{API}/cash-outs", headers=H, timeout=30, json={
        "asset": "USDC", "network": "polygon", "brl_amount": brl,
        "pix_key": chave, "pix_key_type": tipo, "external_id": ident}).json()

Sandbox: teste antes de gastar

Uma chamada, sem aprovação prévia, sem cartão; só o seu e-mail é obrigatório (é para ele que mandamos o manual, o fluxograma e o passo a passo da integração). A chave lun_test_ permite testar os fluxos e cenários documentados sem movimentar dinheiro real.

curl -X POST https://api.luniumpay.com/keys/sandbox \
  -H "Content-Type: application/json" \
  -d '{"email":"voce@empresa.com","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

O catálogo de entrada de cripto é GET /catalog; o de entrega após Pix é GET /cashin/catalog. Consulte o ativo e a rede do fluxo escolhido antes de cotar. Disponibilidade e mínimos podem mudar.

Use deposit_tag no depósito quando o aceite informar um memo. Na entrega, envie payout_tag quando exigido pela rota. O manual da API descreve cada campo.

Limites e retenções

Consulte GET /keys/me para os limites e as taxas da conta, GET /cashin/limits?payer_tax=... para o pagador e as prévias para o mínimo da rota. Não use um teto fixo compartilhado entre cash-in, cash-out e payout.

Uma cobrança paga pode aguardar retenção antes da liquidação. Use os estados, a linha do tempo e os eventos assinados para distinguir recebimento, saldo disponível e entrega final. A validade da operação vem em expires_at.

Medições, não promessas

O prazo depende do fluxo, da rota disponível, das confirmações da rede e de eventuais retenções. Acompanhe a operação até o estado final e consulte o status do serviço. O tempo de uma simulação não mede uma liquidação real.

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

Cada erro traz erro (o que houve) e acao (o que fazer): corrigir, repetir, esperar ou parar. É o campo que um agente ou um retry automático consegue seguir sem heurística.

parar é o mais importante: em provedor_sem_resposta num saque, o PIX pode ter saído. Consulte a operação, não repita.

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

Sandbox em uma chamada, sem aprovação prévia. A sandbox permite exercitar os fluxos e cenários documentados com valores fictícios. Cotações e algumas respostas de simulação têm campos próprios. Confira o manual e valide a configuração e a liquidação em um piloto de produção antes de atender clientes.

Perguntas sobre Pix, on-ramp e off-ramp

Leve um plano de integração para sua equipe

Use o checklist para definir o fluxo, validar saldo e mínimos, testar falhas e registrar as evidências antes do piloto. Ele pode ser preenchido por um desenvolvedor ou usado como contexto para um agente de IA.

Baixar checklist de integração (Markdown) · Integrar com IA · Todos os guias

Conteúdo técnico da equipe LuniumPay · Revisado em 18 de setembro de 2026. Conheça a empresa.