Commissioni e limiti della Merchant API

Le fatture hanno una commissione della piattaforma, che viene detratta da quello che incassi; trasferimenti e buoni hanno limiti di importo. I valori qui sotto sono le impostazioni attuali, non clausole contrattuali: quando non coincidono con quello che vedi ha ragione l’app, e la fonte affidabile restano sempre le tue fatture pagate.

La commissione sulle fatture

Chi paga versa sempre l’importo nominale della fattura. La commissione è a carico dell’esercente: il saldo della tua app viene accreditato dell’importo al netto della commissione.

La commissione sull’importo della fattura è 3% e scende da sola con il volume dei pagamenti degli ultimi 30 giorni:

Due regole contano più dell’importo:

• La commissione si determina e si blocca al momento del pagamento. Un cambio successivo della percentuale non tocca mai una fattura già pagata.
• La tua fascia può cambiare con il volume. Un volume di pagamenti più alto nella finestra mobile di 30 giorni può spostarti da solo su una fascia più bassa. Non devi chiederlo e non c’è niente da configurare.

Per sapere esattamente quanto ti è stato addebitato, leggi fee_asset e fee_amount dalla fattura pagata: dal payload del webhook invoice_paid o da getInvoices. Per la tua contabilità fa fede quella.

I rimborsi non restituiscono la commissione: quello che refundInvoice manda a chi aveva pagato esce dal tuo saldo, e la commissione non viene rimborsata, nemmeno su un rimborso parziale.

Anche gli addebiti degli abbonamenti hanno una commissione a carico dell’esercente: ogni addebito riporta il suo importo nel campo charge.fee del webhook subscription_charged.

I limiti sui trasferimenti

transfer è delimitato da un minimo e un massimo per trasferimento, valutati come controvalore in dollari ai tassi del momento e non come importo per asset. Un importo fuori da quell’intervallo viene rifiutato con un errore esplicito, quindi gestisci amount_too_small e amount_too_big nella tua integrazione.

Un trasferimento fallisce anche quando:

• il saldo della tua app in quell’asset non basta,
• chi riceve non è un utente dell’app: un pagamento verso un ID Telegram sconosciuto o digitato male dà errore, invece di accreditare un portafoglio che non aprirà nessuno,
• l’account di chi riceve è bloccato.

I limiti di frequenza

I metodi che muovono denaro hanno un limite di frequenza per app (condiviso tra tutti i suoi token): createInvoice e createCheck a 60 al minuto, refundInvoice e transfer a 30, transferBatch a 10. I metodi di lettura non hanno limiti. Un’integrazione fatta bene non se ne accorge nemmeno; un ciclo di tentativi sì: davanti a rate_limited rallenta invece di insistere.

L’idempotenza

transfer richiede uno spend_id che generi tu; createCheck e refundInvoice lo accettano. Riusare lo stesso valore ripete il risultato originale invece di muovere denaro una seconda volta: quindi una richiesta andata in timeout si può ritentare in sicurezza con lo stesso spend_id, e solo un pagamento davvero nuovo ne prende uno nuovo.

Che cosa non costa niente

Nella Merchant API non c’è nessuna commissione di rete: fatture, trasferimenti e buoni si chiudono tutti dentro l’app, fuori dalla catena. La commissione della piattaforma sulle fatture è l’unico addebito.

⚠️ Non calcolarti la commissione da solo

Non scrivere una percentuale fissa nel codice e non ricostruire il netto dall’importo nominale. Fasce e percentuali cambiano, e una costante vecchia ti corrompe la contabilità senza dire niente. Leggi ogni volta la commissione registrata sulla fattura.