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 3% del monto de la factura antes de aplicar los descuentos por volumen. La tasa depende de los niveles configurados y del volumen de facturas pagadas durante los últimos 30 días:

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ó.
• Tu tasa puede cambiar con tu volumen. Un volumen de pagos mayor en una ventana móvil de 30 días te puede mover a un nivel más bajo automáticamente. No lo solicitas y no hay nada que configurar.

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 suscripción también llevan una comisión del lado del comerciante; cada cobro informa su propia cifra en el campo charge.fee del webhook subscription_charged.

Límites de las transferencias

transfer tiene un mínimo y un máximo por transferencia, expresados como un equivalente en dólares y no como un monto distinto para cada activo. Gestiona los errores amount_too_small y amount_too_big en tu integración cuando se rechace un monto por esos límites.

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 no es usuario de la app: 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.

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: 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 reconstruyas el neto a partir del monto nominal. Los niveles y las tasas cambian, y una constante desactualizada corrompe tu contabilidad en silencio. Lee la comisión registrada de la factura cada vez.