COMERCIO ELECTRÓNICO · MARKETPLACE · BILLETERA

Cómo recibir PIX de varios pagadores y liquidar en stablecoins

Crea una solicitud de cobro por pedido, nunca un QR genérico. Vincula tu external_id al pedido, indica el CPF/CNPJ del pagador, consulta el tramo disponible antes de mostrar el PIX y confirma mediante el webhook. La liquidación puede dirigirse a una billetera o al saldo/subcuenta, según el producto.
1 solicitud de cobro por pedidoCPF/CNPJ del pagadorexternal_idwebhookUSDT · USDC

Modelo de datos mínimo

checkout_order
  id                 // identificador interno
  lunium_external_id // estable y único
  lunium_cashin_id   // devuelto por la API
  payer_tax_hash     // política interna; no lo envíes a herramientas de analítica
  amount_cents
  status
  expected_release_at
  created_at

Flujo por pedido

Valida al pagador

Normaliza el CPF/CNPJ en el servidor y consulta GET /cashin/limits?payer_tax=. Los límites son individuales por documento.

Obtén la vista previa

Valida el importe, el activo, la red y la billetera en POST /cashin/preview. No muestres promesas basadas en una cotización calculada localmente.

Crea con un identificador único

Envía un external_id derivado del pedido. En caso de timeout, repite el mismo cuerpo y el mismo identificador.

Muestra el QR y la previsión

Si la API indica una retención, informa antes del pago de que la liberación se realizará más adelante. No lo llames fallo.

Confirma y concilia

El webhook actualiza el pedido. La consulta de estado y el historial de entregas recuperan cualquier vacío operativo.

Dos arquitecturas posibles

Liquidación directa

Cada solicitud de cobro indica payout_address; las stablecoins se envían a la billetera configurada para ese pedido.

Saldo y subcuentas

Con destino: saldo y customer_ref, el abono se separa por cliente y se usa después en las vías permitidas.

Errores que cuestan dinero

QR reutilizado: pierde la relación un pedido ↔ una solicitud de cobro y dificulta identificar el importe, el pagador y la devolución.
Reintento con un external_id nuevo: convierte una incertidumbre de red en una segunda solicitud de cobro.
Límite fijo en el código: queda desactualizado. Consulta /keys/me y /cashin/limits.
Estado guardado de forma persistente: guarda los identificadores antes de mostrar el QR y antes de confirmar el pedido en tu sistema.

Lista de comprobación de validación

Conciliación

Pedido interno, external_id y cashin_id vinculados y que se puedan buscar.

Privacidad

El CPF/CNPJ no se envía a herramientas de analítica, URL, grabación de sesiones ni registros de la aplicación.

Experiencia

El comprador ve el importe, el plazo, el vencimiento y las posibles retenciones antes de pagar.

Soporte

request_id y los identificadores técnicos bastan; nunca envíes la clave de API.

Valida tu checkout antes de migrar clientes

En el sandbox de cash-in, valida la autenticación, el catálogo, los límites, la vista previa y el webhook sin dinero. El QR pagable y los estados reales de la solicitud de cobro requieren una clave de producción y una primera prueba controlada.

Probar integraciónHablar sobre mi caso