On-ramp y off-ramp en Brasil, en una API

A quién va dirigido

• Empresas extranjeras que quieren vender, pagar o recibir fondos en Brasil sin montar una operación local desde cero.
• Exchanges, plataformas de intercambio o brokers que necesitan un par BRL sin operar un banco brasileño.
• Productos globales que ya tienen PIX en su hoja de ruta y no quieren tres proveedores para una sola función.

¿Qué son on-ramp y off-ramp?

On-ramp es la conversión de moneda tradicional a criptomonedas. En este flujo, el cliente paga Pix y la aplicación sigue la entrega del activo en la red elegida. Off-ramp es la conversión de criptomonedas a moneda tradicional: tras la cotización, la aceptación y el depósito confirmado, la operación continúa con el pago Pix.

Recibir Pix en custodia es una opción diferente: el saldo permanece en reales brasileños hasta que se solicita un retiro. Recibir el Pix no significa que el saldo ya se haya convertido en stablecoins.

El flujo de principio a fin

1. Entrada: POST /cashin/charge crea un QR PIX identificado con el CPF/CNPJ de quien va a pagar. Tras el pago, sigue las posibles retenciones y la entrega de criptomonedas hasta el estado final.
2. Salida: POST /cash-outs cotiza, /accept fija la cotización y devuelve la dirección; haces el depósito y una clave PIX recibe reales brasileños.
3. Custodia (opcional): con destino: "saldo" el PIX se convierte en saldo en reales brasileños por subcuenta, y puedes pagar con POST /payouts cuando quieras.
4. Ambos sentidos usan la misma clave, el mismo formato de error (erro + acao) y el mismo external_id.
5. Valida la firma de los webhooks y usa la consulta de estado para conciliar eventos ausentes o retrasados.

Endpoints utilizados

Ejemplo de solicitudes — sustituye los datos

# entrada: PIX se convierte en stablecoins en tu billetera
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"}'

# salida: las stablecoins se convierten en PIX en la cuenta de alguien
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: prueba antes de gastar

Una llamada, sin aprobación previa ni tarjeta; solo es obligatorio tu correo (al que enviamos el manual, el diagrama de flujo y la guía de integración paso a paso). La clave lun_test_ permite probar los flujos y escenarios documentados sin mover dinero real.

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

Lo que el sandbox no demuestra: liquidación real. No se mueven criptomonedas ni se paga ningún PIX; sirve para ajustar el contrato, no para medir la vía de procesamiento.

Activos y redes

El catálogo de entrada de criptomonedas es GET /catalog; el de entrega tras Pix es GET /cashin/catalog. Consulta el activo y la red del flujo elegido antes de cotizar. La disponibilidad y los mínimos pueden cambiar.

Usa deposit_tag en el depósito cuando la aceptación indique un memo. En la entrega, envía payout_tag cuando lo requiera la ruta. El manual de la API describe cada campo.

Límites y retenciones

Consulta GET /keys/me para conocer los límites y las tarifas de la cuenta, GET /cashin/limits?payer_tax=... para el pagador y las vistas previas para el mínimo de la ruta. No uses un límite máximo fijo compartido entre cash-in, cash-out y payout.

Una solicitud de cobro pagada puede quedar retenida antes de la liquidación. Usa los estados, la cronología y los eventos firmados para distinguir entre cobro, saldo disponible y entrega final. La validez de la operación figura en expires_at.

Mediciones, no promesas

El plazo depende del flujo, la ruta disponible, las confirmaciones de la red y las posibles retenciones. Sigue la operación hasta su estado final y consulta el estado del servicio. El tiempo de una simulación no mide una liquidación real.

Idempotencia

Envía external_id en cada operación que mueve dinero. Repetir la misma llamada devuelve la misma operación, nunca una segunda; los mismos parámetros con un id distinto crean dos, y el mismo id con parámetros distintos devuelve 409 external_id_divergente en lugar de intentar adivinar.

Un timeout no es un rechazo. Si la llamada no respondió, consulta por el external_id antes de repetirla: la operación puede existir.

Webhooks y conciliación

Cada transición genera un evento firmado con HMAC SHA-256 y una marca de tiempo (cabecera X-Lunium-Signature, formato t=…,v1=…). La marca de tiempo impide reutilizar una entrega capturada. Verifica la firma antes de confiar en el cuerpo.

El webhook es la señal principal; el polling es opcional. Cuando necesites consultar, el estado incluye la timeline marcada por el servidor — representa la etapa a partir de ella, porque el cronómetro de tu polling mide tu red, no la operación.

¿No respondió con 2xx? Se reintenta la entrega con esperas progresivas. Puedes reenviarla manualmente en POST /webhooks/deliveries/{event_id}/retry y probar tu URL en POST /webhooks/test.

Cuando algo falla

Cada error incluye erro (qué ocurrió) y acao (qué hacer): corrigir, repetir, esperar o parar. Es el campo que puede seguir un agente o un reintento automático sin recurrir a heurísticas.

parar es el más importante: en provedor_sem_resposta en un retiro, el PIX puede haberse enviado. Consulta la operación; no la repitas.

Seguridad

• webhook firmado — Cada webhook se firma con HMAC SHA-256 y una marca de tiempo (cabecera X-Lunium-Signature, formato t=…,v1=…), lo que impide reutilizar una entrega capturada.
• idempotencia — external_id en cash-in, cash-out y payout: repetir la misma llamada devuelve la MISMA operación, nunca una segunda. Los parámetros distintos con el mismo external_id devuelven 409.
• tráfico de salida validado — La URL del webhook se resuelve y valida antes de cada entrega: se rechazan direcciones internas, metadatos de la nube y redirecciones a redes privadas, y la conexión se fija en la IP validada.
• retención con bloqueo ante fallos — La retención se verifica al liquidar y de nuevo al reclamar la operación en SQL: ninguna vía (worker, consulta de estado o cola) puede liquidar antes de tiempo.
• payout duradero — El retiro registra la operación y debita el saldo en la MISMA transacción, antes de cualquier llamada al proveedor: no existe un débito sin una orden que conciliar.
• verificación abierta — GET /v1/verificar/{e2e} comprueba un PIX liquidado sin ninguna clave; la contraparte no tiene que confiar en nuestra palabra.

La verificación abierta es especialmente importante en una negociación: tu contraparte comprueba el PIX por su cuenta, sin clave y sin depender de nuestra palabra.

Tiempo hasta la primera integración

Sandbox con una llamada, sin aprobación previa. Permite probar los flujos y escenarios documentados con importes ficticios. Las cotizaciones y algunas respuestas de simulación tienen campos propios. Consulta el manual y valida la configuración y la liquidación en una prueba piloto de producción antes de atender a clientes.

Preguntas sobre Pix, on-ramp y off-ramp

Prepara un plan de integración para tu equipo

Usa la lista de comprobación para definir el flujo, validar el saldo y los mínimos, probar los fallos y registrar las evidencias antes de la prueba piloto. Puede rellenarla un desarrollador o usarse como contexto para un agente de IA.

Descargar lista de comprobación de integración (Markdown) · Integrar con IA · Todas las guías

Contenido técnico del equipo de LuniumPay · Revisado el 18 de septiembre de 2026. Conoce la empresa.