Para plataformas y socios · PIX → saldo BRL
Recibir Pix mediante la API, con saldo en reales brasileños.
Recibe PIX en el saldo en custodia de tu cuenta o de una subcuenta, sin registrar una billetera fija de criptomonedas. Después, elige entre retirar por PIX o convertir a una moneda y una red disponibles en el catálogo de entrega.
Solicitudes de cobro Pix para tu sitio, SaaS o plataforma.
Tu sistema puede crear una solicitud de cobro para cada pedido, mostrar el QR al cliente y seguir la confirmación mediante un webhook. El cobro se recibe en custodia BRL; comprueba la liquidación, las tarifas y el saldo disponible antes de solicitar un retiro.
Si estás eligiendo una solución, empieza por la descripción general de la API Pix. A continuación se indican los campos y ejemplos para implementar este cobro.
Recibe primero. Elige la salida después.
Este flujo es adecuado cuando tu producto necesita recibir pagos, mantener saldos separados y dejar el destino del retiro para una etapa posterior. La custodia es en BRL: un PIX no crea saldos simultáneos de BTC, USDT y USDC. La conversión a cripto ocurre cuando se solicita el retiro.
Solicitud de cobro sin billetera
Crea el PIX con destino: "saldo". Indica el importe y el documento del pagador; usa customer_ref para dirigir el crédito a una subcuenta.
Crédito y disponibilidad
Sigue la liquidación y confirma en los movimientos el importe neto tras las tarifas. Usa el saldo disponible; las retenciones y el período de espera pueden mantener bloqueada parte del total.
Retiro elegido posteriormente
Usa POST /payouts para PIX o POST /saldo/sacar-cripto para elegir moneda, red y dirección en el momento del retiro.
En la API, omitir destino sigue significando entrega directa de criptomonedas. Para la custodia, envía explícitamente destino: "saldo". En Telegram, /cobrar valor cpf usa custodia de forma predeterminada.
Cómo generar el PIX sin indicar una billetera
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": 100000,
"payer_tax_number": "12345678901",
"destino": "saldo",
"customer_ref": "cliente-teste",
"external_id": "sandbox-custodia-001"
}El ejemplo crea una solicitud de cobro ficticia de R$ 1.000,00. Envía a https://api.luniumpay.com/cashin/charge, con la clave de prueba en X-API-Key y el cuerpo como JSON. No incluyas payout_address en este flujo. payer_tax_number es el documento del pagador; customer_ref es la referencia del cliente en tu sistema.
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.
Después, consulta GET /saldo?customer_ref=cliente-teste. El abono es neto de las tarifas de la clave. Compara los movimientos con el importe efectivamente recibido, sin dar por hecho que el importe bruto del QR se haya convertido en saldo disponible.
Negocio, clientes y movimientos conciliables
| Consulta | Saldo o información devuelta |
|---|---|
GET /saldo | Saldo del negocio: la cuenta principal de la clave. No suma los clientes. |
GET /saldo?customer_ref=cliente-teste | Sólo la subcuenta indicada, con disponible, bloqueado y condiciones aplicables. |
GET /saldo/consolidado | Negocio y clientes, con el total en custodia para conciliar. |
GET /saldo/clientes | Lista de subcuentas; sigue la paginación devuelta. |
GET /saldo/extrato?customer_ref=cliente-teste | Movimientos de la subcuenta; continúa mediante before=proxima_pagina. |
Reutiliza la misma referencia, de hasta 80 caracteres, en el depósito, la consulta y el retiro. POST /saldo/transferir mueve saldo disponible entre subcuentas o el negocio, sin generar PIX. La transferencia interna también requiere una intención autorizada y un external_id estable.
La separación por customer_ref no sustituye la autenticación ni la autorización de los usuarios de tu producto. La clave de API autoriza operaciones sobre todas las subcuentas de esa cuenta; mantenla solo en el backend.
Retiro por PIX o en la criptomoneda elegida
Saldo BRL → PIX
POST /payouts recibe el importe en centavos, la clave PIX y la subcuenta que se debitará. Comprueba payout.enabled, el saldo y las tarifas antes de crear la operación.
Saldo BRL → cripto
POST /saldo/sacar-cripto recibe el importe en reales brasileños, la moneda, la red, la billetera, el documento del titular y el memo cuando sea necesario. La dirección puede cambiar en cada retiro.
POST /saldo/sacar-cripto · cuerpo de ejemplo para el sandbox
{
"amount_cents": 10000,
"asset": "usdc",
"chain": "base",
"payout_address": "0x1111111111111111111111111111111111111111",
"tax_number": "12345678901",
"customer_ref": "cliente-teste",
"external_id": "sandbox-saque-usdc-001"
}En el retiro en criptomonedas, amount_cents es el importe BRL que se va a convertir, no la cantidad de tokens. El débito incluye la tarifa del negocio; la conversión y los costes de la ruta afectan a la cantidad recibida. Sigue el cashin_id devuelto hasta settlement_status=sent.
Selecciona solo pares entregavel=true de GET /cashin/catalog; Liquid/DePix no están soportados en el retiro de custodia. Consulta los mínimos actuales y el memo. POST /cashin/preview estima la conversión, pero no es una vista previa completa del débito del retiro. max_debited_cents puede limitar el débito BRL, sin fijar el tipo de cambio ni la cantidad de tokens.
Las tarifas y las retenciones deben mostrarse en el producto
Lee deposito_fee_bps, deposito_fee_fixed_cents, carencia_horas y las próximas liberaciones en GET /saldo. Consulta también los límites del pagador en GET /cashin/limits. Un crédito liquidado puede continuar parcialmente bloqueado por una regla de retención.
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.
Consultas de integración
¿El socio recibe reales o todas las criptos?
El socio recibe saldo en reales brasileños, neto de tarifas. Al retirar criptomonedas, elige un par de moneda y red disponible para entrega en ese momento. Esto no significa compatibilidad ilimitada con todas las criptomonedas.
¿Se necesita una billetera fija en la clave?
No. El depósito en custodia no requiere dirección. En cada retiro cripto, indicas la billetera correspondiente a la red seleccionada. En el retiro PIX, indicas una clave PIX.
¿Cómo evitar gastar saldo bloqueado?
Usa el campo de saldo disponible de la subcuenta correcta y consulta las liberaciones y los movimientos. total_cents puede incluir importes bloqueados y no debe tratarse como saldo disponible para retirar.
¿Puedo probar depósito y retiro en la misma sandbox?
Sí. El recorrido custody crea el PIX ficticio, confirma el abono y ejecuta un retiro simulado en criptomonedas. El kit completo también prueba payout y la transferencia interna; no se mueve dinero real.