Pagos en criptomonedas en Telegram: facturas, webhooks y pagos a usuarios
La API para comerciantes permite integrar pagos de TgPay Crypto en bots y servicios. Crea una aplicación, obtén un token, emite facturas y recibe webhooks firmados. Un agente de IA puede ayudarte mediante el servidor MCP. Los pagos con saldo de TgPay Crypto son internos, sin comisión de red ni espera de confirmaciones de blockchain.
Base de la API: app.tgpaycrypto.com/pay/api · pruebas: testnet.tgpaycrypto.com
Del token al primer pago en cuatro pasos
Crea una factura, muestra el enlace y procesa el evento de pago.
Crea una aplicación
Abre "Más → API para comerciantes" en la app, indica un nombre y la URL del webhook. El token se muestra una sola vez; guárdalo en tu servidor.
Crea una factura
Una solicitud POST a createInvoice incluye monto en cripto o moneda fiduciaria, descripción y fecha límite. La respuesta contiene el enlace de pago.
Muestra el enlace al usuario
Con un botón o enlace en tu bot, el usuario paga desde el saldo de su billetera. Los montos elevados se confirman con PIN o Face ID.
Procesa el webhook
Tu servidor recibe invoice_paid firmado con HMAC-SHA256. Verifica la firma, evita duplicados mediante update_id y entrega el producto.
Tu agente de IA puede ayudarte con la integración
La API para comerciantes tiene un servidor MCP. Conéctalo en un cliente de agente compatible: el agente puede leer la documentación, solicitar la creación de una aplicación, configurar webhooks y ayudar a escribir la integración. Tú apruebas la aplicación en Telegram, revisas y pruebas el resultado.
- Paso 1
Envía la instrucción al agente
Usa un cliente de agente con soporte para MCP remoto disponible en tu cuenta o espacio de trabajo. La instrucción también está en “Más → API para comerciantes → Conectar un agente de IA”.
- Paso 2
Autoriza la aplicación en Telegram
El agente comparte un enlace t.me. El bot muestra lo solicitado para que lo autorices. El enlace solo funciona una vez y no se crea ninguna aplicación antes de tu aprobación.
- Paso 3
Completa y prueba la integración
El agente recibe un token limitado y ayuda a configurar facturas, planes de suscripción y webhooks. Para obtener la clave de firma de los webhooks, renueva el token principal en la app y guárdalo de forma segura en tu servidor.
El token emitido por este proceso permite aceptar pagos y configurar el webhook. No habilita transferencias, cheques ni reembolsos. Tú administras y otorgas los permisos adicionales de pago.
Más sobre la conexión con agentes en la documentaciónConnect the MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the Merchant API.
claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
Agrega app.tgpaycrypto.com/mcp como servidor en la configuración de conexiones de tu cliente MCP
https://testnet.tgpaycrypto.com/mcp
Comisiones y límites
Los valores proceden del catálogo público de límites al generar esta página. Consulta la app para conocer los valores vigentes.
Funciones de la API para comerciantes
Cada aplicación tiene un saldo separado de tu billetera. Las facturas lo acreditan; los pagos y cheques se descuentan de él.
Facturas y reembolsos
Monto fijo en cripto, precio en moneda fiduciaria o monto elegido por el pagador. Reembolsos totales o parciales, también para pagos anónimos.
Suscripciones
El usuario autoriza el plan y cada período se cobra automáticamente, con un evento por cobro.
Transferencias y cheques
Realiza pagos a usuarios de Telegram desde el saldo de la aplicación o crea cheques que se canjean mediante un enlace.
Webhooks
invoice_paid siempre se envía. En cada app puedes activar los eventos de expiración de facturas y cheques, canje de cheques, reembolsos, pagos de salida y suscripciones.
Red de pruebas
La misma API y Mini App están en @tgpaycrypto_testnet_bot. El botón de la pantalla principal entrega monedas de prueba una vez por hora.
Agentes de IA y MCP
Conecta app.tgpaycrypto.com/mcp en un cliente de agente compatible con servidores MCP remotos. Tras tu aprobación en Telegram, el agente puede crear una aplicación y ayudar con la integración. Revisa y prueba el resultado antes de usarlo.
Compatible con la API de Crypto Bot
Conserva los nombres de métodos, el formato {ok, result} y el esquema de firma de webhooks. Cambia la URL base y el token, y comprueba los métodos utilizados en la documentación.
Control de tokens y permisos
Tokens con permisos limitados, rotación inmediata, pagos solo a destinatarios guardados o desactivados, y un límite diario para reducir el impacto de una filtración.
Preguntas frecuentes sobre la API
Información sobre tokens, firmas de webhooks, pruebas y migración desde otra API.
La creación puede requerir una verificación de identidad completa según las reglas vigentes. Si se solicita, completa la verificación en la app e inténtalo de nuevo.
TgPayCrypto-API-Signature contiene la firma HMAC-SHA256 del cuerpo de la solicitud, con el hash SHA-256 del token principal como clave. Verifícala sobre los bytes originales del cuerpo. No entregues el producto ni marques la factura como pagada antes de validarla.
La API para comerciantes conserva los métodos, el formato {ok, result}, los montos como cadenas decimales y el esquema de firmas. Cambia la URL base y el token y revisa los métodos que usas. Crypto-Pay-API-Token se acepta como encabezado alternativo.
La red de pruebas ofrece la misma API y Mini App en @tgpaycrypto_testnet_bot, con base testnet.tgpaycrypto.com/pay/api. El botón para obtener monedas de prueba entrega 1.000 USDT, 1.000 GRAM y 0,01 BTC una vez por hora. Los tokens de producción y de prueba no son intercambiables.
Con un token limitado, el agente puede crear facturas y planes, consultar saldo y estadísticas y configurar el webhook según sus permisos. Transferencias, cheques y reembolsos requieren permisos de pago y funciones habilitadas. Tú decides qué permisos otorgas.
Documentación pública de la API para comerciantes
Referencia de métodos, especificación OpenAPI y guías en docs.tgpaycrypto.com.
Integra los cobros en tu producto
Crea una aplicación en @tgpaycryptobot o comparte el enlace del servidor MCP con tu agente y autoriza la creación en el bot.
Abrir bot