Aceptar pagos con facturas

Una factura es la forma de cobrarle a un usuario de Telegram. Creas una por la API, le envías su enlace a quien paga y el saldo de tu app se acredita en el instante en que esa persona confirma.

El flujo

1. Crea la factura con createInvoice, dando un activo y un monto (o un precio en fiat — mira más abajo).
2. Envíale el enlace a quien paga, desde la respuesta. Al abrirlo llega a la pantalla de pago de la app.
3. Confirma y paga con su saldo, al instante y sin comisión de red. Quien no tenga saldo suficiente puede financiar la factura desde una billetera externa; se liquida sola cuando llega su transferencia, y para ti se ve igual.
4. Se te avisa. Se dispara el webhook invoice_paid y el monto llega al saldo de tu app.
5. Despacha el pedido. No esperes nada más; en ese punto el pago es final.

Si prefieres consultar en vez de recibir un webhook, getInvoices devuelve tus facturas con su estado actual. El webhook es el camino más rápido; consultar es el plan B.

Poner el precio en fiat

Una factura puede tener precio en cripto o en una moneda fiat con una lista de activos aceptados. Quien paga entonces liquida con el activo aceptado que tenga, convertido al tipo de cambio del momento del pago. Es la elección habitual para una tienda cuyo catálogo está en una moneda del mundo real.

Si prefieres cotizar un precio firme, rate_lock_seconds congela los tipos de conversión al crearla durante una ventana acotada: quien paga ve exactamente los montos fijados y tú asumes el riesgo de tipo de cambio durante esos minutos. Detalles en la referencia de facturas.

También puedes fijar swap_to para que los pagos entrantes se conviertan a un solo activo a medida que llegan — útil para mantener tu saldo en una stablecoin sin hacer los intercambios tú.

Opciones útiles de las facturas

• description — se le muestra a quien paga en la pantalla de pago.
• hidden_message — se le revela a quien paga solo después de pagar. Así entregas un código, una clave o un enlace sin un canal de entrega aparte.
• payload — tu propia cadena opaca, devuelta en el webhook. Pon aquí el ID de tu pedido.
• expires_in — un plazo, pasado el cual la factura ya no se puede pagar.
• paid_btn_name / paid_btn_url — el botón que ve quien paga después de pagar, para devolverlo a tu bot, a tu canal o a la página del producto.
• open_amount — sin monto fijo; quien paga ingresa uno al momento de pagar. La forma natural para donaciones y propinas.

Una factura sin pagar se puede cancelar con deleteInvoice.

Reembolsos

refundInvoice devuelve el monto nominal de una factura pagada —o cualquier parte de él— desde el saldo de tu app a quien la pagó, incluso a quienes pagaron de forma anónima, sin revelar quiénes eran. Los reembolsos parciales se acumulan hasta el monto nominal; la factura los sigue en refunded_amount. Pasa un spend_id para que un reintento por tiempo agotado repita en vez de reembolsar dos veces. La comisión de la plataforma no se reembolsa.

⚠️ Verifica la firma del webhook antes de despachar

Cualquiera puede hacer POST a tu URL de webhook. Revisa la cabecera TgPayCrypto-API-Signature —HMAC-SHA256 sobre el cuerpo crudo de la petición, con clave el SHA-256 de tu token de API— antes de dar un pago por real, y deduplica por update_id para que un reintento no despache el pedido dos veces.