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 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
Ofrece un botón o enlace en tu bot. El usuario abre la factura y paga con el saldo de su billetera.
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 ofrece un servidor MCP. Comparte su URL: el agente puede leer la documentación, crear la aplicación con tu aprobación, configurar el webhook y escribir el código sin que copies el token manualmente.
- Paso 1
Envía la instrucción al agente
Usa Claude Code, claude.ai, Claude Desktop, ChatGPT u otro cliente MCP compatible. 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
El agente completa la configuración
Recibe un token limitado y configura facturas, planes de suscripción y el webhook. Tú administras la clave de firma de webhooks desde la app.
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 tgpay MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the TgPay 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 se envía siempre. Los eventos de expiración de facturas, canje de cheques, reembolsos y suscripciones se activan por aplicación.
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
Comparte app.tgpaycrypto.com/mcp con tu agente. Puede crear la aplicación, configurar el webhook y escribir la integración. Tú autorizas la creación en el bot.
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