Empieza por el flujo correcto

1. Elige el flujo#

La custodia es un saldo en reales brasileños. El socio recibe el importe neto del PIX y elige la moneda y la red al retirar. No es necesario registrar una billetera fija. Un depósito en custodia no crea saldos simultáneos en BTC, ETH y USDT.

Ten en cuenta el valor predeterminado de cada canal: en la API, omitir destino sigue significando cripto. Para recibir fondos en custodia, envía destino: "saldo". En Telegram, /cobrar valor cpf ya usa custodia de forma predeterminada.

2. Claves y configuración#

Base: https://api.luniumpay.com. En las rutas autenticadas, envía X-API-Key y, en los cuerpos JSON, Content-Type: application/json. Usa la clave en tu servidor; autoriza operaciones sobre la cuenta.

Sandbox

curl --fail-with-body https://api.luniumpay.com/keys/sandbox \
  -H 'Content-Type: application/json' \
  -d '{"email":"voce@empresa.com","name":"Minha integração de teste"}'

Sustituye voce@empresa.com por el correo de quien realizará la prueba: email es obligatorio. Aproximadamente un minuto después, el soporte de LuniumPay envía a esa dirección, una sola vez, una explicación de qué es LuniumPay, la integración en 3 pasos, el manual y el PDF, el diagrama de flujo y VendaCripto (aplicación lista para quienes solo quieren comprar o vender criptomonedas con PIX, sin integrar). Un mensaje por dirección, con un enlace para darse de baja. Sin un email válido, la respuesta es 400 con erro: "email_obrigatorio". Sigue siendo una llamada, sin aprobación ni clave de API; name es opcional.

Guarda api_key como LUNIUM_API_KEY en el entorno de tu servidor. Las claves nuevas de prueba tienen el prefijo lun_test_; las de producción, lun_live_. Las claves antiguas lun_ siguen siendo válidas.

El sandbox simula PIX de entrada, abonos en custodia BRL, entregas y retiros de criptomonedas, payout PIX, transferencias internas y cash-out. El QR no se puede pagar: confirma en POST /sandbox/cashin/{cashin_id}/pay. No se activa ningún banco, plataforma de intercambio ni blockchain. Consulta la guía del sandbox y GET /sandbox para conocer los escenarios, la persistencia y las diferencias con producción. La custodia no requiere una billetera fija.

Producción sin billetera fija

Una llamada. Sin registro, sin aprobación humana y sin espera: la clave de producción se crea al instante, igual que la de prueba. Solo name es obligatorio; indica email de todas formas, porque la clave se envía a esa dirección. Entrar en Lunium Partners se recomienda, pero no es una condición.

curl --fail-with-body https://api.luniumpay.com/keys \
  -H 'Content-Type: application/json' \
  -d '{"name":"Meu projeto","email":"operacao@example.com"}'

Sustituye el nombre y el correo por los tuyos. La respuesta incluye api_key, key, limits, monitor_url y las instrucciones de Telegram. La clave completa solo se presenta al crearla. monitor_url es el panel de seguimiento; trata también ese enlace como información privada del proyecto.

Las claves de producción nuevas se crean con custodia y payouts habilitados. La situación de tu clave es la que prevalece: consulta payout.enabled en GET /keys/me y custodia_ativa en GET /saldo.

curl --fail-with-body https://api.luniumpay.com/keys/me \
  -H "X-API-Key: $LUNIUM_API_KEY"

curl --fail-with-body https://api.luniumpay.com/saldo \
  -H "X-API-Key: $LUNIUM_API_KEY"

Configura un receptor HTTPS de webhooks mediante PATCH /keys/me con webhook_url; guarda el webhook_secret devuelto. settlement_address es una opción para la entrega directa en Polygon. No es un requisito para la custodia ni define los destinos de los retiros futuros.

Reutiliza tu clave de prueba: la creación de claves tiene límites por IP. En 429, respeta el plazo indicado. No crees una clave por operación.

3. Cobrar PIX para custodia#

Crear la solicitud de cobro

Consulta antes GET /cashin/limits?payer_tax=CPF_OU_CNPJ, autenticado con la clave del proyecto. El documento pertenece a quien pagará el PIX; customer_ref identifica la subcuenta de tu sistema. Son datos distintos.

El ejemplo usa R$ 50,00. Sustituye el documento y la referencia, y elige un importe permitido para ese pagador. La llamada en producción crea una solicitud de cobro real.

curl --fail-with-body https://api.luniumpay.com/cashin/charge \
  -H "X-API-Key: $LUNIUM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "amount_cents":5000,
    "payer_tax_number":"00000000191",
    "destino":"saldo",
    "customer_ref":"cliente-42",
    "external_id":"deposito-cliente42-001"
  }'

No envíes payout_address para este flujo. Sin customer_ref, el abono pertenece al saldo de la propia clave, llamado casa. Con la referencia, pertenece solo a esa subcuenta.

Guarda cashin_id y external_id. Muestra qr_copypaste, qr_image_url cuando esté disponible, el importe y el expires_at devueltos. Un QR generado significa que se ha creado una solicitud de cobro; aún no significa que se haya recibido dinero.

Confirmar el abono

Usa GET /cashin/{cashin_id}/status o los eventos de webhook. Sigue dos estados:

Considera el abono/entrega completado en cashin.settled o al consultar status: "paid" con settlement_status: "sent". En custodia, confirma el importe y la disponibilidad en GET /saldo?customer_ref=cliente-42 y en los movimientos. Un abono registrado puede estar bloqueado por una retención; no gastes total_cents como si fuera disponivel_cents.

depix_received_cents es el importe recibido del liquidador antes de deducir las tarifas de depósito de la clave. El nombre es heredado y no implica que ese sea el abono neto del cliente. Para conciliar, usa los movimientos del saldo.

Tarifa de depósito y disponibilidad

GET /saldo publica deposito_fee_bps, deposito_fee_fixed_cents, carencia_horas, carencia_ate, retencao_acima_cents y proximas_liberacoes. 100 bps = 1%. Los nuevos depósitos tienen deposito_fee_bps=0 y deposito_fee_fixed_cents=100, sin comisión del socio.

Hay tres conceptos separados:

held_hours y hold_hours no son alias. Una solicitud de cobro puede tener held: false y seguir sujeta a una retención local. No prometas una liberación inmediata a partir de ese booleano aislado.

No existe un período de espera universal de 24 horas para todos los socios. Las claves con saldo instantáneo tienen sus propias reglas, pero siguen sujetas a las retenciones del pagador, de la solicitud de cobro y a bloqueos. Consulta la creación, el estado y el saldo en conjunto; un retiro rechazado por el período de espera devuelve 423 y el momento de liberación.

Límites por pagador

GET /cashin/limits publica el tramo instantáneo, la posibilidad de un QR con retención, el uso y la próxima liberación del documento. Las condiciones de la clave pueden cambiar los límites. La consulta es orientativa: la creación vuelve a validar la operación, incluido el flujo de custodia instantánea.

allow_hold: false rechaza la solicitud de cobro cuando requiere la retención calculada a partir del límite del pagador. No desactiva otras reglas contractuales ni bloqueos posteriores. Omitir el campo permite la retención aplicable. Muestra estas condiciones antes del pago.

El mínimo efectivo también depende de las tarifas y del proveedor. No uses R$ 1,00 como prueba universal ni confundas el mínimo global con el mínimo admitido por la ruta.

8. Criptomonedas externas a PIX#

Este flujo recibe criptomonedas de una billetera externa. Para gastar saldo en custodia mediante PIX, usa /payouts.

1. Consulta GET /catalog, el catálogo de entrada de criptomonedas; es distinto de /cashin/catalog.
2. Opcionalmente, usa POST /cash-outs/preview para obtener una estimación sin una orden.
3. Crea la cotización mediante POST /cash-outs.
4. Muestra la cantidad, la red, el importe neto en reales brasileños, el destinatario y la validez. Acepta mediante POST /cash-outs/{cashout_id}/accept.
5. Solo entonces muestra el deposit_address, el deposit_tag cuando exista y el importe exacto devuelto.
6. Sigue GET /cash-outs/{cashout_id} o el webhook hasta el estado final.

Ejemplo de sandbox, usando LUNIUM_API_KEY de prueba:

curl --fail-with-body https://api.luniumpay.com/cash-outs \
  -H "X-API-Key: $LUNIUM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "asset":"USDT",
    "network":"polygon",
    "amount":"10.00",
    "pix_key":"teste@example.com",
    "pix_key_type":"email",
    "external_id":"sandbox-cashout-001"
  }'

Envía amount (criptomonedas) o brl_amount (reales brasileños deseados), como cadena decimal con punto. No envíes ambos. La creación puede responder con 200 en producción o 201 en el sandbox; acepta respuestas 2xx según el contrato. cashout_id es el identificador devuelto, no un ID creado por el integrador.

En producción, indica una refund_address válida para la misma red y controlada por el destinatario de la devolución. El origen de un retiro de un exchange puede ser la billetera colectiva del exchange; no des por hecho que sirva como billetera de devolución.

Estados y comprobantes

No todas las rutas pasan por todas las etapas. timeline, confirmations y confirmations_required, cuando existan, ayudan a hacer el seguimiento. No trates la confirmación del depósito como un PIX completado.

En COMPLETED, comprueba pix_e2e, pix_paid_at, receipt_url, receipt_pdf_url y verify_url, cuando estén disponibles. Usa los enlaces devueltos. La consulta pública GET /v1/verificar/{e2e} verifica un PIX conocido; no es una prueba genérica de toda operación con criptomonedas.

En una devolución, sigue REFUNDED y refund_tx_hash. El importe y el plazo dependen de la etapa alcanzada y de la devolución del proveedor. No prometas una reversión íntegra, automática ni con un plazo fijo para cualquier fallo. Un depósito tardío o distinto de lo indicado requiere seguir la misma orden; no reutilices su dirección para otra operación.

Consulta del titular y pago de QR

GET /pix/keys/lookup?key=...&type=... es auxiliar. Puede responder con 200 con available: false, verified: false, verification_status: "not_performed" y nombres null. Muestra «titular no verificado»; no inventes un nombre ni confundas una consulta no disponible con un pago no disponible. En el sandbox, el titular es ficticio y viene con source: "sandbox".

br_code tiene una disponibilidad independiente. Producción puede rechazar la creación con 503 br_code_indisponivel, aunque una vista previa o el sandbox acepten el QR. No ofrezcas el pago del código para copiar y pegar como una función siempre activa. Cuando está habilitado, sustituye pix_key, amount y brl_amount, y requiere un importe definido y un activo compatible.

La reserva operativa de las nuevas ventas de criptomonedas a Pix es de R$ 1,00 por operación, para todos los socios, ya incluida en la cotización e indicada en reserve_brl. El equivalente en USDT se calcula al tipo de cambio del momento y queda fijado en la orden: pix_key_reserve_usd para clave Pix o copia_e_cola_buffer_usd para el código para copiar y pegar. Estos campos representan el importe convertido, no un cobro de US$ 1. No vuelvas a sumar la reserva al total. Los porcentajes y costes del proveedor siguen incluidos en la cotización. El QR se paga solo por el importe exacto. La reserva operativa no se devuelve después del pago; el margen temporal de saldo es independiente. Las órdenes anteriores mantienen los importes contratados. DePix/Liquid sigue su propia tarifa en reales brasileños.

Usa solo las redes ofrecidas en el catálogo de la operación. Las redes con memo pueden quedar excluidas de cash-out aunque existan en el catálogo de entrega; no copies la lista de un producto a otro.

12. Sandbox y pruebas de integración#

Ejecuta node sandbox.mjs all o python3 sandbox.py all en el kit. Los ejemplos confirman la clave de prueba, simulan el pago PIX y recorren custodia, retiro USDC/Base, payout, BTC, USDC/Polygon y cash-out. Para cash-in/payout, usa sandbox_scenario; la retención, la devolución, el fallo de entrega y el resultado incierto se detallan en la guía. GET /sandbox/events permite examinar los eventos; los callbacks configurados usan la cola firmada del producto. Los precios y plazos son sintéticos, no condiciones reales de la plataforma de intercambio asociada.

En el cash-out del sandbox, los dos primeros decimales de amount seleccionan el escenario:

Las órdenes de prueba son temporales y no representan depósitos reales. El sandbox no certifica plazos, precios, disponibilidad del proveedor ni abonos en custodia de producción. Para cash-in y saldo, prueba las rutas de simulación y los escenarios documentados. La prueba piloto real posterior usa el mínimo admitido por la ruta y el pagador, con un importe y un destinatario autorizados.

15. Lista de comprobación de producción#

• Clave guardada en el servidor; entorno de pruebas separado de producción.
• /keys/me y /saldo comprobados para la clave y para el ámbito de cada cliente.
• La custodia usa destino: "saldo"; la billetera solo se elige al retirar criptomonedas.
• La interfaz consulta el catálogo y los límites actuales, muestra la retención y exige un memo cuando es necesario.
• IDs guardados de forma persistente; los reintentos conservan el cuerpo y external_id; recuperación tras un timeout probada.
• El webhook verifica el HMAC y la marca de tiempo, elimina duplicados por evento y responde antes del timeout.
• La conciliación distingue entre PIX pagado, abono registrado, saldo disponible para retirar y criptomonedas entregadas.
• Los errores de saldo, período de espera, ruta, tarifa, proveedor y clave se gestionan sin duplicar operaciones.
• Telegram vinculado por un administrador identificado; retiros confirmados en el contexto correcto.
• La validación incluye éxito, retención, vencimiento, fallo, reenvío y consulta después de perder una respuesta.

Soporte: @luniumB2B · contato@luniumpay.com. Sigue el estado y el canal de socios. Al pedir ayuda, envía los IDs y request_id cuando esté disponible, sin compartir la clave completa.