Para billeteras y plataformas · criptomonedas → PIX
Paga PIX con criptomonedas y consulta el comprobante
Usa criptomonedas de una billetera externa para pagar a un destinatario por PIX. Antes del envío, consulta la cotización, confirma el importe y recibe las instrucciones de depósito. Sigue el pago y los enlaces del comprobante cuando estén disponibles.
Cómo empezar con tu IA
Puedes usar Gemini, ChatGPT u otra IA para entender este recorrido y preparar tu integración.
Indica el PIX y elige la criptomoneda
Usa la clave con el importe en reales brasileños o el código completo para copiar y pegar. La IA consulta las monedas y redes admitidas y presenta la cotización, los costes y el vencimiento.
Confirma y envía
Comprueba el importe efectivo del PIX y la cantidad exacta de criptomonedas. Tras la aceptación, envía a la dirección devuelta, por la red correcta y con memo/tag cuando se requiera.
Sigue el pago
Consulta el depósito, las confirmaciones y el pago del PIX. La operación presenta el E2E y los enlaces del comprobante disponibles; el documento puede estar listo después del pago.
Una petición para tu IA
Quiero pagar un PIX usando mis criptomonedas con Lunium. Comprueba las monedas y redes disponibles, muestra la cotización y explica cómo conectar mi cuenta. Con las herramientas conectadas, pide mi confirmación antes de aceptar y haz el seguimiento hasta el comprobante.
Los pagos por clave siguen el catálogo. El código para copiar y pegar admite actualmente USDT/USDC en rutas compatibles. El plazo depende de la red y del procesamiento del PIX.
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.
De la billetera del cliente a la clave PIX
Cash-out es la conversión de criptomonedas externas a reales brasileños. Sirve a billeteras y plataformas que ofrecen retiros por PIX a usuarios con activos en blockchain. La red de entrada y la moneda deben existir en GET /catalog; este catálogo es distinto del que se usa para entregar criptomonedas después de un PIX.
Cotiza antes de depositar
Usa POST /cash-outs con la cantidad de criptomonedas o el importe deseado en reales brasileños. Muestra el importe neto, el destinatario, la red y la validez.
Acepta la cotización
Llama a POST /cash-outs/{cashout_id}/accept. Solo después muestra la dirección de depósito, la cantidad exacta y el memo cuando exista.
Haz el seguimiento hasta el PIX
Consulta la orden o recibe webhooks. La confirmación del depósito aún no es un pago PIX; espera state=COMPLETED.
¿Tu dinero ya está en el saldo BRL de Lunium? Usa payout PIX para debitarlo. Cash-out es el flujo para recibir un nuevo depósito de criptomonedas externas.
Ejemplo de cotización de USDT a PIX
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 /cash-outs · cuerpo de ejemplo para el sandbox
{
"asset": "USDT",
"network": "polygon",
"amount": "10.00",
"pix_key": "teste@example.com",
"pix_key_type": "email",
"external_id": "sandbox-usdt-pix-001"
}Envía a https://api.luniumpay.com/cash-outs con X-API-Key y JSON. Guarda el cashout_id devuelto, acepta la cotización y sigue GET /cash-outs/{cashout_id}. La creación puede responder con 200 en producción o 201 en el sandbox; trata el éxito según el contrato, sin exigir solo uno de estos códigos.
| Campo | Regla de integración |
|---|---|
amount | Cantidad de criptomonedas como cadena decimal, por ejemplo "10.00". No uses float. |
brl_amount | Alternativa para cotizar a partir del PIX deseado, por ejemplo "50.00". Para pagar a una clave, envía amount o brl_amount. Para una solicitud de cobro con importe, envía solo br_code completo, sin esos dos campos y sin pix_key; USDT/USDC en una ruta compatible. |
network | Red de entrada de criptomonedas del GET /catalog. No copies las redes del catálogo de entrega. |
refund_address | Confirma una billetera controlada por el destinatario, compatible con el activo y la red de devolución. Tras la conversión, estos datos pueden diferir de las criptomonedas enviadas. Si la orden solicita una dirección, sigue refund_asset, refund_network y el flujo autenticado de AWAITING_REFUND_ADDRESS. |
En el sandbox, el depósito y el PIX se simulan después de la aceptación. Nunca envíes criptomonedas a la dirección ficticia. Para ejecutar todos los pasos, usa node sandbox.mjs cashout o python3 sandbox.py cashout en el kit de integración.
Cuándo considerar el PIX completado
| Etapa | Estados y acción |
|---|---|
| Cotización y depósito | QUOTE_CREATED, AWAITING_DEPOSIT, DEPOSIT_DETECTED: conserva la misma orden y muestra sus instrucciones. |
| Confirmación y ejecución | DEPOSIT_CONFIRMED, SELLING, SOLD, FORWARDING, PAYING_OUT: haz el seguimiento. No todas las rutas usan todas las etapas. |
| Pago completado | COMPLETED: comprueba pix_e2e, pix_paid_at, receipt_url y verify_url, cuando existan. Los enlaces pueden llegar después; sigue la misma orden o cashout.receipt_ready. |
| Excepciones | MANUAL_REVIEW, REFUNDING_CRYPTO, REFUNDED, EXPIRED y FAILED requieren un tratamiento específico. |
Usa los enlaces del comprobante devueltos. La consulta pública de un E2E verifica un PIX conocido; no sustituye a la confirmación de todo el recorrido. En una devolución, sigue REFUNDED y refund_tx_hash. El plazo y el importe dependen de la etapa alcanzada y del proveedor.
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.
Red, devolución y límites en el checkout
Consulta los límites de la clave en GET /keys/me y las condiciones efectivas en la cotización. Muestra la oferta solo mientras sea válida. Deposita exactamente el importe aceptado en la red devuelta e incluye deposit_tag cuando exista. Un depósito tardío o distinto de lo indicado debe conciliarse en la misma orden; no reutilices la dirección para otra venta.
En producción, no uses el origen on-chain como billetera de devolución sin confirmar su control: un retiro de un exchange puede proceder de una billetera colectiva. Registra una refund_address adecuada. La disponibilidad de una ruta, sus costes y las confirmaciones exigidas pueden cambiar.
Consultas de integración
¿Cuál es la diferencia entre USDT a PIX y payout PIX?
USDT a PIX recibe una nueva transferencia de criptomonedas y después paga reales brasileños. Payout PIX usa el saldo BRL ya disponible en custodia. Elige según dónde esté el dinero antes de la operación.
¿Puedo definir cuánto recibirá el destinatario en reales brasileños?
Usa brl_amount para indicar el objetivo en reales brasileños. La cotización devuelve la cantidad exacta de criptomonedas y el importe efectivo del PIX, que puede variar por redondeo. Comprueba estos importes, la validez, las tarifas y los límites antes de aceptar.
¿Es necesario identificar al destinatario por CPF?
Indica una clave PIX válida. Los formatos de 11 dígitos requieren el tipo cpf o phone. La consulta auxiliar del titular puede no estar disponible y no acredita la titularidad cuando verified=false.
¿Puedo pagar cualquier QR PIX con criptomonedas?
El pago mediante br_code tiene una disponibilidad propia y puede rechazarse en producción. No lo trates como equivalente al pago a una clave PIX ni como una función siempre habilitada.