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 vive en Más → API para comerciantes.

Pasos

1. Abre Más → API para comerciantes.
2. Ingresa un Nombre de la app (por ejemplo, “Mi tienda”) y, si quieres, una URL del webhook.
3. Toca Crear la app.
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 que mueven dinero —createInvoice, transfer, createCheck y sus contrapartes de borrado— son solo POST, a propósito: los montos y las claves de idempotencia no van en los registros de acceso. Los parámetros se pueden enviar como cuerpo JSON, form-urlencoded o parámetros de consulta.

Administrar una app

Cada tarjeta de app en API para comerciantes muestra su ID y su saldo, y te deja:

• Fijar o cambiar la URL del webhook y guardarla.
• Elegir eventos de webhook adicionales — una vez que hay una URL de webhook, los interruptores de Eventos de webhook adicionales te dejan sumar tipos de eventos más allá de invoice_paid (mira la referencia de webhooks).
• Crear tokens restringidos — tokens de API extra en Tokens restringidos, cada uno limitado a los ámbitos que elijas (mira la referencia de la API).
• Renovar el token — 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 — la app deja de autenticar, pero su saldo y su historial de pagos se conservan. Eliminar una app nunca hace desaparecer su dinero.

Webhooks

Si pones una URL de webhook, la app le hace POST de un cuerpo JSON firmado:

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

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

Las entregas se reintentan con retroceso exponencial 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 se entrega siempre. 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 formas 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 móvil, en un bundle de front-end ni en una configuración versionada. Si dudas de si se filtró, rótalo: rotar es instantáneo y no cuesta nada. Y dale a cada servidor solo lo que necesita: un token restringido sin el ámbito payouts puede crear facturas, pero nunca sacar tu saldo.