Incassare con le fatture

Con una fattura chiedi un pagamento a un utente Telegram. La crei tramite l’API e mandi il link a chi deve pagare. Quando il pagamento va a buon fine, l’importo viene accreditato sul saldo della tua app al netto della commissione.

Come funziona

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ò versare i fondi da un portafoglio esterno, se l’opzione è disponibile. Il pagamento automatico richiede un saldo accreditato sufficiente prima del termine di pagamento e nessuna restrizione sui pagamenti in uscita. Un deposito, da solo, non dimostra che la fattura sia stata pagata.
4. Ti avvisiamo. Se hai configurato un URL per i webhook, dopo il pagamento viene messo in coda l’evento invoice_paid. La tua app riceve l’importo al netto della commissione.
5. Evadi l’ordine. Prima verifica la firma del webhook, associa la fattura al tuo ordine e controlla che lo stato sia paid. Puoi verificarlo anche con getInvoices; non servono altre conferme della blockchain.

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 per convertire i pagamenti ricevuti in un unico asset quando la conversione è disponibile. Se non può essere eseguita, il pagamento riesce comunque nell’asset originale: controlla is_swapped e i campi swapped_*.

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 inserisce chi paga al momento. Un’opzione adatta a donazioni e mance.

Descrizione, contenuti riservati e pulsante dopo il pagamento possono restare nascosti finché i contenuti non vengono approvati. Non dare per scontato che siano visibili subito dopo la creazione della fattura.

Una fattura non pagata si annulla con deleteInvoice.

I rimborsi

refundInvoice restituisce l’importo in cripto effettivamente pagato — o una sua parte qualsiasi — dal saldo della tua app a chi ha pagato, anche a chi ha pagato in forma anonima e senza rivelare chi fosse. I rimborsi parziali si sommano fino all’importo in cripto pagato in origine; la fattura li registra in refunded_amount. Per le fatture in valuta fiat, il rimborso usa paid_asset e paid_amount, non il valore nominale in valuta fiat. La tua app deve avere un saldo sufficiente nell’asset del pagamento originale, anche dopo uno scambio automatico. 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 TgPayCrypto-API-Signature — HMAC-SHA256 sul corpo grezzo della richiesta, con chiave l’SHA-256 del tuo token API principale — prima di considerare vero un pagamento, e deduplica su update_id, così un tentativo ripetuto non ti fa spedire due volte lo stesso ordine.