PIX y stablecoins para billeteras y aplicaciones

A quién va dirigido

• Billeteras o aplicaciones ya publicadas que quieren sustituir su on-ramp/off-ramp brasileño actual.
• Productos que necesitan depósitos y retiros con una misma integración, sin dos proveedores.
• Equipos que quieren mostrar al usuario en qué punto está la operación, más allá de un indicador de espera.

El problema

En una aplicación de billetera, el depósito es donde el usuario abandona. Introduce un importe, el proveedor lo rechaza sin decir cuánto se permitiría y la pantalla muestra «error». Después de pagar, se queda mirando un indicador de carga sin saber si serán cinco segundos o cinco minutos. Estos dos momentos hacen perder más usuarios que cualquier tarifa.

Ambos problemas tienen respuesta en la API. El límite de cada pagador se puede consultar antes de que aparezca el teclado, y el estado incluye una cronología marcada por el servidor, con la mediana medida de cada etapa: puedes escribir «etapa 3 de 5, suele tardar 39 s» sin inventar cifras.

El flujo de principio a fin

1. El usuario indica su CPF una vez. Consultas GET /cashin/limits?payer_tax= y ya puedes mostrar cuánto puede depositar sin retención y cuánto se permite con retención.
2. Elige el importe. POST /cashin/charge con customer_ref (su id en tu sistema) devuelve el código para copiar y pegar.
3. Paga. Llega el webhook cashin.paid ; la pantalla cambia de etapa sin polling.
4. Se realiza la entrega y cashin.settled incluye el hash. Si el destino es saldo, el abono ya aparece disponible.
5. Para retirar: POST /payouts (PIX) o POST /saldo/sacar-cripto (cualquier moneda del catálogo), siempre con el mismo customer_ref.

Endpoints utilizados

Ejemplo ejecutable

# depósito del usuario: PIX identificado con su CPF, criptomonedas en su billetera
curl -X POST https://api.luniumpay.com/cashin/charge -H "X-API-Key: $LUNIUM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":15000,"asset":"usdt","chain":"polygon",
       "payout_address":"0xCarteiraDoUsuario",
       "payer_tax_number":"12345678909",
       "customer_ref":"user_8842","external_id":"dep-8842-17"}'

# límite de ese usuario ANTES de mostrar el teclado del importe
curl "https://api.luniumpay.com/cashin/limits?payer_tax=12345678909" -H "X-API-Key: $LUNIUM_KEY"

async function limiteDoUsuario(cpf) {
  const r = await fetch(`${API}/cashin/limits?payer_tax=${cpf}`, {
    headers: { "X-API-Key": process.env.LUNIUM_KEY },
  });
  const l = await r.json();
  return { naHora: l.instant_available_cents, comRetencao: l.held_qr?.available_cents ?? 0 };
}

async function depositar({ cents, cpf, carteira, userId, idempotencia }) {
  const r = await fetch(`${API}/cashin/charge`, {
    method: "POST",
    headers: { "X-API-Key": process.env.LUNIUM_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      amount_cents: cents, asset: "usdt", chain: "polygon",
      payout_address: carteira, payer_tax_number: cpf,
      customer_ref: userId, external_id: idempotencia,
    }),
  });
  if (r.status === 403) throw new Error("acima do limite deste pagador");
  return r.json();
}

import os, requests

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

def limite_do_usuario(cpf):
    l = requests.get(f"{API}/cashin/limits", headers=H, params={"payer_tax": cpf}, timeout=20).json()
    return l["instant_available_cents"], (l.get("held_qr") or {}).get("available_cents", 0)

def depositar(cents, cpf, carteira, user_id, idempotencia):
    r = requests.post(f"{API}/cashin/charge", headers=H, timeout=30, json={
        "amount_cents": cents, "asset": "usdt", "chain": "polygon",
        "payout_address": carteira, "payer_tax_number": cpf,
        "customer_ref": user_id, "external_id": idempotencia})
    if r.status_code == 403:
        raise RuntimeError("acima do limite deste pagador")
    return r.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 toda la interfaz sin mover dinero.

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

Por encima del límite del pagador: 403 limite_do_pagador con acao: "corrigir" y el importe permitido. Muestra la cifra, no la palabra «error»: es lo que mejor ha convertido en las aplicaciones que ya lo usan.

Por debajo del mínimo de la ruta: la respuesta incluye el mínimo estimado en reales brasileños y no se debita nada. Ofrece el importe adecuado con un toque.

Primer depósito de un documento: el abono está disponible en cuanto se confirma el Pix; solo el primer PIX de un documento por encima de R$ 100,00 se retiene durante 24 h en el proveedor (delayed, se libera automáticamente con saldo.liberado). Indica la hora, no «inténtalo más tarde».

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

El recorrido crítico de la aplicación consta de dos llamadas: límite y solicitud de cobro. Ambas existen en el sandbox, con el mismo contrato: puedes construir toda la pantalla antes de que exista un contrato comercial.

Preguntas de los integradores