Aceptar pagos con facturas

Una factura te permite cobrarle a un usuario de Telegram. La creas por la API y le envías el enlace. Cuando el pago se completa, el monto se abona al saldo de tu app, descontando la comisión para comerciantes.

El flujo

1. Crea la factura con createInvoice, indicando un activo y un monto (o un precio en fiat, como se explica más abajo).
2. Envía el enlace a quien paga. Lo encontrarás en la respuesta. Al abrirlo, esa persona accede a la pantalla de pago de la app.
3. La persona confirma y paga con su saldo, al instante y sin comisión de red. Si no tiene saldo suficiente, puede aportar fondos desde una billetera externa cuando esa opción esté disponible. El pago automático requiere saldo suficiente abonado antes de la fecha límite y que no haya restricciones para los pagos salientes. Un depósito por sí solo no demuestra que se haya pagado la factura.
4. Recibes un aviso. Si configuraste una URL de webhook, el evento invoice_paid se pone en cola tras el pago. Tu app recibe el monto menos la comisión.
5. Entrega el pedido. Primero verifica la firma del webhook, comprueba que la factura corresponda a tu pedido y confirma que su estado sea paid. También puedes consultar el estado con getInvoices; no hacen falta más confirmaciones de la blockchain.

Si prefieres consultar el estado en lugar de recibir un webhook, getInvoices devuelve tus facturas con su estado actual. El webhook es la vía más rápida; la consulta periódica sirve como alternativa.

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 fiat.

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 usar swap_to para convertir los pagos entrantes a un solo activo cuando la conversión esté disponible. Si no se puede realizar, el pago se completa en el activo original. Consulta is_swapped y los campos swapped_*.

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.

La descripción, el contenido oculto y el botón posterior al pago pueden permanecer ocultos hasta que se apruebe su contenido. No des por hecho que estarán visibles en cuanto crees la factura.

Una factura sin pagar se puede cancelar con deleteInvoice.

Reembolsos

refundInvoice devuelve la cripto que se pagó —o cualquier parte de ella— desde el saldo de tu app a quien pagó, incluso si lo hizo de forma anónima, sin revelar su identidad. Los reembolsos parciales se acumulan hasta el monto en cripto originalmente pagado; la factura los registra en refunded_amount. En las facturas fiat, el reembolso usa paid_asset y paid_amount, no el valor nominal en fiat. Tu app debe tener saldo suficiente en el activo del pago original, incluso si se realizó un intercambio automático. Usa un spend_id para que, al repetir una solicitud tras agotar el tiempo de espera, se devuelva el resultado anterior 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 original de la petición, sin modificar, usando como clave el SHA-256 de tu token principal de API— antes de dar un pago por real, y deduplica por update_id para que un reintento no despache el pedido dos veces.