Uso de pagos multicadena
Todo el servicio de cobros:
- Dos vías de integración: la caja de pago (la configuras y envías el enlace, sin código) y una aplicación con la API (tu sistema crea las órdenes y recibe las notificaciones)
- Dos modelos de custodia: el dinero de las direcciones custodiadas por la plataforma se puede retirar tras consolidarse, y la comisión se descuenta al consolidar; el de las direcciones autocustodiadas llega directamente a tu dirección, y la comisión se descuenta del saldo de la cuenta en cada pago
- Configuración de la aplicación: la App Key firma las órdenes, el secreto de notificaciones firma las notificaciones, la URL de callback debe ser https y se puede cobrar por rotación o en modo 1 a 1
- Una notificación cuenta como entregada cuando se devuelve un 2xx; si falla se reintenta automáticamente hasta 10 veces, y se puede reenviar desde el registro de notificaciones
- Páginas de fondos: pool de direcciones, activos, configuración de consolidación, retiros y transferencias de fondos, transacciones y retiro por API
- La precisión del token y el desplazamiento de cobro definen los últimos decimales del monto a pagar; las órdenes de una misma dirección se distinguen por esos decimales, así que hay que pagar el monto exacto
Qué hace este servicio
Pagos multicadena es el servicio central de la plataforma: tus clientes pagan con USDT u otras criptomonedas y el dinero llega a las direcciones de cobro a tu nombre. Hay dos vías de integración; puedes usar solo una o las dos a la vez.
- Caja de pago: la plataforma genera un enlace de pago dedicado y un código QR. Configura tu marca y tus parámetros y envíalo a un cliente; sin nada de código.
- Aplicación más API: crea una aplicación para obtener sus claves, y luego haz que tu propio sistema cree órdenes y reciba Webhooks de pago. Es lo adecuado para quien ya tiene un sistema al que conectarse.
Decide primero un modelo de custodia
Hay dos tipos de direcciones de cobro: las custodiadas por la plataforma y las autocustodiadas. El modelo de custodia va con cada dirección, así que una misma aplicación puede usar los dos tipos a la vez. De él depende dónde queda el dinero, cómo se cobra la comisión y qué funciones están disponibles, así que tenlo claro antes de empezar a cobrar.
- Custodia de la plataforma — La plataforma asigna las direcciones de cobro. Una vez consolidado, el dinero recibido pasa a «Retirable (consolidado)» en «Activos», y desde ahí puedes retirarlo a una dirección externa, transferirlo al saldo de la cuenta o retirarlo por API.
- Autocustodia — Importa en «Direcciones → Direcciones autocustodiadas» direcciones cuya clave privada tienes tú. El dinero llega directamente a tu dirección; la plataforma solo detecta la llegada, envía la notificación y lleva el registro, sin consolidar nada: la gestión queda en tus manos.
El dinero de las direcciones autocustodiadas no pasa por la plataforma, así que no aparece en «Retirable (consolidado)» y no se puede retirar desde la plataforma ni por API. Antes de elegir la autocustodia, confirma que tu proceso de pagos no dependa de ninguna de esas dos vías.
Cómo se cobra la comisión
- Custodia de la plataforma — Se descuenta un porcentaje del monto consolidado al consolidar, con una comisión mínima por token, y lo que queda pasa a «Retirable (consolidado)». El porcentaje es la tarifa vigente de tu cuenta, que puede ser la tarifa predeterminada, una tarifa propia o una tarifa escalonada según el monto consolidado en el mes.
- Autocustodia — Cuando llega el pago de cada orden, la comisión se calcula multiplicando la cantidad de tokens de esa orden por la tarifa, se convierte a dólares y se descuenta del saldo de tu cuenta, con una comisión mínima por orden.
La comisión de la autocustodia se descuenta del saldo de la cuenta, que puede quedar en negativo. Mientras el saldo esté por debajo de 0, las aplicaciones que cobran con direcciones autocustodiadas dejan de aceptar órdenes nuevas: si un cliente intenta pagar en ese momento, la orden falla, aunque las órdenes ya generadas no se ven afectadas. Las notificaciones de llegada del modo 1 a 1 también quedan en espera. Cuando recargas y el saldo vuelve a estar por encima de 0, todo se reanuda solo y las notificaciones en espera se envían automáticamente.
Las tarifas se consultan en «Reglas de comisión de la plataforma», dentro de «Activos → Configuración de consolidación»: la tarifa vigente, las tarifas escalonadas por volumen mensual y la comisión mínima de cada token. En el detalle de una orden, la línea «Comisión» es la base del cargo de esa orden en las direcciones autocustodiadas; en las custodiadas por la plataforma es solo un valor de referencia y lo que se cobra de verdad es lo que se calcula al consolidar.
Crear una aplicación de pago
- Crea la aplicación y guarda sus credenciales: En «Pagos multicadena → Lista de apps», pulsa «Crear aplicación»; al crearla aparece una ventana con el App ID y la App Key. Después puedes volver a ver la App Key pulsando «Secreto» en la lista de aplicaciones. Una aplicación nueva todavía no tiene secreto de notificaciones: en esa misma ventana pulsa «Restablecer secreto de notificaciones» para generar uno y configúralo en tu servidor para verificar las firmas.
- Configura las URL de callback y de redirección: La URL de callback recibe las notificaciones del resultado del pago y debe ser una dirección https; la URL de redirección es la página a la que se lleva al cliente después de pagar. Tienen propósitos distintos: no pongas la misma en las dos.
- Elige un modo de pago: La rotación asigna una dirección de cobro del pool cada vez que se crea una orden; el modo 1 a 1 vincula una dirección fija por cliente y notifica los fondos entrantes. Ambos se pueden activar a la vez.
- Elige qué cadenas y tokens aceptar: Abre la pestaña «Configuración de la aplicación» en el detalle de la aplicación: la lista muestra las cadenas y los tokens que la plataforma tiene habilitados. Marca los que esta aplicación va a aceptar, elige la moneda fiat en la que se expresan las órdenes y pulsa «Guardar».
La App Key y el secreto de notificaciones son credenciales. Para ver el secreto de notificaciones completo, o para generarlo o restablecerlo, primero tienes que verificar tu identidad; si la aplicación tiene activada la API abierta, ver o restablecer la App Key también lo requiere. Al restablecer, el valor anterior deja de funcionar al instante y cualquier integración en marcha se interrumpe, así que planifica el cambio antes de restablecer.
Recibir pagos a través de la caja de pago
La caja de pago no necesita código: la configuras y obtienes un enlace dedicado y un código QR para entregar a los clientes. La configuración está en tres pestañas.
- Parámetros de pago — La aplicación vinculada, la moneda fiat y la criptomoneda predeterminadas, el monto mínimo, la ventana de tiempo de la orden, la URL de redirección tras el pago y la URL de notificación de pago. La ventana de tiempo es la duración de la cuenta regresiva de la página de pago y se puede fijar entre 5 y 1440 minutos; cuando termina, la orden se conserva 25 minutos más para recoger los pagos enviados justo antes del límite que todavía se están confirmando en la cadena. Si llenas la URL de notificación de pago, las notificaciones van ahí; si la dejas vacía, van a la URL de callback de la aplicación vinculada.
- Marca — La plantilla de la caja de pago (hay cinco: Moderna minimalista, Marca destacada, Compacta, Cripto nativa y Confianza Pro, y puedes cambiarla cuando quieras), el logo, el nombre de marca, el color del tema, el eslogan y la descripción: definen lo que ve el cliente al abrir la caja de pago.
- Configuración de visualización — Los datos de contacto que se muestran al cliente (correo, teléfono, Telegram, sitio web oficial), si el cliente puede escribir una nota en la orden, y si debe dejar datos de contacto y de qué tipos puede elegir.
Si la aplicación vinculada a la caja de pago tiene la rotación activada, la página lo dice directamente; esa línea te indica de dónde viene la dirección de cobro y no es un error.
Órdenes, órdenes de caja de pago y registros de Webhook
- «Órdenes»: aquí están todas las órdenes de cobro. Las que vienen de la caja de pago llevan la etiqueta «Caja» y se pueden filtrar con «Origen de la orden». El detalle de cada orden muestra la información en la cadena, la comisión de esa orden y el estado de la notificación.
- «Órdenes de caja»: lista solo las órdenes generadas por la caja de pago; se pueden filtrar por pendientes de pago, pagadas, vencidas y canceladas, y puedes copiar el enlace de caja de cada orden.
- «Registro de notificaciones»: la solicitud, la respuesta y el resultado de cada notificación. Empieza por aquí cuando revises una integración: verás si no se envió nada o si tu servidor no la aceptó. Tanto los registros exitosos como los fallidos tienen el botón «Reenviar».
Reglas de notificación: se considera entregada cuando tu servidor devuelve cualquier código de estado 2xx en menos de 10 segundos; la plataforma no mira el contenido de la respuesta. Un tiempo agotado, una respuesta que no sea 2xx o una redirección cuentan como fallo. Tras un fallo, la plataforma reintenta a los 30 segundos, 1 minuto, 2 minutos y 5 minutos, y después cada 10 minutos, con un máximo de 10 reintentos. Cada notificación lleva un notify_id único que no cambia ni en los reintentos automáticos ni al pulsar «Reenviar»: úsalo para eliminar duplicados.
Fondos, pool de direcciones y pagos salientes
Dónde está el dinero depende del modelo de custodia, y estas páginas cubren sus distintas etapas.
- Pool de direcciones — Muestra el total de direcciones, cuántas están disponibles y cuántas vinculadas, y los activos de cada dirección; puedes poner a una dirección una nota que solo ves tú. Al desvincular una dirección vuelve al pool disponible. Las direcciones custodiadas por la plataforma se pueden consolidar una por una con «Consolidar». Las direcciones autocustodiadas se importan desde la entrada «Direcciones autocustodiadas»; las reglas están en la nota de abajo.
- Activos — Arriba se muestran por separado el saldo de la cuenta, «Retirable (consolidado)» y «En cadena, sin consolidar (est.)». Los dos últimos no se suman: lo que está pendiente de consolidar en la cadena solo se puede retirar después de consolidarse y de descontar la comisión. Esta página también tiene accesos a recargar, retirar, transferir fondos, las facturas de la plataforma, el historial de consolidación y la configuración de consolidación.
- Configuración de consolidación — Muestra las «Reglas de comisión de la plataforma». En «Configuración de consolidación automática» defines un umbral de consolidación por token: al alcanzarlo se consolida automáticamente, y el umbral no puede ser menor que el mínimo de consolidación de la plataforma. También puedes pulsar «Consolidar ahora todos los activos elegibles». Con un umbral más alto se consolida menos veces y se paga menos veces la comisión mínima.
- Retiros y transferencias de fondos — «Retirar» envía los activos retirables a una dirección externa y requiere tener activada la verificación en dos pasos. La página muestra la comisión, el retiro mínimo y el total descontado de cada token; la comisión se cobra aparte, así que el monto que escribes llega completo. También puedes configurar reglas de retiro automático, que retiran solas cuando se alcanza el umbral después de consolidar. «Transferir» convierte los activos retirables a dólares al tipo de cambio del momento y los pasa al saldo de la cuenta; no se puede deshacer.
- Transacciones — Las transacciones en la cadena de todas las direcciones del pool. Cada una indica la orden asociada; las que no coinciden con ninguna orden aparecen como «Sin vincular» y las que no generaron orden, como «Sin pedido».
- API de retiro — Pagos salientes programáticos que solo usan los activos de «Retirable (consolidado)». Antes de poder encender el «Interruptor principal» tienes que configurar la clave pública de la contraparte y al menos una IP en la lista de IP permitidas, y la clave API que uses debe tener marcado «Retiros por API» en «Gestión de API». Puedes fijar un retraso del retiro, el modo de comisión, un límite por transacción y una lista de direcciones permitidas; durante el retraso puedes pausar, cancelar o procesar de inmediato cada retiro en «Registros de retiro».
Importar direcciones autocustodiadas: solo se registra la dirección; no hace falta ni se acepta la clave privada. Al importar, firmas con la billetera de cada dirección un texto de verificación que da la página, para demostrar que la dirección es tuya. La firma no gasta activos ni autoriza ninguna transferencia, y el texto es válido durante 15 minutos. Las redes que se pueden importar son las que muestra la página; solo se admiten direcciones TRON y EVM, hasta 20 por importación y 100 por cadena. Una dirección no se puede eliminar mientras esté vinculada a una aplicación con rotación o tenga órdenes sin vencer; al eliminarla también se borran las transacciones que se detectaron en ella.
Configuración de tokens: precisión y desplazamiento
La configuración de tokens tiene dos parámetros, y juntos deciden cómo ve el cliente el monto a pagar.
- Precisión: cuántos decimales muestra el monto en cripto, configurable de 2 a 10. Se sugieren seis para USDT / USDC y dos para TRX.
- Desplazamiento de cobro: cuando una dirección tiene varias órdenes sin pagar al mismo tiempo, el sistema ajusta los últimos decimales para poder distinguir las órdenes.
- El desplazamiento tiene un tipo y un rango, y el rango debe caber dentro de la precisión: el desplazamiento solo puede moverse dentro de los decimales que la precisión permite.
Justo por eso el monto de la página de pago debe pagarse al centavo: los últimos dígitos son los que identifican la orden. Pagar un poco más o un poco menos puede dejar al sistema sin poder saber a qué orden pertenece la transferencia.
Integración por API
La referencia completa de la API está en el centro de documentación para desarrolladores: el mecanismo de firma, ejemplos de solicitud y respuesta, códigos de error, eventos de notificación y verificación de firma. La entrada «Documentación de integración API» de la barra lateral de la consola lleva directamente ahí.
Las solicitudes de creación de órdenes se firman con la App Key; las notificaciones que te envía la plataforma se firman con el secreto de notificaciones, y debes verificar esa firma en tu servidor. La opción «Permitir otras API abiertas» del detalle de la aplicación viene desactivada: así, las credenciales de la aplicación solo pueden llamar a las API de cobro y de tipo de cambio. Si la activas, pueden consultar otros servicios, pero las API que crean órdenes o cobran siguen aceptando únicamente claves API de «Gestión de API».
Solución de problemas
- Un cliente pagó pero no llegó ninguna notificación — La URL de callback está mal, o tu servidor no respondió correctamente — Revisa primero el «Registro de notificaciones». Si no hay ningún registro, comprueba la URL de callback de la aplicación, que debe ser una dirección https. Si hay un registro fallido, comprueba si tu servidor devolvió un 2xx en menos de 10 segundos; cuando lo corrijas, puedes pulsar «Reenviar». Confirma también que verificas la firma con el secreto de notificaciones vigente.
- Una transferencia no se asoció a ninguna orden — El monto pagado difiere del monto exacto mostrado — Una misma dirección puede tener varias órdenes pendientes de pago, y el sistema las distingue por el desplazamiento de los últimos decimales del monto, así que hay que pagar exactamente el monto que muestra la página. Las transferencias que no coinciden aparecen como «Sin vincular» en «Transacciones».
- No se puede asignar una dirección de cobro — El pool de direcciones no tiene direcciones libres y la asignación automática ya llegó a su límite; o las direcciones de rotación no incluyen ninguna de esta cadena — Modo 1 a 1: cuando tu pool de direcciones no tiene direcciones libres, la plataforma asigna más automáticamente, hasta 1000 por cadena cada 24 horas; superado eso, desvincula las direcciones que ya no uses o importa direcciones propias. Rotación: si la aplicación tiene direcciones de rotación configuradas, solo se usan esas, así que confirma que la lista incluya direcciones de esta cadena.
- La API de retiro dice que no hay saldo — El dinero todavía está en la cadena pendiente de consolidar, o se cobró en una dirección autocustodiada — Mira «Retirable (consolidado)» en «Activos». Lo que está pendiente de consolidar se puede consolidar en «Configuración de consolidación» con «Consolidar ahora todos los activos elegibles»; el dinero de las direcciones autocustodiadas no pasa por la plataforma y no se puede retirar por API.
- Una aplicación con direcciones autocustodiadas no acepta órdenes nuevas — El saldo de la cuenta está por debajo de 0 — La comisión de la autocustodia se descuenta del saldo de la cuenta. Cuando recargas y el saldo vuelve a estar por encima de 0, todo se reanuda solo y las notificaciones 1 a 1 en espera se envían automáticamente.
- Una dirección 1 a 1 recibió una transferencia muy pequeña y no se generó ninguna orden — Las llegadas por menos de 0.01 dólares no generan orden — El dinero ya está en la dirección; simplemente no genera orden ni notificación. Verás esa transferencia en «Transacciones» con la etiqueta «Sin pedido».
- Se rechaza crear una orden de cobro o vincular una dirección nueva — La cuenta está restringida o congelada — En ese estado no puedes crear órdenes de cobro ni vincular direcciones nuevas; las órdenes existentes se pueden seguir consultando y cerrando. Contacta a soporte para resolverlo.
Preguntas frecuentes
Un cliente pagó pero mi sistema no recibió la notificación, ¿qué hago?
Revisa primero el «Registro de notificaciones». Si no hay ningún registro de notificación, comprueba que la URL de callback de la aplicación sea correcta y que sea una dirección https; si hay notificaciones fallidas, tu servidor no devolvió un 2xx en menos de 10 segundos. Cuando lo corrijas, puedes pulsar «Reenviar» en el registro, y la plataforma también volverá a enviarla automáticamente según su calendario de reintentos.
¿Dónde veo la comisión y cuándo se cobra?
La tarifa vigente está en «Reglas de comisión de la plataforma», dentro de «Activos → Configuración de consolidación». En las direcciones custodiadas por la plataforma, la comisión se descuenta al consolidar; en las autocustodiadas, se descuenta del saldo de la cuenta cuando llega cada pago. En el detalle de la orden, la «Comisión» de una dirección custodiada por la plataforma es solo un valor de referencia: lo que se cobra de verdad es lo que se calcula al consolidar.
¿Por qué el cliente tiene que pagar exactamente el monto que muestra la página?
Porque una misma dirección puede tener a la vez varias órdenes pendientes de pago, y el sistema las distingue por el desplazamiento de los últimos decimales del monto. Si el monto no coincide, puede que la transferencia no se asocie automáticamente a la orden.
Páginas relacionadas: Centro de ayuda · Guías y preguntas frecuentes · Pagos cripto multicadena · Documentación de la API
Cargando…