Para plataformas y billeteras · PIX → cripto
Cobra PIX y recibe USDT en tu billetera
Tu cliente paga en reales brasileños desde el banco. Tú sigues el cobro del PIX y la entrega de USDT en la billetera indicada, por la red disponible. Lunium ofrece una API y herramientas para agentes; empieza por entender el flujo y preparar tu integración.
Cómo empezar con tu IA
Puedes usar Gemini, ChatGPT u otra IA para entender este recorrido y preparar tu integración.
Comprueba cuánto vas a recibir
Indica el importe en reales brasileños, el documento del pagador y la billetera con la red correcta. Consulta la estimación neta, las tarifas, el mínimo y las posibles retenciones.
Genera y comparte el QR
La solicitud de cobro devuelve el código QR, el PIX para copiar y pegar y la fecha de vencimiento. El pagador usa su aplicación bancaria.
Haz el seguimiento hasta la entrega
Consulta el PIX recibido y el envío de las criptomonedas. El enlace de la transacción y la confirmación en la red se muestran cuando están disponibles.
Una petición para tu IA
Quiero recibir R$ 100 por PIX y recibir USDT en mi billetera usando Lunium. Comprueba la moneda, la red, las tarifas y el mínimo; explica cómo conectar mi cuenta y generar el QR, y sigue las etapas cuando las herramientas estén disponibles.
El importe en USDT es una estimación hasta la conversión. El plazo depende de la retención aplicable, el procesamiento y la red.
La ejecución real desde el chat requiere un agente conectado a tu cuenta. El conector público de Lunium ofrece demostraciones; la conexión de producción mediante OAuth en ChatGPT aún no está disponible. Nunca pegues tu clave de producción en una conversación.
Cómo integrar PIX a stablecoins
Este flujo sirve a los productos que necesitan entregar criptomonedas después de cada pago: entrada de fondos en billeteras, compra de activos por usuarios y cobros comerciales con liquidación en criptomonedas. El pagador usa PIX en el banco; tu backend elige la moneda, la red y la billetera de destino.
Consulta la ruta
Lee GET /cashin/catalog, selecciona un par disponible para entrega y consulta POST /cashin/preview para estimar el importe recibido y el mínimo en reales brasileños.
Genera la solicitud de cobro
Envía POST /cashin/charge con destino: "cripto", el importe en centavos, el documento del pagador y la dirección en la red seleccionada.
Concilia la entrega
Muestra el QR y la validez devueltos. Sigue el pago y, por separado, la entrega de criptomonedas mediante la consulta de estado o un webhook.
Si quieres recibir reales brasileños y decidir el retiro después, usa PIX a custodia BRL. En ese flujo, la solicitud de cobro no exige una billetera y la conversión solo se realiza al retirar.
Ejemplo de solicitud de cobro PIX a USDT
Usa una clave lun_test_, guardada en el backend, y confirma key.sandbox=true en GET /keys/me. Los ejemplos siguientes usan documentos y destinos sintéticos. No los envíes con credenciales de producción.
POST /cashin/charge · cuerpo de ejemplo para el sandbox
{
"amount_cents": 10000,
"payer_tax_number": "12345678901",
"destino": "cripto",
"asset": "usdt",
"chain": "polygon",
"payout_address": "0x1111111111111111111111111111111111111111",
"external_id": "sandbox-pix-usdt-001"
}Envía a https://api.luniumpay.com/cashin/charge con X-API-Key: $LUNIUM_API_KEY y Content-Type: application/json. amount_cents: 10000 representa R$ 100,00. El importe es ilustrativo: la creación vuelve a validar los límites y el mínimo efectivo.
Guarda el cashin_id devuelto. En el sandbox, confirma mediante POST /sandbox/cashin/{cashin_id}/pay con cuerpo {} y consulta GET /cashin/{cashin_id}/status hasta status=paid y settlement_status=sent. El QR de prueba contiene SANDBOX:NAO_PAGAVEL: y no se debe pagar en un banco.
Para USDC o BTC, selecciona un par disponible y cambia asset, chain y la dirección a la vez. El campo de red es chain en este endpoint; recibe el network del catálogo de entrega.
La moneda, la red y el mínimo proceden de la API
| Consulta | Qué usar en tu producto |
|---|---|
GET /cashin/catalog | Pares de instant y convert con entregavel=true; lee memoRequired, withdrawMin y withdrawFee. |
POST /cashin/preview | Estimación de conversión y min_brl_cents. La vista previa no crea una solicitud de cobro ni fija el tipo de cambio hasta el pago. |
GET /cashin/limits?payer_tax=... | Límites orientativos del pagador, tramos de retención y saldo disponible. La creación vuelve a validar las condiciones. |
GET /cashin/{cashin_id}/status | Pago, entrega, retención y hash, cuando esté disponible. Lee los dos estados de la operación. |
No mantengas una lista fija de criptomonedas, redes, mínimos o plazos en el checkout. Una ruta puede entrar en mantenimiento, requerir un memo o dejar de estar disponible para entrega. stale=true indica que el catálogo está en caché. El plazo depende de la retención aplicable, el proveedor y la red; generar el QR no garantiza la liquidación inmediata.
PIX pagado y criptomonedas entregadas son etapas diferentes
cashin.paid confirma el PIX recibido. cashin.settled y la combinación status=paid con settlement_status=sent indican el envío registrado. Para entrega en blockchain, lee settlement_proof, la transacción y settlement_confirmed_at: envío registrado y confirmación en red son etapas separadas. Un resultado incerto exige conciliación: no marques el pedido como entregado ni inicies otra solicitud de cobro automáticamente.
Guarda external_id y el identificador devuelto antes de actualizar tu pedido. En los reintentos, conserva la misma referencia y el mismo cuerpo. Configura un receptor HTTPS, valida la firma HMAC sobre el cuerpo sin procesar y elimina los duplicados mediante event_id. Después de un timeout, consulta la operación original antes de decidir si repites la solicitud. El manual de webhooks y conciliación detalla la implementación.
Muestra al cliente las retenciones devueltas en held_hours, hold_hours y liberar_em, cuando existan. Si no aceptas la retención prevista para el pagador, usa allow_hold:false; esto no elimina otras restricciones de la clave.
Consultas de integración
¿Es obligatorio registrar una billetera fija?
No. En el cash-in directo puedes indicar payout_address por solicitud de cobro. Para recibir fondos sin definir una dirección, elige destino: "saldo" y retira después desde la custodia.
¿USDT y USDC están disponibles en cualquier red?
Utiliza únicamente los pares entregables del catálogo actual. La existencia de un activo en una red no garantiza que esta ruta esté habilitada. Mínimos, costos y memo varían por ruta.
¿El sandbox paga un PIX y envía fondos mediante la plataforma de intercambio asociada?
No. El PIX no se puede pagar y la entrega de criptomonedas es ficticia, con un hash que empieza por sandbox:. El sandbox valida tu código y tus eventos. Una operación con PIX y entrega reales se realiza en producción.
¿Por qué informar el CPF o el CNPJ del pagador?
payer_tax_number identifica a quien realizará el pago y se usa en los límites y las verificaciones. No es el identificador del pedido ni sustituye a customer_ref. Envía el documento correcto en producción.