PRIMEROS PASOS

Documentación

Instala, acepta pagos y cuida tu servidor.

¿Acabas de llegar? Sigue las guías paso a paso →

Requisitos del VPS

Usa un VPS Linux nuevo con acceso root, no un servidor que ya aloje sitios o bases de datos. No necesitas Docker, compilador ni nodos de blockchain.

VPSMínimo
Uso ligero
Recomendado
CPU1 vCPU2 vCPU
RAM2 GB4 GB
SSD20 GB60 GB

El mínimo es un punto de partida para uso ligero con imágenes mínimas de Ubuntu/Debian, no una garantía de rendimiento. El espacio de disco incluye Linux; deja al menos 3 GiB libres antes de instalar, además de espacio para actualizaciones, historial y copias de seguridad.

El instalador nativo requiere x86-64, systemd 247+ y Python 3.9+. ARM64 y Alpine/OpenRC no están incluidos.

Versiones de Linux y notas sobre capacidad
  • Ubuntu 22.04+ o Debian 12+; Mint 21+ y Pop!_OS 22+.
  • Fedora 42+; Rocky, AlmaLinux, RHEL, Oracle Linux o CentOS Stream 9–10.
  • openSUSE Leap 16+ o Tumbleweed; Arch, Manjaro o EndeavourOS.

Elige una versión mantenida por su proveedor. Los requisitos más altos del sistema operativo tienen prioridad: openSUSE Leap 16 requiere más de 40 GB de disco.

Más redes y facturas simultáneas pueden requerir más CPU y RAM. Un VPS más grande no elimina los límites de RPC. Los flujos de instalación tienen pruebas automatizadas; las pruebas completas en VPS nuevos aún no cubren todas las distribuciones.

Instalar

Apunta estos nombres de host predeterminados a tu VPS, o elige los tuyos:

  • merchant.example.com: consola
  • pay.example.com: página de pago
  • api.example.com: API

Usa registros solo DNS durante la instalación. Abre TCP 80/443 en ambos firewalls y mantén SSH accesible. Nunca expongas PostgreSQL ni la aplicación en los puertos 5432/8080.

bash <(curl -fsSL https://releases.whollycrypto.com/setup_wholly.sh)

La instalación verifica las descargas y configura PostgreSQL, Nginx, HTTPS y los servicios. ¿Prefieres contenedores? Consulta la instalación opcional con Docker.

Comprueba primero o reanuda la instalación

Inspecciona el instalador. Añade --check al comando para comprobar la compatibilidad sin instalar, o --help para ver las opciones.

Reanuda el progreso guardado sin sustituir claves ni ajustes:

bash <(curl -fsSL https://releases.whollycrypto.com/setup_wholly.sh) --resume

Los dominios base adicionales pueden usar los mismos nombres de servicio. Los registros IPv6 también deben apuntar a este VPS. Activa un proxy de Cloudflare solo después de la validación del dominio.

Configuración inicial

  1. Introduce el acceso HTTP Basic. Crea tu cuenta de administrador, elige idioma y zona horaria y revisa la licencia y política de privacidad.
  2. Comprueba Ajustes → Conexiones de redes. Usa proveedores de respaldo independientes y en buen estado que permitan escanear pagos.
  3. Crea un proyecto y después su primera tienda.
  4. Haz una copia de seguridad de las wallets del proyecto. En la tienda, selecciona las redes aceptadas y los tokens verificados.
  5. Define moneda, confirmaciones, vencimiento, margen y tolerancia. Comprueba tu saldo de créditos antes de crear facturas.

Los QR solicitan todo el importe pendiente. La tolerancia solo acepta diferencias por defecto; las confirmaciones siguen siendo obligatorias.

Importes de stablecoins

Las nuevas cotizaciones de stablecoins reconocidas se redondean hacia arriba: 1.321 USDC → 1.33 USDC, incluso con tolerancia cero. Mínimo: 0.01 token.

Las facturas existentes, los saldos y los importes restantes de pagos parciales mantienen su precisión exacta. Los demás tokens y los personalizados conservan su precisión habitual.

Activación automática

El registro del administrador registra automáticamente tu cuenta de créditos con tu email, con un crédito de bienvenida único equivalente a 10 USD . No necesitas código de activación.

Crear una factura. La activación pendiente se reintenta automáticamente; volver a conectar nunca concede crédito de nuevo.

Datos de acceso y valores predeterminados

Tu acceso Basic Auth se guarda en /root/whollycrypto/config/setup-credentials.txt. Es independiente del email y la contraseña de la consola.

Los proyectos nuevos heredan la moneda y la zona horaria predeterminadas del sistema; las tiendas usan la moneda del proyecto. Las zonas horarias de cuentas existentes se gestionan aparte en Ajustes → Cuenta.

whollycrypto welcome muestra la URL de tu consola.

Modo comercio u operador

Las instalaciones nuevas desde 7.0.0 eligen un modo al configurar el primer administrador. No se puede deshacer; cambiar de modo requiere una nueva instalación. Las instalaciones anteriores a 7 siguen en modo comercio, incluso sin administrador.

Comercio: gestiona tus propios proyectos y tiendas. Operador: aloja comercios independientes en una instalación y cobra tu propia comisión de procesamiento prepaga. Tu negocio está incluido sin una comisión interna de operador.

Configurar comercios alojados
  1. Los nodos compartidos, tipos de cambio, dominios, créditos de instalación y actualizaciones están en el panel de operador.
  2. Abre Wallets → Crear wallets receptoras para BTC, ETH y USDC/USDT de Ethereum. Guarda ambas frases de recuperación independientes. Este proyecto dedicado no puede emitir facturas de venta; se conserva cualquier tienda receptora existente.
  3. Añade un comercio con moneda de crédito, comisión y email de administrador. Comparte la invitación y el Basic Auth del comercio de forma privada. El comercio elige su contraseña. Nunca compartas el Basic Auth del operador.
  4. Los comercios recargan desde tu página de pago, o tú registras un ajuste de crédito con una explicación. Necesitan crédito antes de crear proyectos o tiendas. Gestiona usuarios e historial de créditos en Comercios → Administrar.

La configuración del operador pide una cuarta dirección, como operator.example.com, y su propio usuario y contraseña de Basic Auth. Elige tu etiqueta, apunta el DNS al VPS, comprueba el DNS y activa HTTPS. El panel se abre directamente en esa dirección. Las direcciones de comercio, pago y API siguen separadas.

Usa el nuevo acceso Basic Auth del operador y después tu email y contraseña de administrador. El Basic Auth del comercio no cambia. La configuración puede reanudarse tras errores de DNS o certificados. Los operadores que actualicen desde 7.0.0 también deben completar este paso; las direcciones activas existentes siguen disponibles.

Comisiones, aislamiento y responsabilidad

Al 3%, una factura de 100 EUR cuesta 3 EUR de crédito del comercio. Si su moneda de crédito es otra, se guarda el tipo de cambio fiat del momento de creación junto con la comisión.

El operador paga por separado la comisión habitual de la instalación de Wholly Crypto. Los fondos del cliente no se dividen en la blockchain. Las compras de créditos no se vuelven a cobrar.

Solo una liquidación verificada automáticamente acredita una recarga. Abrir una página de pago o aceptar manualmente una factura no lo hace. Las reversiones crean asientos contables; si una recarga revertida vuelve a recibirse, requiere revisión del operador.

Un crédito bajo del comercio alojado pausa IPN, webhooks, envíos de fondos y la creación de nuevos proyectos o tiendas. Las facturas de clientes existentes y la recepción continúan. Un crédito bajo de instalación puede pausar las automatizaciones de todos los comercios alojados. Deshabilitar un comercio también bloquea el acceso y las nuevas facturas, mientras los pagos anteriores siguen bajo seguimiento.

Este aislamiento se aplica en la aplicación; no hay un VPS independiente por comercio. Los comercios no pueden acceder a los proyectos, wallets, credenciales API, exchanges ni créditos de otros. El administrador del servidor puede acceder a las claves de las hot wallets alojadas. Informa a los comercios antes de incorporarlos; usa un alojamiento de confianza, copias independientes y capacidad adecuada para cargas compartidas.

Finanzas e invitaciones del operador

Disponible en modo operador desde 7.1.0.

Wallets y finanzas

Desde 7.2.0, Wallets gestiona saldos receptores, direcciones y copias de seguridad; Envío de fondos gestiona envíos y reglas automáticas. Guarda ETH para las comisiones de tokens. Recargas de comercios registra sus compras. Los créditos del encabezado pagan por separado las comisiones de instalación. Mi negocio abre tu propia consola en una nueva pestaña.

Abre Finanzas para ver comisiones ganadas, cargos verificados de instalación, margen estimado y créditos actuales de los comercios. Filtra por fecha, comercio o moneda del informe; exporta CSV.

Los informes agrupan las facturas por su primera liquidación y reflejan sus últimas reversiones de comisión. Los saldos prepagos no son ingresos. Los cargos de tu propio negocio van por separado. Los cargos pendientes o tipos de cambio ausentes dejan los márgenes afectados sin calcular. Las conversiones usan los tipos fiat actuales en caché; no incluyen gas ni costes operativos.

Invitar usuarios o restablecer contraseñas

Añadir comercio crea una invitación. Desde 7.3.0 puedes elegir un crédito inicial gratuito en la moneda de crédito del comercio; se permite cero. Esto no recarga tu saldo de operador. Enviar invitación por email está marcado de forma predeterminada.

Configura tu proveedor SMTP en Ajustes → Email de invitación primero, usando TLS o STARTTLS. La prueba de conexión no envía emails. También puedes desmarcar el email y compartir el enlace de forma privada. Un fallo de email conserva la cuenta y el crédito; no vuelvas a crear el comercio.

Para generar otro enlace o restablecer una contraseña, abre Comercios → Administrar → Cuentas de usuario. La aceptación SMTP no garantiza la entrega en la bandeja de entrada. Comparte el Basic Auth del comercio por separado, nunca las credenciales del operador.

Las invitaciones duran 48 horas; los restablecimientos, una hora. Cada enlace funciona una vez. Sustituye o revoca un enlace desde la misma pantalla. Un restablecimiento cierra las sesiones existentes, pero mantiene 2FA activado. Sigue siendo obligatorio el Basic Auth del comercio.

API de operador

Automatiza los comercios alojados con SDK 2.6.0 y Wholly Crypto 7.4.0+. Activa Operador → Ajustes → API de operador, y crea una clave de servidor con permisos limitados.

Incorporación, permisos y reintentos seguros

Crea cuentas directamente con contraseña o envía invitaciones. Gestiona usuarios, proyectos, tiendas, comisiones y créditos prepagos locales; consulta informes y suscríbete a eventos firmados del ciclo de vida. Se mantienen el consentimiento de custodia del primer acceso, 2FA y el aislamiento entre comercios.

Cada escritura necesita una clave de idempotencia guardada. Las concesiones de crédito son ajustes locales de cuenta, no recargas de instalación. Los secretos de wallets, los envíos y la configuración del servidor quedan fuera de esta API.

Usa api.your-domain.com/v1/operator. Mantén las claves de operador en tu backend, nunca en un navegador ni en manos de un comercio alojado.

Referencia y permisos de la API de operador → · SDKs de PHP, Python y Node con ejemplos →

Wallets y tokens

Ajustes → Tokens carga primero 250 tokens y después el resto del catálogo.

Proyecto → Wallets → Copia de seguridad de todas exporta TXT o HTML sin conexión con búsqueda y códigos QR. Ambos exponen claves y frases de recuperación. Guarda una copia privada fuera del servidor; nunca la compartas ni la subas a ningún sitio.

Root puede acceder a las claves. Las guías de recuperación de wallets explican las direcciones de facturas, el gas nativo y las copias externas de Monero/Lightning.

Direcciones guardadas y saldos actualizados

Ajustes → Libreta de direcciones: guarda una red y dirección. Las monedas nativas y los tokens coincidentes de CoinGecko aparecen automáticamente. Es de solo lectura y lo gestiona el administrador; no cambia la aceptación en el pago.

Los lectores de tokens cubren 22 redes. Los saldos privados y las capas de Bitcoin/CashTokens/Kaspa requieren acceso o indexadores independientes. Las lecturas fallidas muestran errores, no ceros.

Reúne los saldos de facturas en otra wallet con envíos manuales o automáticos de fondos. Las transferencias de tokens también necesitan la moneda nativa de la red para las comisiones.

Precio no disponible se refiere a tipos de cambio, no a saldos.

Añadir un token personalizado
  1. Tienda → Métodos de pago → EVM o Solana → Token personalizado.
  2. Introduce contrato/mint, nombre y símbolo. Elige precio fijo en USD o precio automático de DEX.

Se verifican la red y los decimales. Los precios del proyecto no cambian las cotizaciones existentes. Una coincidencia en el catálogo por sí sola no activa el pago.

Precios automáticos

DEX Screener requiere un pool con el contrato exacto, $10,000 de liquidez y una operación durante la última hora. Los precios se actualizan cada minuto; un fallo o una antigüedad de cinco minutos bloquea nuevas cotizaciones.

Los precios de DEX pueden manipularse; las comprobaciones no son auditorías. Usa tokens ERC-20 estándar o SPL clásicos de confianza. Token-2022 y las extensiones no son compatibles. Sin un pool adecuado, usa precios fijos.

Moneda y zona horaria

Ajustes → Sistema → Valores regionales predeterminados define la moneda y zona horaria de nuevos proyectos y la zona horaria de nuevas cuentas. Los ajustes y créditos existentes no cambian; la moneda del panel sigue pudiendo ajustarse.

Zona horaria personal: Ajustes → Cuenta → Editar usuario.

Crear una factura

Usa Métodos de pago → Elegir para esta factura para limitar las redes y tokens aceptados. Todos los métodos de pago de la tienda mantiene los valores predeterminados.

  1. Abre Proyecto → Facturas → Crear factura.
  2. Elige la tienda, la moneda fiat y el importe.
  3. Comparte el enlace de pago. Tu cliente elige una red y token disponibles y ve el QR, el importe restante, el vencimiento y las confirmaciones.

Prueba un pago pequeño con cada método antes de empezar a operar. Comprueba la factura antes de entregar un pedido: una URL de retorno no demuestra que se haya pagado.

Para integraciones, verifica los IPN/webhooks firmados y confirma el estado mediante la API de facturas. Trata los eventos duplicados como un mismo evento.

API: filtra payment_methods por chain_slug y asset_tickers. Se ignoran las opciones inactivas; si no hay coincidencias, se usan los valores de la tienda. Filtrar solo por red incluye todos sus activos activos. Los símbolos compartidos requieren IDs de activos. Siguen siendo necesarios wallets y tipos de cambio.

Importes y confirmaciones

¿Escáner desconectado? Las facturas mantienen los métodos configurados mientras espera la detección. Comprueba las API compatibles en Conexiones de redes; estar en buen estado no significa ser compatible con el escáner. Por defecto: dos proveedores independientes.

Siguen siendo necesarios wallets y tipos de cambio. Los servicios Monero/Lightning deben emitir solicitudes de pago.

Los errores de API/MCP incluyen error.details.payment_methods. SDK 2.4.0 añade explicaciones seguras: PHP getPaymentMethodIssues(), Python payment_method_issues, Node paymentMethodIssues. Referencia de errores →

Las cotizaciones cripto se redondean hacia arriba e incluyen el margen de la tienda. Una factura con precio fiat no convierte la cripto recibida en saldo bancario.

Cero confirmaciones liquida el pago al detectarlo, sin la protección de las confirmaciones de red. Los pagos nativos EVM se detectan como transferencias directas. Revisa pagos inusuales o inciertos en Requiere atención.

API de escaneo

Comprueba Conexiones de redes para ver API compatibles, historial completo y proveedores independientes. Ponerse al día desde un nodo sin procesar lleva tiempo. Todas las API de recepción →

Pagos, saldos y mantenimiento comparten los límites de los proveedores. Las comprobaciones inactivas se espacian. Las facturas antiguas mantienen el seguimiento de pagos tardíos y reorganizaciones, hasta una vez por hora después de ponerse al día. Los avisos WSS disponibles complementan el escaneo HTTP. Cerrar la página de pago nunca detiene la detección. Los nodos públicos siguen teniendo límites; Wholly Crypto no opera nodos.

Facturas de importe cero

Bloqueadas por defecto. Activa Tiendas → Factura → Permitir facturas de importe cero para permitir totales cero manuales o por API. Se completan inmediatamente, sin pago, dirección receptora, transacción ni comisión de procesamiento.

Página de pago

Tienda → Página de pago: colores, logos, métodos, enlaces, tamaños de letra de Intro/Outro y visibilidad del nombre de proyecto o tienda. Las tiendas nuevas heredan el diseño de la tienda predeterminada. Los cambios se guardan solos.

Las vistas previas no pueden aceptar pagos. No se permite HTML/CSS/JavaScript personalizado.

Prueba la demo.

IPN y webhooks

IPN envía cada evento de factura a la URL de la tienda o al ipn_url de la factura. Los webhooks envían eventos seleccionados. Ambos envían por POST la misma instantánea JSON.

¿Cuándo debo entregar el pedido? Para el procesamiento por eventos, usa event_type = invoice.settled con status = settled. Verifica la factura actual y tu pedido, y entrega una sola vez. payment.received por sí solo no basta.

Estado frente a eventos: ejemplos de Ethereum y Solana

status es el estado de la factura al crear el evento; event_type indica qué ocurrió.

  • Ejemplo de Ethereum: payment.received + processing, después invoice.settled + settled.
  • Ejemplo de Solana: ya es definitivo al detectarse, por lo que payment.received y invoice.settled ambos incluyen settled.

Cualquiera de los flujos puede ocurrir en otras redes. Son eventos distintos, no necesariamente dos pagos. Pueden compartir sequence pero tener distintos valores de event_id . El orden de entrega no está garantizado; no exijas processing primero.

Estados y datos de notificación
Estado de la facturaSignificado
newEsperando el pago
processingPago parcial o esperando finalidad
settledAceptado según las reglas de la factura o manualmente
expiredPlazo vencido; el seguimiento tardío puede continuar
invalidEl pago requiere revisión o se ha rechazado
cancelledCancelado, no reembolsado

Eventos: invoice.created, payment.received, invoice.processing, invoice.settled, invoice.expired, invoice.invalid, invoice.cancelled. Tabla completa de eventos y reglas de excepción →

amount_status: none, partial, paid, overpaid. paid incluye la tolerancia, no la finalidad. timing_status: on_time o late. resolution: automatic, manually_settled o manually_invalidated. Aplica tu política de excepciones cuando requires_review sea true.

invoice_id coincide con la respuesta de la API. amount, currency y order_id describen tu pedido original. payment_info añade transferencias, importes cripto exactos, cotización/margen/tolerancia fijados y tipos de cambio orientativos. Los datos del cliente y los metadatos son privados.

paid_chain, paid_asset, paid_payment_method_id, paid_asset_amount, paid_asset_amount_received y settlement_exchange_rate resumen la liquidación. Permanecen fijos; la evidencia o el historial ausentes quedan en null. Para recibos posteriores usa payment_info o la API de pagos.

Usa cadenas decimales. Nunca combines activos ni trates fondos sin confirmar como si faltaran. Gestiona las excepciones explícitamente; una advertencia por sí sola nunca autoriza la entrega ni el reembolso. Las recargas internas de gas verificadas no son pagos de clientes y no activan payment.received.

Secretos de firma, reintentos e historial de entregas

Secretos de firma separados: Tienda → IPN firma las entregas IPN, incluido el valor personalizado de la factura para ipn_url. Cada endpoint de Tienda → Webhooks tiene su propio secreto, que se muestra al crearlo o rotarlo.

Ambos usan Wholly-Signature y el mismo verificador del SDK, pero necesitan el secreto correspondiente, no una clave API. Rotar el secreto IPN no cambia los secretos de webhooks.

Verifica el cuerpo sin modificar, la marca de tiempo y el ámbito de proyecto y tienda. Guarda de forma duradera y devuelve HTTP 2xx. Un worker consulta la factura actual mediante el host API configurado y entrega una sola vez dentro de una transacción de base de datos. Los encabezados no están firmados; usa la identidad firmada del cuerpo de la versión 2.

Por eventos: elimina duplicados del valor firmado event_id, y después filtra invoice.settled. Por estado con SDK: agrupa proyecto + invoice_id + sequence, y comprueba el estado sin importar el tipo de evento. No añadas un filtro de eventos después de agrupar. Ambos requieren protección independiente contra duplicados por pedido.

Los reintentos conservan el cuerpo y el ID del evento originales. Las revisiones anteriores no deben sobrescribir las nuevas. IPN realiza hasta ocho intentos; los reintentos de webhooks son opcionales. El crédito bajo pausa las entregas, no los pagos.

Tienda → IPN / Webhooks → Historial → Detalles muestra el cuerpo guardado y el resultado. Los datos caducan a los 90 días. Un reenvío no demuestra la liquidación.

Datos completos, tabla de eventos y ejemplos del receptor →

Conversión mediante exchange

Envía activos compatibles a Kraken, Binance o Coinbase. Conserva la moneda o convierte los depósitos acreditados. El dinero fiat permanece en el exchange.

Los mínimos de depósito se aplican por transacción, no por envío de fondos. Los depósitos por debajo del mínimo detienen el plan. Consolida primero los saldos pequeños en tu propia wallet; se aplican comisiones de red adicionales.

Conecta y elige una ruta
  1. Ajustes → Exchanges: conecta una clave dedicada, comprueba los saldos y concede acceso a proyectos. Sin permisos de retirada; restringe la clave a la IP de tu VPS.
  2. Proyecto → Envío de fondos: verifica activo, red, dirección y contrato del token. Para cada red y token, elige otra wallet o un exchange.

Los mercados se actualizan cada dos minutos. Solo se convierten depósitos identificados y acreditados; los mercados desactualizados detienen nuevas órdenes. Una reserva del 1% del activo de origen permanece en el exchange para comisiones y redondeos, aparte de los créditos de procesamiento.

Mantener importe mínimo reserva monedas o tokens en todo el proyecto tras los envíos automáticos. Es independiente del umbral; cero no reserva nada. Las comisiones usan el excedente. Los envíos manuales no cambian.

Reanuda las transferencias inciertas; nunca las sustituyas. Las wallets siguen reservadas hasta la confirmación o hasta que venza una cotización no usada. Los envíos grandes necesitan lotes.

Se aplican la custodia del exchange, KYC, restricciones regionales y comisiones. Sin pagos a bancos ni apalancamiento. El crédito bajo pausa nuevas conversiones; las órdenes enviadas siguen conciliándose.

Créditos de procesamiento

Sigues recibiendo pagos aunque se agoten los créditos. Las tiendas existentes mantienen facturas, página de pago y seguimiento de pagos. La falta de una conexión de facturación verificada o la suspensión de la cuenta son casos distintos y pueden bloquear nuevas facturas.

Sigue disponibleEn pausa sin crédito utilizable
Facturas, página de pago y confirmacionesIPN/webhooks, incluidos los reintentos
Wallets, saldos y copias de seguridadEnvío de fondos: envíos, gas, reembolsos y nuevas conversiones en exchanges
Informes, API de lectura y ajustes existentesCreación de proyectos y tiendas
Comprobación de actualizaciones y recuperación de actualizaciones interrumpidasInstalación de nuevas versiones

Recarga desde el icono de créditos. Tras verificar la recuperación, se reanudan las automatizaciones activadas, incluidas las reglas que envían fondos. Desactiva las reglas que no quieras reanudar.

Recargas automáticas de créditos

Abre Recarga automática después de Solicitudes. Elige una wallet receptora con copia de seguridad, umbral, importe de compra, límite diario y límite de comisión de red. Autoriza y guarda. Empieza desactivada.

Usa BTC, ETH o USDC/USDT de Ethereum cuando se ofrezcan. Las direcciones que envían tokens necesitan ETH; esta regla no aporta el gas que falte. Los operadores usan wallets receptoras dedicadas; los comercios alojados pagan a su operador.

La recarga aprobada puede ejecutarse mientras el crédito bajo pausa el envío de fondos. Solo el servicio receptor confirma el crédito. Se ejecuta una compra automática a la vez. Desactivar detiene el trabajo no enviado, no las transacciones ya enviadas.

Recuperar un pago automático

En Recarga automática, usa Comprobar pago. Reanuda el mismo pago válido o cierra una transferencia Ethereum cuyo fallo esté verificado y pausa la regla. Los pagos pendientes o inciertos siguen retenidos para evitar envíos duplicados. Una cotización vencida no demuestra un fallo.

Comisiones y recuperación del acceso completo

El 1% predeterminado usa el valor fiat original de la factura liquidada. Los pagos cripto del cliente no se dividen.

Las comisiones siguen acumulándose hasta generar un saldo negativo. Cubre el importe negativo y restablece crédito utilizable por encima del umbral de cortesía de tu cuenta. Los cambios de saldo suelen aparecer en 10–15 segundos con una conexión en buen estado.

Instalar actualizaciones requiere crédito verificado mayor que cero, incluso si hay un margen de cortesía para automatizaciones. Las recargas nunca instalan actualizaciones automáticamente.

Las notificaciones en pausa no consumen intentos. Se reanudan las entregas retenidas; sigue aplicándose la caducidad normal. Concilia los eventos perdidos mediante la API de facturas.

Si el operador desactiva las comisiones de procesamiento, no se aplican nuevas comisiones ni restricciones de crédito. Los cargos anteriores permanecen en el historial. Una instalación sin vincular puede configurar proyectos y tiendas, pero necesita facturación verificada para emitir facturas. Las facturas ya emitidas siguen bajo seguimiento.

Informes

Los gráficos de ingresos y los filtros permanecen sobre las pestañas: Proyectos y tiendas, Facturas, Wallets y Envíos de fondos. Busca debajo. Proyectos y tiendas incluye exportaciones CSV. Las fechas personalizadas abarcan hasta 366 días. Las wallets usan saldos en caché.

Cómo funcionan las cifras de los informes
  • Los ingresos muestran los valores de facturas liquidadas antes de comisiones y reembolsos, usando las fechas de liquidación. No son el saldo de las wallets ni las ganancias.
  • Las conversiones usan tipos de cambio actuales en caché, no tipos contables históricos. Los totales en la moneda original siguen disponibles si faltan tipos de cambio.
  • Los gráficos de estado usan las fechas de creación de las facturas. Las cifras de Requiere atención muestran los problemas actuales sin resolver.

Asistentes de IA · MCP

Acceso opcional limitado al proyecto en api.example.com/mcp. Consulta pagos o aprueba la creación de facturas. Configuración y permisos de MCP →

SDKs

Usa nuestros SDKs oficiales para crear facturas, consultar pagos y verificar IPN/webhooks.

SDK de PHP

PHP 7.4+

Añade pagos cripto a tu aplicación PHP con Composer.

composer require whollycrypto/php-sdk
GitHub y ejemplos ↗

SDK de Python

Python 3.10+

Conecta tu aplicación o backend Python sin dependencias de ejecución.

python -m pip install whollycrypto
GitHub y ejemplos ↗

SDK de Node.js

Node.js 22+

JavaScript o TypeScript, un paquete npm con tipos integrados.

npm install whollycrypto
GitHub y ejemplos ↗

Usa el dominio API de tu instalación y mantén las claves API en el servidor. Todos los SDKs tienen licencia MIT.

Envío de fondos

Mueve los fondos recibidos al destino que elijas. Gestiona reglas e historial en Proyecto → Envío de fondos.

Envía monedas nativas en 29 redes; Monero sigue siendo de solo lectura. Tokens: ERC-20 verificados y SPL clásicos. Los envíos manuales y automáticos usan las mismas protecciones.

Envío manual: prepara, revisa y aprueba

BTC, EVM, SOL y TRX se suman a 18 adaptadores nativos. Usa un proveedor capaz de transmitir transacciones. ZEC solo admite direcciones transparentes; ADA conserva las salidas de tokens; DOT usa Asset Hub; HBAR necesita un relay. Los destinos salientes que requieren memo/tag/comentario necesitan una wallet externa.

  1. Abre Proyecto → Wallets → activo → Enviar. Elige una entrada de la libreta de direcciones o introduce un destino. Comprueba la dirección completa y la red.
  2. Elige un importe exacto o enviar el disponible, y después un nivel de comisión. Para tokens compatibles, Usar ETH del proyecto para gas (o la moneda nativa de la red) puede aportar las comisiones que falten desde el mismo proyecto y red.
  3. Haz clic en Preparar transferencia. Revisa orígenes, destino, importe, comisiones máximas y cualquier asignación de gas. Aprobar y enviar autoriza este plan; prepararlo no envía nada.

La provisión de gas, las confirmaciones y el envío de tokens continúan en segundo plano tras la aprobación. Sigue Actividad de transferencias, incluso tras cerrar la ventana. La transmisión no es una confirmación.

Conservar ETH en la wallet del proyecto: 0 no añade una reserva; no gasta todo tu ETH. 0.005 conserva al menos 0.005 ETH para después, por lo que necesitas fondos adicionales para este flujo. Las reglas automáticas guardadas no cambian.

Configuración de envíos automáticos
  1. Abre Configuración de envíos automáticos → activo → Configurar. Elige una dirección de wallet o un destino de exchange compatible, no ambos.
  2. Define el mínimo de envío y Mantener importe mínimo. Ejemplo: activar a 100 USDC, conservar 20 USDC, enviar hasta 80 USDC. La reserva se aplica a todo el proyecto, no a cada dirección.
  3. Para tokens, revisa Usar ETH del proyecto para gas e introduce un Límite diario de provisión de fondos. Activa Envío automático y después Guardar regla y confirma. Abrir Configurar no activa nada por sí solo.

El límite diario restringe el gas nativo asignado por regla de token durante 24 horas móviles. €1 puede servir como límite inicial para uso ligero, no como coste garantizado ni cargo diario. Las transacciones de provisión de fondos también tienen comisiones. Comisión de red máxima % puede limitar la suma de comisiones de provisión y transferencia.

Las comprobaciones se ejecutan automáticamente. Solo reciben gas las direcciones aptas que tienen tokens; las vacías no. Una dirección sin fondos suficientes y por debajo del mínimo de envío espera. Explicación de los límites de gas →

Buenas prácticas y transferencias en pausa
  • Haz copias de seguridad de las wallets y prueba una transferencia pequeña. Envía los tokens antes de vaciar las monedas nativas. El ETH de otra parte del proyecto debe llegar primero a cada dirección con tokens; el gas no usado permanece en tus wallets.
  • Usa saldos recientes, proveedores en buen estado y fondos nativos suficientes. Las reglas automáticas necesitan una wallet activa con copia de seguridad y el activo habilitado en una tienda habilitada. Un saldo bajo de créditos de procesamiento puede pausar los envíos.
  • En Actividad de transferencias, revisa el progreso, Provisión de gas y los enlaces al explorador. Si el resultado es incierto, actualiza la misma transferencia; no crees otra para sustituirla. Reanuda solo tras revisar el motivo y los límites.

¿Envío desactivado? Comprueba whollycrypto transfers status. Revisa cada regla activada antes de whollycrypto transfers enable: se aplica a todo el servidor y puede ejecutar inmediatamente las reglas guardadas. Detener pasos futuros no revierte las transmisiones.

Dominios

Ajustes → Sistema: elige Administrar o Añadir dominio. Guarda, revisa el DNS y publica. Los hosts sin cambios omiten las comprobaciones DNS/SSL.

Dominios de la tienda

Tienda → Básico: elige hosts activos de comercio/pago/API. Los enlaces priorizan tienda → tienda predeterminada → sistema; los nombres retirados usan alternativas. Configura los hosts del SDK por separado. Los reintentos firmados conservan sus enlaces originales.

HTTPS es automático. Activa Cloudflare después de configurar; Let's Encrypt sigue activo.

Lista de comprobación de Cloudflare
  • Usa Full (strict), no Flexible; no necesitas clave API.
  • Desactiva la caché y los desafíos de navegador/bots para consola, pago y API.
  • Permite /.well-known/acme-challenge/ en el puerto 80 sin redirecciones ni desafíos para las renovaciones.

Las comprobaciones consultan el DNS autoritativo y verifican el origen: Directo o Cloudflare. Los visitantes pueden tener DNS anterior en caché.

Guardar y eliminar en la consola usa POST desde 5.6.2; no hace falta una excepción «Not GET or POST». El inicio de sesión y CSRF siguen activos. En api.*, permite los métodos documentados de la API pública.

Seguridad de la cuenta

Configura 2FA en Ajustes → Cuenta. Los usuarios limitados a proyectos usan Mi seguridad en el pie de página. Confirma tu contraseña, escanea el QR o la clave TOTP e introduce un código de seis dígitos.

Prueba Verifyr Authenticator para iOS o Android, u otra aplicación TOTP estándar. Guarda los códigos de recuperación de un solo uso separados de tu contraseña. Mantén activada la protección HTTP Basic.

Recuperación y apariencia

Sustituir códigos o desactivar 2FA requiere tu contraseña y un autenticador o código de recuperación sin usar. Se cierran las demás sesiones. Mantén sincronizados los relojes del teléfono y el servidor; 2FA no protege un servidor comprometido.

El icono de tema alterna entre Claro → Atenuado → Oscuro y recuerda la elección de este navegador. Los temas de pago de las tiendas son independientes.

Seguridad del servidor

  • Usa claves SSH y restringe SSH a IP de confianza. Mantén una conexión de recuperación probada.
  • Activa el proxy de Cloudflare después de configurar, usando Full (strict).
  • En Ajustes → Sistema → Restricciones de IP de origen, permite IP o rangos de confianza por cada nombre de host activo de merchant.* o api.* . La IP actual de la consola debe seguir permitida.
  • Normalmente deja pay.* abierto: los clientes necesitan pagar desde cualquier lugar.
Cloudflare y recuperación de acceso

Opcionalmente añade reglas de acceso de Cloudflare. Excluye los desafíos de renovación HTTPS; evita desafíos de acceso interactivos en API y pago. El modo proxy por sí solo no es una restricción de IP.

¿Te has quedado sin acceso? Ejecuta whollycrypto access-reset --domain merchant.example.com por SSH. Solo se vuelve a abrir ese nombre de host, en cinco segundos; la autenticación de cuenta sigue activada.

Reparar HTTPS

whollycrypto ssl
whollycrypto ssl --fix

El primer comando comprueba los certificados activos. --fix repara los archivos de soporte TLS y renueva certificados ausentes o próximos a vencer. Nginx debe estar en ejecución; mantén abiertos los puertos 80/443.

Reemitir un certificado

Ejecuta whollycrypto ssl --domain merchant.example.com --reissue para forzar su sustitución. Se aplican límites de emisión. Si Cloudflare bloquea el desafío HTTP, usa temporalmente solo DNS. Wallets, autenticación y dominios no cambian.

Comprobaciones diarias

  • En Requiere atención, selecciona facturas o la página actual para marcarlas como revisadas, añadir una nota o volver a escanear. Las decisiones financieras siguen siendo individuales.
  • Vigila el espacio en disco, el retraso de los escáneres y los nodos alternativos independientes. Los endpoints públicos no garantizan capacidad.
  • Mantén Linux actualizado, restringe SSH y limita usuarios y claves API a los proyectos y permisos necesarios.

Las decisiones necesitan un motivo. Los reembolsos requieren una transferencia confirmada independiente; cambiar el estado de una factura nunca envía dinero.

Actualizaciones y copias de seguridad

Lee las notas de la versión, y después usa Ajustes → Sistema → Actualizaciones de software o la CLI. Las actualizaciones verifican firmas, crean copias de seguridad y comprueban el estado. La página de pago se pausa durante la instalación.

whollycrypto update --check
whollycrypto update

Las actualizaciones esperan hasta dos minutos a las tareas en segundo plano; el pago sigue disponible. Si se agota el tiempo, se restauran los temporizadores.

Actualizar desde 0.1.31 o anteriores

¿El actualizador antiguo está bloqueado? Ejecuta esto una vez. La clave instalada verifica el asistente.

bash <(curl -fsSL https://releases.whollycrypto.com/update_wholly.sh)

Mantén copias probadas fuera del servidor de PostgreSQL, configuración, claves de cifrado de wallets y exportaciones de wallets. Los archivos locales de recuperación no están cifrados.

Restaura juntas las copias correspondientes de base de datos y configuración. Nunca interrumpas migraciones ni ejecutes binarios antiguos con bases de datos más nuevas. Las reglas de crédito siguen aplicándose.

Descarga alternativa desde GitHub

La instalación y las actualizaciones prueban automáticamente el mirror oficial de GitHub. Siguen siendo obligatorias las comprobaciones de firma, checksum y crédito.

CLI del servidor

Comandos root por SSH.

whollycrypto status
whollycrypto doctor
whollycrypto backup
Todos los comandos
ComandoPropósito
whollycrypto versionVersión instalada.
whollycrypto statusEstado de la aplicación y la base de datos.
whollycrypto logsÚltimas 80 líneas del registro de la aplicación.
whollycrypto restartReiniciar y comprobar el estado.
whollycrypto doctorComprobaciones de instalación de solo lectura.
whollycrypto doctor --fixReparar permisos gestionados y un enlace CLI ausente.
whollycrypto htaccessRestablecer un acceso Basic Auth.
whollycrypto admin-resetRestablecer una contraseña de administrador.
whollycrypto 2fa-resetRestablecer el autenticador de una cuenta sin cambiar su contraseña.
whollycrypto transfers status
whollycrypto transfers enable
whollycrypto transfers disable
Comprobar, activar o pausar los envíos de todos los proyectos. Activar reinicia la aplicación y puede ejecutar inmediatamente las reglas guardadas; requiere confirmación. Las actualizaciones conservan las pausas.
whollycrypto sslComprobar HTTPS; añade --fix para reparar.
whollycrypto access-reset --domain HOSTQuitar la restricción de IP de un nombre de host.
whollycrypto update --checkBuscar actualizaciones firmadas.
whollycrypto updateHacer copia de seguridad, actualizar y reiniciar.
whollycrypto backupArchivo solo para root en /root/whollycrypto/backups/releases/.
whollycrypto recoverRecuperar mantenimiento interrumpido o una actualización sin cambio de esquema. Nunca restaura una base de datos automáticamente.
whollycrypto resetElegir un proyecto, todos los proyectos del negocio o solo reparar.
whollycrypto uninstall --check
whollycrypto uninstall
Previsualizar y después eliminar el entorno nativo. Se conservan base de datos, claves y copias de seguridad.
whollycrypto welcomeURL y enlaces de la consola.
whollycrypto --helpComandos; añade --help después de uno para ver sus opciones.
Diagnosticar problemas de instalación

Las comprobaciones son de solo lectura y devuelven un código de salida distinto de cero cuando requieren atención. --fix solo repara permisos gestionados y un enlace CLI ausente. Nunca cambia la facturación, elimina datos ni reinicia servicios.

Elegir el alcance del restablecimiento
whollycrypto reset
# Preview without changing anything:
whollycrypto reset --scope business --check
whollycrypto reset --scope project --project YOUR_PROJECT_IDENTIFIER --check

Elige un proyecto, todos los proyectos del negocio o solo reparar. Restablecer proyectos borra permanentemente los proyectos, tiendas, registros de wallets e historial de pagos seleccionados. Solo reparar comprueba y corrige los permisos gestionados y el enlace CLI.

Primero desactiva los proyectos seleccionados, resuelve pagos y transferencias abiertos y mueve los saldos conocidos de las wallets. Se conservan cuentas, dominios, nodos, créditos, identidad de facturación y modo de instalación. Las wallets receptoras del operador y los registros de crédito alojados están protegidos. Esto no vuelve a abrir el asistente de configuración.

Un restablecimiento destructivo requiere una confirmación escrita y crea una copia de recuperación verificada antes de borrar. Guarda también una copia de las wallets fuera del servidor: las direcciones antiguas aún pueden recibir fondos, pero los proyectos borrados dejan de seguirlas. Los saldos en caché no demuestran que las wallets estén vacías.

Eliminar una instalación nativa
whollycrypto uninstall --check
whollycrypto uninstall

Detiene pago, API y workers; elimina archivos de ejecución e integración gestionada con el servidor después de una copia de seguridad y una confirmación escrita. Los pagos o transferencias pendientes bloquean la eliminación. Los archivos se mueven a la copia de recuperación en lugar de destruirse.

Se conservan la base de datos, configuración, claves y copias de seguridad. No se modifican los paquetes compartidos de Nginx/PostgreSQL ni los certificados TLS. El comando muestra un comando de recuperación sin conexión; no ejecutes una instalación nueva sobre los datos conservados.

Los comandos de restablecer/eliminar son para instalaciones nativas en VPS, no Docker ni Umbrel. Para contenedores, usa los comandos de copia de seguridad y parada de tu integración; conserva los volúmenes. Ninguno de los comandos destructivos acepta --yes.

Restablecer el acceso Basic Auth
whollycrypto htaccess

Selecciona un usuario, elige nombre y contraseña y confirma. Esto restablece el primer diálogo de acceso del navegador, no tu cuenta de consola. Los demás usuarios y credenciales API no cambian.

Restablecer una contraseña de administrador
whollycrypto admin-reset

Elige un administrador por email y confirma la nueva contraseña. Se borran las sesiones y los bloqueos de acceso de la cuenta; las restricciones de IP permanecen.

Los restablecimientos normales conservan 2FA. Si has perdido tanto el autenticador como los códigos de recuperación, ejecuta explícitamente whollycrypto admin-reset --email admin@example.com --reset-2fa. Configura 2FA de nuevo tras acceder.

Necesita la base de datos, no la aplicación ni la contraseña anterior. Las demás cuentas, wallets y permisos no cambian; las cuentas desactivadas siguen desactivadas.

Restablecer 2FA

¿Perdiste el autenticador y los códigos de recuperación? Elige una cuenta como root.

whollycrypto 2fa-reset
# Or select the account directly:
whollycrypto 2fa-reset --email user@example.com

Elimina sesiones, autenticador y códigos de recuperación. Accede con la contraseña existente y configura 2FA de nuevo. Permisos, wallets y Basic Auth no cambian; las cuentas desactivadas siguen desactivadas.

Requiere la base de datos, no la aplicación ni créditos. Sin interacción: --email y --yes.

Contraseñas generadas y automatización

Intro genera una contraseña en /root/whollycrypto/config/credential-resets/: privada, sin cifrar y utilizable tras el éxito. Las contraseñas introducidas manualmente no se guardan.

whollycrypto htaccess --user admin --new-user operator
whollycrypto admin-reset --email admin@example.com

Sin terminal, especifica la cuenta existente más --generate o --password-file /root/private-password.txt, y --yes. Los archivos de contraseña deben pertenecer a root, con modo 600. Nunca pongas contraseñas en comandos ni variables de entorno.

--yes solo omite la confirmación. Termina primero la recuperación de actualizaciones interrumpidas; los cambios simultáneos en la cuenta detienen los restablecimientos.