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: el saldo de tu app se acredita el monto neto de comisión.

La comisión es del 3% del monto de la factura, y baja automáticamente con tu volumen de pagos de los últimos 30 días:

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

• La comisión se resuelve 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 está acotado por un mínimo y un máximo por transferencia, aplicados como una estimación equivalente en dólares a los tipos de cambio del momento y no como una cifra por activo. Un monto fuera de ese rango se rechaza con un error explícito, así que maneja amount_too_small y amount_too_big en tu integración.

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í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 a 60 por minuto, refundInvoice y transfer a 30, transferBatch a 10. Los métodos de lectura no tienen límite. Una integración que se porta bien nunca lo nota; un bucle de reintentos sí: haz retroceso ante rate_limited en vez de insistir.

Idempotencia

transfer exige un spend_id que generas tú; createCheck y refundInvoice aceptan uno. Reutilizar el mismo valor repite el resultado original en lugar de mover fondos una segunda vez, así que una petición que se agotó por tiempo se puede reintentar sin riesgo con el mismo spend_id, y solo un pago genuinamente nuevo recibe uno 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. La comisión de la plataforma sobre las facturas es el único cargo.

⚠️ 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.