¿Qué es la API para comerciantes?
La API para comerciantes es la API de pagos de la app para negocios y bots. Creas una app, obtienes un token de API y lo usas para cobrarles a los usuarios de Telegram, enviarles pagos y consultar tu saldo, todo desde tu propio código.
Es el lado de desarrollo del mismo producto que ven los usuarios: una factura que creas por la API es la factura que ellos pagan con su saldo después de confirmar el pago.
Qué puedes hacer con ella
- Facturas — crea una solicitud de pago (un monto fijo en cripto, uno con precio en fiat o un monto abierto que elige quien paga), envíale su enlace a quien paga y recibe un webhook firmado tras el pago si configuraste una URL de webhook.
- Reembolsos — devuelve el monto de una factura pagada, entero o en parte, a quien la pagó, incluso a quienes pagaron de forma anónima.
- Transferencias — envía cripto desde el saldo de tu app a un usuario de Telegram, de a una o hasta 100 en un lote.
- Cheques — financia enlaces canjeables con el saldo de tu app, para cualquiera o para destinatarios específicos, según tu configuración de pagos.
- Suscripciones — cobros recurrentes: los usuarios aprueban un plan una vez y se les cobra automáticamente cada período.
- Saldos, monedas, tipos de cambio y estadísticas — endpoints de solo lectura para tu propia contabilidad.
Cómo funciona
- Tu app tiene un saldo, separado de tu billetera personal.
- Las facturas pagadas abonan fondos a ese saldo.
- Las transferencias y los cheques usan fondos de ese saldo.
- Los eventos de pago admitidos pueden enviarse a tu servidor como un webhook firmado si configuras la URL y la suscripción a esos eventos.
Los pagos se completan dentro de la app, sin transacciones on-chain: no hay
comisión de red ni confirmaciones que esperar, y puedes usar los fondos en
cuanto llegan. Quien paga también puede aportar fondos desde una billetera
externa cuando esa opción esté disponible. El depósito se abona a su propia
billetera; el pago automático requiere además saldo suficiente, ausencia de
restricciones para los pagos salientes y un plazo de pago vigente. Comprueba
que la factura esté en estado paid antes de entregar el pedido.
Compatible con Crypto Bot
La API replica a propósito la de Crypto Bot: los mismos nombres de métodos, la
misma estructura de respuesta {ok, result}, los mismos montos como cadenas decimales, el
mismo esquema de firma de webhooks. Para adaptar una integración existente,
cambia la URL base y el token, y prueba los métodos que uses consultando
nuestra referencia. Igual que Crypto Bot, tenemos una
red de prueba con su propio bot y su propia
URL base.
La cabecera canónica del token es TgPayCrypto-API-Token; la anterior al
2026-09-07, TgCryptoPay-API-Token, sigue funcionando, y
Crypto-Pay-API-Token se acepta como alias para que las bibliotecas cliente
existentes sigan funcionando sin cambios.
⚠️ Tu token de API es una llave para gastar
Un token principal autoriza pagos dentro del modo y los límites de pagos de la app. Guárdalo en el servidor, fuera de las apps cliente y los repositorios, y renuévalo apenas sospeches que se filtró. Para los servidores que no necesitan acceso completo, emite un token restringido limitado a los ámbitos que realmente usan — mira la referencia de la API.
Siguiente
¿Te sirvió este artículo?
Gracias por tu comentario.