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%, prima di applicare eventuali fasce legate al volume. La percentuale dipende dalle fasce configurate e dal volume delle fatture pagate negli 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

Per transfer sono previsti un minimo e un massimo per trasferimento, espressi come controvalore in dollari, non come importi distinti per asset. Se un importo viene rifiutato per questi limiti, gestisci gli errori amount_too_small e amount_too_big nella tua integrazione.

Uno username sconosciuto crea invece un pagamento in attesa, se la modalità dei pagamenti lo consente: vedi trasferimenti e buoni.

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.

Limite giornaliero dei pagamenti

Il proprietario può impostare un limite sulle ultime 24 ore nelle impostazioni dei pagamenti dell’app. Trasferimenti, buoni e pagamenti dal saldo dell’app condividono questo limite. Superarlo restituisce 403 daily_cap_exceeded; un lotto viene controllato prima del primo pagamento. I rimborsi non contano per questo limite. getMe restituisce daily_payout_max_usd_cents e daily_payout_spent_usd_cents.

Le restrizioni sull’account del proprietario possono bloccare anche trasferimenti, buoni e rimborsi (403 verification_required); una sospensione temporanea restituisce 503 merchant_payouts_paused.

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: 60 al minuto; refundInvoice: 30 al minuto; transfer: 30 al minuto; transferBatch: 10 al minuto. Anche updateApp e createSubscriptionPlan hanno limiti: vedi il riferimento API. In caso di rate_limited, aumenta l’attesa prima di riprovare.

L’idempotenza

transfer richiede uno spend_id che generi tu; createCheck e refundInvoice lo accettano. Riusare lo stesso valore con gli stessi parametri 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 vengono regolati all’interno dell’app, senza transazioni sulla blockchain. Possono applicarsi commissioni della piattaforma alle fatture e agli addebiti degli abbonamenti. Uno scambio automatico facoltativo usa la quotazione dello scambio. Versare fondi da un portafoglio esterno sul portafoglio di chi paga può comportare commissioni di quel portafoglio o della rete.

⚠️ 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.