Empezar como desarrollador

Crea una app en la Mini App, copia su token de API una vez y empieza a llamar a la API. Toda la configuración está en Más → API para comerciantes.

Pasos

1. Abre Más → API para comerciantes y elige Crear la app.
2. Ingresa un Nombre de la app (por ejemplo, “Mi tienda”) y, si quieres, una URL del webhook (opcional).
3. Acepta las condiciones del formulario y toca Crear la app. Confirma con tu PIN o con biometría cuando se solicite. Al crear una app aceptas las condiciones de la API para comerciantes: para qué puedes usar la API y para qué no.
4. Copia el token de API de inmediato. Se muestra una sola vez y nunca más: la app guarda solo un hash.
5. Envía tu primera petición con el token en la cabecera TgPayCrypto-API-Token.

Tu primera llamada

Apunta tu cliente a la base de la API https://app.tgpaycrypto.com/pay/api y llama a getMe para confirmar que el token funciona. getBalance devuelve los saldos de tu app y getCurrencies los activos que puedes usar.

Los métodos de lectura son GET. Los de escritura, como createInvoice, transfer, createCheck, deleteInvoice y deleteCheck, son solo POST. Los parámetros se pueden enviar en el cuerpo de la petición, como JSON o form-urlencoded, o como parámetros de consulta. Prefiere el cuerpo de la petición para evitar que los montos y las claves de idempotencia queden en los registros de acceso de las URL.

Red de prueba

Desarrolla primero en la red de prueba (testnet): la misma API, la misma Mini App y fondos de prueba sin valor real:

	Red principal	Red de prueba
Bot	@tgpaycryptobot	@tgpaycrypto_testnet_bot
Base de la API	https://app.tgpaycrypto.com/pay/api	https://testnet.tgpaycrypto.com/pay/api
Servidor MCP	https://app.tgpaycrypto.com/mcp	https://testnet.tgpaycrypto.com/mcp

Las apps y los tokens son independientes: un token de la red de prueba no funciona en la red principal, y viceversa. Para conseguir fondos de prueba, abre la Mini App de la red de prueba y toca Obtener monedas de prueba en la pantalla de inicio. Recibirás un paquete de fondos de prueba como depósitos normales; se omiten los activos cuyas redes estén desactivadas. La app muestra lo que se abonó y cuándo podrás volver a pedir fondos. Puedes usar una segunda cuenta de Telegram como cliente para pagar tus facturas de prueba.

Los depósitos y retiros son simulados, sin transacciones reales en la blockchain. Nunca envíes fondos reales a una dirección de depósito de la red de prueba. Ambas redes comparten el contrato de la API, pero las funciones, los tipos de cambio y los límites disponibles pueden variar. Cuando termines, crea una app de producción en @tgpaycryptobot y cambia la URL base.

Administrar una app

Abre una app en API para comerciantes para ver su ID y su saldo. Desde allí puedes:

• Fijar o cambiar la URL del webhook en Webhook y guardarla.
• Elegir eventos de webhook adicionales — los interruptores de Eventos de webhook adicionales, en la sección Webhook, permiten elegir otros tipos de eventos además de invoice_paid (mira la referencia de webhooks).
• Restringir a quién puede pagar la API — en Configuración de pagos, Pagos a través de la API está en Cualquier usuario en una app nueva; cámbialo a Solo usuarios de la lista (y agrega los destinatarios) o a Desactivado si tu integración nunca le paga a nadie: una protección por si el token se filtra (mira el modo de pagos).
• Crear tokens restringidos — abre Acceso y tokens para crear tokens de API adicionales en Tokens restringidos, cada uno limitado a los ámbitos que elijas (mira la referencia de la API).
• Renovar el token — en Acceso y tokens, emite un token nuevo e invalida el viejo al instante. Úsalo si un token se filtró; el nuevo se muestra una sola vez, igual que al crearlo.
• Eliminar — primero envía los fondos del saldo disponible; de lo contrario, se rechaza la eliminación con app_has_balance. Resuelve también los cheques y pagos pendientes antes de eliminar la app. La app desaparece de la lista y sus tokens dejan de funcionar; su historial de pagos se conserva.

Webhooks

Si configuras una URL de webhook, la app envía a esa dirección una petición POST con un cuerpo JSON firmado:

{ "update_id": …, "update_type": "invoice_paid", "request_date": …, "payload": { … } }

La firma va en la cabecera TgPayCrypto-API-Signature (con TgCryptoPay-API-Signature y Crypto-Pay-API-Signature como alias de compatibilidad): HMAC-SHA256 sobre el cuerpo original, sin modificar, con clave el SHA-256 de tu token principal de API. Verifícala antes de confiar en nada del payload.

Las entregas se reintentan con intervalos cada vez mayores durante un período extendido, y update_id se mantiene igual entre reintentos: basa tu deduplicación en él y haz que tu manejador sea idempotente.

invoice_paid no requiere activación adicional si hay una URL de webhook configurada. Los demás tipos de eventos —facturas expiradas, cheques canjeados, reembolsos, eventos de suscripción— son opcionales mediante los interruptores de Eventos de webhook adicionales. La lista completa, las estructuras de los payloads y el calendario de reintentos están en la referencia de webhooks.

⚠️ Cuida el token como una clave privada

Autoriza pagos desde el saldo de tu app. Guárdalo en tu servidor, nunca en una app para celulares, en un bundle de front-end ni en una configuración versionada. Si dudas de si se filtró, renuévalo: la renovación es instantánea y no cuesta nada. Y dale a cada servidor solo lo que necesita: un token restringido con únicamente el ámbito invoices puede crear y eliminar facturas, pero no transferir fondos, crear cheques ni emitir reembolsos.