Incassare con le fatture

La fattura è il modo in cui addebiti qualcosa a un utente Telegram. La crei dall’API, mandi il link a chi deve pagare e il saldo della tua app viene accreditato nell’istante in cui quella persona conferma.

Il giro completo

1. Crei la fattura con createInvoice, indicando asset e importo (o un prezzo in valuta fiat: vedi sotto).
2. Mandi il link che trovi nella risposta a chi deve pagare. Aprendolo, quella persona arriva alla schermata di pagamento dell’app.
3. Conferma e paga dal suo saldo: all’istante e senza commissione di rete. Chi non ha abbastanza saldo può coprire la fattura da un portafoglio esterno; si salda da sola quando il suo trasferimento arriva, e per te è identica.
4. Ti avvisiamo. Parte il webhook invoice_paid e l’importo arriva sul saldo della tua app.
5. Evadi l’ordine. Non aspettare altro: a quel punto il pagamento è definitivo.

Se preferisci interrogare l’API invece di ricevere un webhook, getInvoices restituisce le tue fatture con lo stato aggiornato. Il webhook è la strada più veloce; interrogare l’API è l’alternativa di riserva.

Il prezzo in valuta fiat

Il prezzo di una fattura può essere in cripto oppure in una valuta fiat, con un elenco di asset accettati. Chi paga salda con quello che ha tra gli asset accettati, convertito al tasso del momento del pagamento. È la scelta abituale per un negozio il cui catalogo è in euro o in dollari.

Se preferisci fissare un prezzo fermo, rate_lock_seconds blocca i tassi di conversione alla creazione per una finestra limitata: chi paga vede esattamente gli importi bloccati, e per quei minuti il rischio di cambio te lo prendi tu. I dettagli sono nel riferimento delle fatture.

Puoi anche impostare swap_to, così i pagamenti in arrivo vengono convertiti in un unico asset man mano che arrivano: comodo per tenere il saldo in una stablecoin senza doverti fare gli scambi a mano.

Le opzioni utili di una fattura

• description — quello che chi paga vede sulla schermata di pagamento.
• hidden_message — si svela a chi paga solo dopo il pagamento. È così che consegni un codice, una chiave o un link senza un canale di consegna a parte.
• payload — una tua stringa opaca, che ti rimandiamo indietro nel webhook. Mettici l’ID del tuo ordine.
• expires_in — un termine, superato il quale la fattura non si paga più.
• paid_btn_name / paid_btn_url — il pulsante che chi paga vede dopo aver pagato, per rimandarlo al tuo bot, al tuo canale o alla pagina del prodotto.
• open_amount — nessun importo fisso: lo digita chi paga al momento. La forma naturale per donazioni e mance.

Una fattura non pagata si annulla con deleteInvoice.

I rimborsi

refundInvoice restituisce l’importo nominale di una fattura pagata — o una sua parte qualsiasi — dal saldo della tua app a chi l’ha pagata, anche a chi ha pagato in forma anonima e senza rivelare chi fosse. I rimborsi parziali si sommano fino all’importo nominale; la fattura li tiene in refunded_amount. Passa uno spend_id, così un tentativo andato in timeout ripete la risposta invece di rimborsare due volte. La commissione della piattaforma non viene rimborsata.

⚠️ Verifica la firma del webhook prima di evadere

Al tuo URL può mandare un POST chiunque. Controlla l’intestazione TgCryptoPay-API-Signature — HMAC-SHA256 sul corpo grezzo della richiesta, con chiave l’SHA-256 del tuo token API — prima di considerare vero un pagamento, e deduplica su update_id, così un tentativo ripetuto non ti fa spedire due volte lo stesso ordine.