Referencia de la API: transferencias y cheques

Los métodos de pago. Una transferencia envía fondos del saldo de tu app directo a la billetera de un usuario de Telegram; un cheque es un enlace canjeable que financias por adelantado. Las convenciones (autenticación, envoltorio, montos, spend_id) están en la página de referencia de la API para comerciantes.

transfer

POST /pay/api/transfer — ámbito payouts, límite de 30 por minuto. Se liquida al instante y de forma atómica; no hay estado pendiente.

Parámetro	Tipo	Obligatorio	Significado
user_id	integer	sí	el id de usuario de Telegram de quien recibe. Tiene que ser ya usuario de la app: un pago a un id desconocido da error en vez de dejar los fondos varados
asset	string	sí	código del activo
amount	string	sí	cadena decimal positiva; también acotada por el mínimo y el máximo por transferencia de la plataforma (una estimación equivalente en dólares a los tipos del momento)
spend_id	string	sí	clave de idempotencia, de 1 a 64 caracteres, única por pago
comment	string	no	hasta 1024 caracteres, se le muestra a quien recibe
disable_send_notification	boolean	no	true = no avisarle a quien recibe por Telegram

El resultado es el objeto de transferencia: transfer_id, hash, user_id, asset, amount, amount_minor, spend_id, comment, status (siempre completed), created_at, completed_at.

Errores: 404 user_not_found (quien recibe nunca usó la app), 409 recipient_blocked, 400 amount_too_small / 400 amount_too_big (fuera de los límites por transferencia), 409 insufficient_funds, 404 unknown_asset, 400 invalid_amount, y el par de spend_id 409 idempotency_conflict / 409 idempotency_in_progress.

transferBatch

POST /pay/api/transferBatch — ámbito payouts, límite de 10 por minuto. Una extensión para pagos masivos: hasta 100 transferencias en una llamada.

Un parámetro: items, un array donde cada elemento es un juego completo de parámetros de transfer (user_id, asset, amount, spend_id, y los opcionales comment y disable_send_notification). Los spend_id tienen que ser únicos dentro del lote, o toda la llamada falla con 400 duplicate_spend_id antes de ejecutar nada.

Los elementos se liquidan de forma independiente y en orden: un elemento fallido nunca revierte a los demás. La llamada devuelve HTTP 200 con ok: true incluso cuando algunos elementos fallaron, así que revisa siempre cada uno:

• éxito: {"ok": true, "spend_id": "…", "result": <transfer object>}
• fallo: {"ok": false, "spend_id": "…", "error": {"code": …, "name": "…"}} con los mismos nombres de error que un transfer suelto.

Los elementos del lote comparten el espacio de idempotencia con las transferencias sueltas: reintentar el lote entero —o reenviar un elemento como un transfer suelto con el mismo spend_id— repite en vez de pagar dos veces.

getTransfers

GET /pay/api/getTransfers — ámbito read. Filtros: asset, transfer_ids (separados por comas), spend_id (coincidencia exacta: busca un pago por tu propia clave), más offset / count. Devuelve {"items": [transfer, …]}, los más recientes primero.

createCheck

POST /pay/api/createCheck — ámbito checks, límite de 60 por minuto. Crea un cheque de un solo uso financiado con el saldo de tu app; cualquiera que tenga el enlace —o solo el usuario fijado— puede canjearlo en su billetera. El monto se bloquea en el momento en que se crea el cheque (pasa de available a onhold en getBalance).

Parámetro	Tipo	Obligatorio	Significado
asset	string	sí	código del activo
amount	string	sí	cadena decimal positiva
pin_to_user_id	integer	no	solo este id de usuario de Telegram puede canjearlo
pin_to_username	string	no	solo este @usuario puede canjearlo (la @ es opcional; se ignora cuando también se usa pin_to_user_id). El usuario tiene que pertenecer a alguien que ya use la app
spend_id	string	no	clave de idempotencia (extensión) — usa una

El resultado es el objeto de cheque: check_id, hash, asset, amount, amount_minor, bot_check_url (el enlace de canje de t.me), status (active / activated), pin_to_user_id, created_at, activated_at. Un canje dispara el webhook opcional check_activated.

Errores: 404 unknown_asset, 400 invalid_amount, 404 user_not_found (el usuario fijado no coincide con nadie), 409 insufficient_funds, y el par de spend_id.

deleteCheck

POST /pay/api/deleteCheck — ámbito checks. Un parámetro: check_id. Cancela un cheque sin canjear y devuelve el monto bloqueado al saldo de tu app; devuelve true. Errores: 404 check_not_found, 409 check_not_active (ya canjeado o eliminado).

getChecks

GET /pay/api/getChecks — ámbito read. Filtros: asset, check_ids (separados por comas), status (active / activated), más offset / count. Devuelve {"items": [check, …]}, los más recientes primero; los cheques eliminados nunca se devuelven.