Comisiones y límites de la API para comerciantes

Las facturas llevan una comisión de la plataforma que sale de lo que recibes; las transferencias y los cheques están acotados por límites de monto. Las cifras de abajo son la configuración vigente, no condiciones contractuales: cuando no coincidan con lo que ves, la app tiene razón, y la fuente confiable son siempre tus propias facturas pagadas.

La comisión de las facturas

Quien paga siempre paga el monto nominal de la factura. La comisión sale del lado del comerciante: en el saldo de tu app se acredita el monto neto de comisión.

La comisión es del 1,5% del monto de la factura: una tasa única para todas las facturas, sin descuentos por volumen.

Dos reglas importan más que el número:

• La comisión se calcula y se fija en el momento del pago. Un cambio posterior de la tasa nunca toca una factura que ya se pagó.
• La comisión se redondea hacia abajo a la unidad mínima del activo, así que una factura muy pequeña puede no tener comisión.

Para ver exactamente qué se cobró, lee fee_asset y fee_amount de la factura pagada: del payload del webhook invoice_paid o de getInvoices. Esa es la cifra de referencia para tus libros.

Los reembolsos no devuelven la comisión: lo que refundInvoice le envía a quien pagó sale de tu saldo, y la comisión no se reembolsa, tampoco en un reembolso parcial.

Los cobros de suscripciones también pueden tener una comisión para el comerciante: actualmente 0%. Cada cobro informa su comisión en el campo charge.fee del webhook subscription_charged.

Límites de las transferencias

transfer tiene un máximo por transferencia de $25.000, expresado como equivalente en dólares estadounidenses, no como un monto distinto para cada activo. También puede establecerse un mínimo por transferencia; por ahora no hay ninguno. Maneja amount_too_big en tu integración y, si se introduce un mínimo, también amount_too_small cuando el monto se rechace por estos límites (ambos son 400). El máximo no se aplica a un activo que en ese momento no tiene precio en dólares.

Un username desconocido crea un pago pendiente si el modo de pagos lo permite; consulta transferencias y cheques.

Una transferencia también falla cuando:

• el saldo de tu app no alcanza en ese activo,
• quien recibe nunca abrió TgPay Crypto: un pago a un ID de Telegram desconocido o mal escrito da error en vez de acreditar una billetera que nadie va a abrir,
• la cuenta de quien recibe está bloqueada; se informa con el mismo 404 user_not_found.

Límite diario de pagos

El titular puede establecer un límite para las últimas 24 horas en la configuración de pagos de la app. Las transferencias, los cheques y los pagos desde el saldo de la app comparten ese límite. Si un pago lo supera, se devuelve 403 daily_cap_exceeded; los lotes se comprueban antes de enviar el primer pago. Los reembolsos no cuentan para este límite. getMe devuelve daily_payout_max_usd_cents y daily_payout_spent_usd_cents.

Las restricciones del titular también pueden bloquear transferencias, cheques y reembolsos (403 verification_required); una suspensión temporal devuelve 503 merchant_payouts_paused.

Límites de frecuencia

Los métodos que mueven dinero tienen un límite de frecuencia por app, compartido entre todos sus tokens y contado por separado para cada método: createInvoice y createCheck permiten 60 por minuto; refundInvoice, 30 por minuto; transfer, 30 por minuto; y transferBatch, 10 por minuto. updateApp y createSubscriptionPlan también tienen límites; consulta la referencia de la API. Si recibes rate_limited, aumenta la espera antes de volver a intentarlo.

Idempotencia

transfer exige un spend_id que generas tú; createCheck y refundInvoice aceptan uno. Reutilizar el mismo valor con los mismos parámetros devuelve el resultado original en lugar de mover fondos una segunda vez, así que una petición cuyo tiempo de espera se agotó se puede reintentar sin riesgo con el mismo spend_id, y solo se genera otro spend_id para un pago nuevo.

Qué no cuesta nada

No hay ninguna comisión de red en la API para comerciantes: las facturas, las transferencias y los cheques se liquidan dentro de la app, fuera de la cadena. Puede haber comisiones de la plataforma en las facturas y los cobros de suscripciones. Un intercambio automático opcional usa la cotización de intercambio. Al aportar fondos desde una billetera externa, esa billetera o la red pueden cobrar sus propias comisiones.

⚠️ Nunca deduzcas la comisión por tu cuenta

No fijes un porcentaje en el código ni calcules el neto a partir del monto nominal. La tasa puede cambiar, y una constante desactualizada puede introducir errores en tu contabilidad sin que te des cuenta. Lee la comisión registrada de la factura cada vez.