{ "revision": "2026-10-06.2", "api_base": "https://api.luniumpay.com", "openapi": "https://docs.luniumpay.com/es/openapi.json", "manual": "https://docs.luniumpay.com/es/manual", "start_url": "https://luniumpay.com/es/integrar", "flows": { "custody": { "title": "Recibir PIX en custodia", "description": "Recibe saldo BRL y elige la moneda, red y dirección solo al retirar. No requiere billetera fija.", "sandbox_supported": true, "operations": [ "GET /keys/me", "GET /cashin/limits?payer_tax=CPF_DO_PAGADOR", "POST /cashin/charge com destino=saldo", "GET /cashin/{cashin_id}/status", "GET /saldo?customer_ref=CLIENTE", "GET /cashin/catalog", "POST /saldo/sacar-cripto" ], "create_example": { "amount_cents": 5000, "payer_tax_number": "CPF_REAL_DO_PAGADOR", "destino": "saldo", "customer_ref": "cliente-42", "external_id": "deposito-cliente42-001" }, "completion": "Crédito confirmado: status=paid Y settlement_status=sent. Comprueba disponivel_cents en el ámbito correcto." }, "cashin": { "title": "PIX con entrega directa en cripto", "description": "Cada solicitud de cobro puede indicar su moneda, red y billetera. Consulta las rutas y los mínimos vigentes antes de cobrar.", "sandbox_supported": true, "operations": [ "GET /cashin/catalog", "POST /cashin/preview", "GET /cashin/limits?payer_tax=CPF_DO_PAGADOR", "POST /cashin/charge com destino=cripto", "GET /cashin/{cashin_id}/status" ], "create_example": { "amount_cents": 5000, "payer_tax_number": "CPF_REAL_DO_PAGADOR", "destino": "cripto", "asset": "USDT", "chain": "polygon", "payout_address": "CARTEIRA_INFORMADA_PELO_CLIENTE", "external_id": "compra-cripto-001" }, "completion": "PIX pagado: status=paid. Envío registrado: settlement_status=sent. Confirmación on-chain registrada: settlement_proof=confirmed y settlement_confirmed_at. broadcast significa envío sin confirmación registrada; la ausencia de confirmación no demuestra un fallo. simulated es solo una prueba." }, "cashout": { "title": "Pagar PIX con cripto y recibir el comprobante", "description": "Indica una clave PIX y el importe en BRL, o la cantidad de cripto. Para pagar una solicitud de cobro existente, envía el PIX Copia y Pega completo: actualmente USDT/USDC en rutas compatibles. La persona envía la cripto después de revisar y aceptar la cotización.", "sandbox_supported": true, "operations": [ "GET /catalog", "POST /cash-outs", "POST /cash-outs/{cashout_id}/accept", "GET /cash-outs/{cashout_id}" ], "create_example": { "asset": "USDT", "network": "polygon", "amount": "10", "pix_key": "sandbox@example.invalid", "pix_key_type": "email", "external_id": "sandbox-cashout-001" }, "completion": "state=COMPLETED confirma el PIX pagado. Entrega pix_e2e y los enlaces devueltos receipt_url, receipt_pdf_url y verify_url. Los enlaces pueden aparecer después: sigue la misma orden o cashout.receipt_ready, sin un pago nuevo." }, "payout": { "title": "Pagar PIX con saldo de custodia", "description": "Usa solo el saldo BRL recibido mediante PIX, de la cuenta principal o subcuenta. Máximo R$ 6.000,00 por PIX, sujeto a límites menores de la cuenta y a las tarifas actuales de la API. El CPF/CNPJ válido del destinatario es obligatorio y puede obtenerse de una clave CPF/CNPJ válida. La billetera USDT es independiente y depende de su habilitación; sus límites proceden de la cotización, no de este máximo.", "sandbox_supported": true, "operations": [ "GET /keys/me", "GET /saldo?customer_ref=CLIENTE", "POST /payouts", "GET /payouts/{payout_id}" ], "create_example": { "amount_cents": 5000, "pix_key": "CHAVE_PIX_DO_DESTINATARIO", "pix_key_type": "email", "customer_ref": "cliente-42", "external_id": "saque-pix-cliente42-001", "tax_number": "CPF_OU_CNPJ_VALIDO_DO_RECEBEDOR", "funding_source": "pix_brl" }, "completion": "Payout confirmado: status=sent. Ante un timeout, conserva external_id y consulta la orden original. En 409 external_id_divergente o external_id_nao_verificavel, usa payout_id/recovery_endpoint; no generes otro ID para eludirlo. En 503 idempotencia_indisponivel, espera y consulta el mismo ID." }, "usdt_wallet": { "title": "Billetera USDT/USDC: saldo en cripto y PIX pagado con él", "description": "Deposita USDT o USDC en varias redes y paga PIX con ese saldo, mediante clave PIX o Copia y Pega. Habilitada para todas las claves de producción.", "sandbox_supported": true, "operations": [ "GET /carteira-usdt", "POST /carteira-usdt/deposits", "GET /carteira-usdt/deposits", "POST /carteira-usdt/quote", "POST /carteira-usdt/payments", "GET /carteira-usdt/payments/{payment_id}", "GET /carteira-usdt/statement" ], "create_example": { "amount": "100", "network": "tron" }, "completion": "Depósito acreditado: status=available en GET /carteira-usdt/deposits (o webhook wallet.deposit_credited). PIX pagado: status=concluido y final=true, con pix_e2e y receipt_url (o webhook wallet.payment_completed)." } }, "sandbox": { "simulates": [ "Solicitud de cobro PIX con QR que no admite pagos y pago simulado explícito", "crédito de custodia BRL y saldos retenidos", "entrega de cripto y retiro de custodia para las rutas compatibles de la instantánea", "payout PIX desde custodia", "transferencias entre subcuentas", "cotización de cash-out, aceptación y progresión de estado", "bandeja de salida de webhooks firmados, reintentos e historial de entregas" ], "does_not_simulate": [ "ejecutar operaciones reales en bancos o exchanges asociados", "precios de mercado actuales, disponibilidad de rutas o escala de riesgo de producción", "confirmaciones reales de blockchain" ], "safety": "Todos los fondos son ficticios. Confirma el PIX solo mediante POST /sandbox/cashin/{cashin_id}/pay. Nunca pagues el QR en un banco ni deposites cripto. Producción requiere proveedores reales, permisos y fondos disponibles.", "guide": "https://docs.luniumpay.com/es/sandbox", "capabilities": "GET /sandbox", "key_creation": { "request": "POST /keys/sandbox", "body_example": { "email": "you@company.com", "name": "my-integration" }, "required": [ "email" ], "email": "El correo electrónico de la persona que hará las pruebas. El soporte de LuniumPay envía un mensaje aproximadamente un minuto después: qué es LuniumPay, la integración en 3 pasos, manual y PDF, diagrama de flujo y VendaCripto. Un mensaje por dirección, con enlace para darse de baja. Pídeselo a la persona; nunca inventes ni reutilices una dirección.", "missing_email": "HTTP 400 erro=email_obrigatorio, acao=corrigir, campo=email", "still": "Una llamada, sin aprobación ni necesidad de clave de API." }, "scenarios": [ "success", "delayed", "held", "expired", "refunded", "failed", "payer_mismatch", "settlement_failed", "settlement_uncertain", "route_unavailable", "provider_unavailable" ], "demo_tools": [ "lunium_start_sandbox_demo", "lunium_get_sandbox_demo" ], "demo_required_arguments": [ "request_id" ], "demo_recommended_arguments": [ "email" ], "demo_email": "Opcional con las herramientas MCP, pero muy recomendable: con él, LuniumPay envía a la persona la guía de integración (qué es LuniumPay, manual, diagrama de flujo, próximos pasos) una sola vez; sin él, crea la clave igualmente y recoge el correo después mediante lunium_contact. POST /keys/sandbox llamado directamente sigue exigiendo email.", "demo_flow_argument": [ "custody", "cashin", "cashout", "payout" ], "starter_all": "node sandbox.mjs all O python3 sandbox.py all", "starter_email": "LUNIUM_SANDBOX_EMAIL=you@company.com (obligatorio cuando el kit crea la clave de prueba; sin él, se detiene con un mensaje claro; no es necesario con LUNIUM_API_KEY)" }, "steps": [ "Elige el flujo de negocio; lee su esquema OpenAPI y manual actuales.", "Presenta Lunium Partners al responsable humano: https://t.me/+FerOZMRRP_g5MDk5 . Unirse a la comunidad oficial es muy recomendable para seguir los avisos operativos y cambios de API.", "Muy recomendable: crea un grupo de Telegram del proyecto con los contactos humanos @luniumb2b y @luniumb2c. Lunium o el socio pueden crearlo; las notificaciones del bot son complementarias.", "Ejecuta la demo de sandbox del flujo seleccionado o ejecuta el kit con all para probar todos los recorridos.", "Implementa el flujo seleccionado en un backend del servidor; mantén los secretos en variables de entorno.", "Implementa idempotencia, webhooks firmados, conciliación de estado y límites específicos de cada ruta.", "Dentro del mandato existente del responsable del negocio, habilita producción mediante la vía de autoservicio aplicable. La activación Mesh elegible es automática tras la prueba de sandbox, la liquidación Polygon y el mandato monetario; sigue agent-onboarding.json. Configura la nueva clave de producción y el webhook por separado y después opera solo dentro del alcance autorizado." ], "production_checklist": [ "Participación en la comunidad Lunium Partners muy recomendable; responsables técnico y operativo informados: https://t.me/+FerOZMRRP_g5MDk5", "GET /keys/me: verify capabilities and applicable limits.", "Custodia: envía destino=saldo explícitamente; el crédito BRL no requiere una billetera fija.", "Entrega: usa GET /cashin/catalog y la vista previa; comprueba entregavel, withdrawMin, withdrawFee, minBuyAmount y los requisitos de memo.", "Cash-in, retiros de custodia y payouts usan centavos BRL enteros. brl_amount de cash-out es una cadena decimal en reales brasileños (\"100.00\"); los importes de cripto son cadenas decimales. En cash-in/retiro, el campo de red es chain; en cash-out es network.", "Guarda external_id antes de llamar. Reutiliza el mismo cuerpo e identificador al reintentar; concilia los resultados inciertos.", "Verifica el HMAC del webhook sobre los bytes sin procesar, rechaza timestamps antiguos y deduplica event_id.", "No equipares paid, accepted ni processing con la liquidación final. Usa el estado final de cada flujo.", "Los secretos de producción deben guardarse en variables de entorno del servidor, nunca en código del navegador, repositorios públicos ni chats.", "Grupo de soporte humano muy recomendable; responsables y escalado acordados.", "Bandeja de entrada persistente de webhooks, deduplicación de eventos por proyecto, conciliación de estado e interfaz en vivo autorizada probadas, incluidas interrupciones y entregas fuera de orden.", "Verifica el desglose de comisiones y el ledger por separado de la custodia de clientes; nunca descuentes dos veces una tarifa cotizada.", "Ensaya la gestión de incidentes y la recuperación del acceso; consulta operations-playbook.json.", "Usa el contrato OpenAPI publicado, no capacidades futuras del panel ni supuestos de precios sin fecha." ], "starters": { "node": "https://docs.luniumpay.com/es/starter/sandbox.mjs", "python": "https://docs.luniumpay.com/es/starter/sandbox.py", "curl": "https://docs.luniumpay.com/es/starter/curl.md" }, "kit": "https://docs.luniumpay.com/es/starter/lunium-starter.zip", "chatgpt": { "mcp_url": "https://api.luniumpay.com/mcp/onboarding", "authentication": "ninguna para el endpoint público de incorporación", "tools": "Plan de integración, catálogo público, demo de sandbox y contacto con consentimiento. Sin operaciones de cuentas de producción.", "setup": "En una cuenta/workspace elegible de ChatGPT, habilita Developer Mode y añade la URL HTTPS MCP en los ajustes de conexión de aplicaciones/plugins. La disponibilidad depende de la cuenta y de la política del workspace.", "without_connector": "Pega las instrucciones de integración y la URL de documentación en ChatGPT o en tu agente de programación. Ejecuta el código generado en tu propio backend.", "production": "La conexión de incorporación no autoriza el acceso a cuentas de producción. El MCP completo admite X-API-Key configurada en el host; la vinculación de cuentas mediante OAuth de ChatGPT no está implementada.", "official_setup": "https://developers.openai.com/plugins/deploy/connect-chatgpt", "official_auth": "https://developers.openai.com/plugins/build/auth" }, "human_support": { "strongly_recommended": true, "api_requirement": false, "group_created_by": [ "Lunium", "equipo del socio" ], "human_contacts": [ "https://t.me/luniumb2b", "https://t.me/luniumb2c" ], "notification_bot": "https://t.me/LuniumNotifyBot", "guide": "https://docs.luniumpay.com/es/manual#telegram" }, "live_tracking": { "guide": "https://docs.luniumpay.com/es/manual#monitor-ao-vivo", "private_monitor": "monitor_url devuelta por GET /keys/me o POST /keys; /monitor en el grupo de Telegram vinculado", "monitor_poll_ms": 3000, "balance_poll_ms": 15000, "feed": "GET /cashin/events", "feed_kind": "Instantánea reciente del proyecto; sin cursor de repetición, no es un registro completo de transiciones ni un ledger", "partner_ui": "Backend autenticado del socio -> bandeja de entrada persistente de webhooks -> conciliación de estado -> SSE/WebSocket/consultas periódicas implementados por el socio", "public_lunium_sse_websocket": false, "recovery": [ "GET /webhooks/deliveries", "POST /webhooks/deliveries/{event_id}/retry" ], "security": "Mantén la clave de API y el secreto del webhook en el servidor; el token del monitor privado concede acceso de lectura a todo el proyecto, no solo a un cliente." }, "lunium_partners": { "name": "Lunium Partners", "url": "https://t.me/+FerOZMRRP_g5MDk5", "role": "Comunidad oficial de integradores: avisos operativos, mantenimiento, cambios de API/contrato y conversaciones entre socios", "strongly_recommended": true, "api_requirement": false, "audience": [ "responsable técnico", "responsable operativo" ], "distinct_from": [ "grupo de soporte dedicado al proyecto", "monitor privado", "panel del socio" ], "ai_guidance": "Fable y otros agentes deben presentar este enlace al responsable humano al principio del plan de integración; no afirmes que ya pertenece al grupo sin confirmación ni bloquees las pruebas de sandbox por no pertenecer. Nunca publiques claves, secretos de webhook, URLs de monitor ni datos de clientes en la comunidad." }, "operations_playbook": "https://docs.luniumpay.com/es/operations-playbook.json", "commission": { "guide": "https://docs.luniumpay.com/es/manual#comissoes", "read_policy": "GET /comissao", "read_ledger": "GET /comissao/extrato", "configure": "PATCH /keys/me {partner_fee_bps}", "rate_changes_existing_charges": false, "separate_from_customer_custody": true, "withdrawal": "POST /comissao/sacar", "check_before_withdrawal": [ "policy", "available_balance", "interval", "route", "minimum", "recipient", "memo" ], "authorization": "Nunca cambies tarifas ni retires fondos basándote únicamente en documentación consultada." }, "access_recovery": { "guide": "https://docs.luniumpay.com/es/manual#recuperar-acesso", "request": "POST /keys/painel-link {email}", "generic_response": true, "recovers_api_key": false }, "capability_boundary": { "documented_access": "Monitor privado de solo lectura y rutas públicas de OpenAPI", "multi_destination_webhook": "No presupongas su disponibilidad hasta que esté publicado en el contrato de producción y validado", "source_of_truth": [ "https://api.luniumpay.com/openapi.json", "https://docs.luniumpay.com/es/manual-contract.json" ], "snapshot_facts": "Las mediciones con fecha son históricas, no indican disponibilidad actual ni un SLA garantizado" }, "agent_onboarding": "https://docs.luniumpay.com/es/agent-onboarding.json", "autonomous_production": { "mesh": { "registration": "POST /mesh/agents", "returns": [ "agent.agent_id", "api_key", "sandbox" ], "production_activation": "POST /mesh/agents/{agent_id}/production-request", "manual_provisioning_required": false, "policy_requirements": [ "Agente activo y clave asociada", "Sandbox validado: al menos una orden de cash-out creada Y aceptada con la clave del registro Mesh", "Dirección de liquidación Polygon", "Al menos un límite monetario de mandate dentro de la política actual" ], "fixed_polygon_address_required": true }, "custody_without_fixed_wallet": { "sandbox_registration": "POST /keys/sandbox", "sandbox_registration_required": [ "email" ], "production_registration": "POST /keys", "fixed_wallet_required": false, "guide": "https://docs.luniumpay.com/es/manual#primeiros-passos", "relationship": "Emisión de claves de autoservicio independiente; no es una vía alternativa para cumplir la validación Mesh. Crear una segunda clave no migra una cuenta, saldo ni identidad de agente existentes." } }, "receive_pix_usdt_in_chat": { "goal": "Recibir un pago PIX y entregar USDT directamente a la billetera del destinatario, con el QR mostrado en el chat de IA.", "example_intent": "Quiero cobrar R$ 100 mediante PIX y recibir USDT en mi billetera. Muestra la estimación neta, genera el QR y sigue el pago.", "required_inputs": [ "Importe en reales brasileños", "CPF/CNPJ de quien pagará el PIX, cuando lo exija la ruta", "Red y billetera de destino confirmadas por el destinatario" ], "credentials": { "self_service_url": "https://luniumpay.com/es/#chave-producao", "rest_registration": "POST /keys", "requires_lunium_sales_contact": false, "full_mcp_url": "https://api.luniumpay.com/mcp", "full_mcp_authentication": "X-API-Key configurada por el host compatible, fuera del chat", "public_mcp_limitation": "/mcp/onboarding permite descubrimiento y simulación; la conexión de una cuenta de producción mediante OAuth aún no está implementada." }, "sequence": [ "Consultar GET /keys/me y GET /cashin/catalog; seleccionar USDT en una ruta entregavel=true compatible con la billetera indicada.", "Consultar POST /cashin/preview para obtener el importe neto estimado, las tarifas y el mínimo vigente. No prometer un tipo de cambio fijo.", "Guardar external_id por intención y crear POST /cashin/charge con destino=cripto, asset=usdt, chain y payout_address del destinatario.", "Mostrar la imagen QR devuelta y qr_copypaste completo, el importe BRL y expires_at. Nunca recrear el contenido del PIX mediante IA.", "El pagador paga el PIX en la aplicación bancaria. En sandbox, simular mediante el endpoint de prueba; nunca pagar un QR simulado.", "Consultar el mismo cashin_id: separar PIX recibido, envío de cripto y confirmación registrada. Presentar la cantidad, red, billetera y settlement_tx_url cuando exista." ], "recovery": [ "Timeout: consultar la solicitud de cobro original mediante external_id antes de repetir; reutilizar la misma intención.", "PIX pagado o retenido: explicar el estado y el plazo devuelto, sin pedir otro pago.", "Fallo, devolución o estado incierto: presentar el estado y la siguiente acción de la API; nunca anunciar una entrega sin evidencia." ], "measurement": [ "Clave creada", "Solicitud de cobro creada", "QR guardado (no demuestra que se haya mostrado en el chat)", "PIX pagado", "Envío de cripto registrado", "Confirmación on-chain registrada cuando esté cubierta" ] }, "pay_pix_with_crypto_in_chat": { "goal": "Descubrir mediante IA cómo pagar PIX con cripto, obtener una cotización e instrucciones de depósito y seguir el proceso hasta el comprobante.", "example_intent": "Quiero pagar R$ 100 a esta clave PIX usando mi cripto. Muestra la cotización, la red y la dirección de depósito; después, sigue el pago y entrega el comprobante.", "entry_modes": { "pix_key": "pix_key y exactamente uno de brl_amount (objetivo en BRL, decimal en cadena) o amount (cripto decimal en cadena). Revisa y aprueba el brl_amount efectivo devuelto; los redondeos pueden diferir del objetivo. Un CPF/teléfono ambiguo exige pix_key_type.", "br_code": "PIX Copia y Pega completo de una solicitud de cobro; no enviar pix_key, amount ni brl_amount junto a él. Actualmente USDT/USDC en las redes aceptadas; no sustituir un cobro rechazado por una transferencia a la clave extraída." }, "scope": "Ofrecer monedas y redes del catálogo vigente y sujetas a cotización. No todos los tokens/redes ni tipos de solicitudes de cobro PIX son aceptados. No prometer un tiempo total fijo.", "mcp_tools": [ "lunium_list_settlement_options", "lunium_quote_crypto_sale", "lunium_confirm_crypto_sale", "lunium_get_crypto_sale" ], "sequence": [ "Identificar la clave PIX y el importe en reales brasileños, o recibir br_code completo; seleccionar una moneda y red compatibles con la billetera de origen.", "Consultar el catálogo, crear una cotización con external_id persistente y mostrar BRL, cripto, destino, costes y vencimiento devueltos. Si existe copia_e_cola_buffer_usd, explicar el coste ya incluido.", "Confirmar las condiciones dentro de la autorización del usuario y aceptar la orden. Solo la respuesta de accept proporciona deposit_address y deposit_tag cuando es necesario.", "La persona envía la cantidad exacta de cripto por la red indicada, incluido el memo/tag si se devuelve, antes del vencimiento. No enviar PIX para iniciar este flujo ni reutilizar direcciones de otras órdenes.", "Seguir el mismo cashout_id: depósito detectado, confirmaciones, conversión/liquidación y PIX pagado.", "En COMPLETED, mostrar el BRL pagado y pix_e2e; entregar receipt_url, receipt_pdf_url y verify_url cuando se devuelvan. Si el comprobante se está preparando, continuar con la misma consulta." ], "recovery": [ "Timeout al crear: recuperar mediante external_id, nunca crear automáticamente una intención nueva.", "Timeout en accept: consultar la misma orden; no indicar un segundo depósito.", "MANUAL_REVIEW y PAYING_OUT no confirman PIX ni devolución; continuar el seguimiento.", "AWAITING_REFUND_ADDRESS requiere una dirección confirmada del cliente en la red indicada; deposit_from es solo informativo. Seguir REFUNDED y refund_tx_hash sin prometer el activo/importe original.", "EXPIRED sin depósito requiere una cotización nueva solo si la persona aún quiere pagar. Si existe un depósito tardío o divergente, conciliar la orden original." ], "credentials": "El MCP completo /mcp exige credenciales configuradas en el host. /mcp/onboarding solo descubre y simula; vincular una cuenta de producción mediante OAuth sigue pendiente.", "sandbox": "Probar con fondos ficticios. Nunca enviar cripto a direcciones de sandbox." } }