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 è 1,5% dell’importo della fattura: una percentuale unica per tutte le fatture, senza sconti sul volume.

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 commissione viene arrotondata per difetto all’unità minima dell’asset, quindi una fattura molto piccola può non avere commissione.

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 possono prevedere una commissione a carico del commerciante: attualmente 0%. Ogni addebito riporta la propria commissione nel campo charge.fee del webhook subscription_charged.

I limiti sui trasferimenti

transfer prevede un massimo per trasferimento di 25.000 $, espresso come controvalore in dollari USA, non come importo distinto per ogni asset. Può essere previsto anche un minimo per trasferimento; al momento non c’è. Gestisci amount_too_big nell’integrazione e, se viene introdotto un minimo, anche amount_too_small quando l’importo viene respinto per questi limiti (entrambi sono 400). Il massimo non si applica a un asset che in quel momento non ha un prezzo in dollari.

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 ha mai aperto TgPay Crypto: 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: viene segnalato con lo stesso 404 user_not_found.

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, con un conteggio separato per ogni metodo): 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 calcolare il netto dall’importo nominale. La percentuale può cambiare, e una costante non aggiornata introduce errori nella contabilità senza che te ne accorga. Leggi ogni volta la commissione registrata sulla fattura.