Biaya dan batas Merchant API

Faktur dikenai biaya platform yang dipotong dari yang kamu terima; transfer dan cek kripto punya batas jumlah. Angka di bawah ini adalah pengaturan yang berlaku sekarang, bukan syarat kontrak — kalau berbeda dengan yang kamu lihat, ikuti yang ada di aplikasi, dan sumber paling tepercaya selalu faktur yang sudah dibayar di akunmu sendiri.

Biaya faktur

Pembayar selalu membayar jumlah penuh yang tertera di faktur. Biayanya ditanggung sisi merchant: saldo aplikasimu bertambah sebesar jumlah setelah dipotong biaya.

Biayanya 1,5% dari jumlah faktur — besaran biayanya sama untuk semua faktur, tanpa potongan berdasarkan volume.

Dua aturan ini lebih penting daripada angkanya:

• Biaya ditentukan dan dikunci saat pembayaran. Perubahan besaran biaya setelahnya tidak pernah menyentuh faktur yang sudah dibayar.
• Biaya dibulatkan ke bawah ke satuan terkecil aset, jadi faktur yang sangat kecil bisa saja tidak kena biaya sama sekali.

Untuk tahu persis berapa yang dipotong, baca fee_asset dan fee_amount dari faktur yang sudah dibayar — lewat payload webhook invoice_paid atau lewat getInvoices. Angka itulah yang sah untuk pembukuanmu.

Pengembalian dana tidak mengembalikan biayanya: dana yang dikirim refundInvoice ke pembayar diambil dari saldomu, dan biayanya tidak ikut kembali — termasuk pada pengembalian sebagian.

Pembayaran langganan juga bisa dikenai biaya di sisi merchant — saat ini 0%. Setiap pembayaran mencatat biayanya sendiri di field charge.fee pada webhook subscription_charged.

Batas transfer

transfer memiliki maksimum per transfer sebesar $25.000, dinyatakan dalam nilai setara dolar AS, bukan jumlah terpisah untuk setiap aset. Minimum per transfer juga bisa ditetapkan; saat ini tidak ada minimum. Tangani amount_too_big dalam integrasi dan, jika minimum diberlakukan, amount_too_small ketika jumlah ditolak karena batas tersebut (keduanya 400). Maksimum ini tidak berlaku untuk aset yang saat itu tidak punya harga dalam dolar AS.

Untuk username yang belum dikenal, pembayaran dibuat dengan status menunggu jika mode pembayaran mengizinkannya; lihat transfer dan cek.

Transfer juga gagal kalau:

• saldo aplikasimu tidak cukup di aset itu,
• penerimanya belum pernah membuka TgPay Crypto — pembayaran ke ID Telegram yang tidak dikenal atau salah ketik akan error, bukan mengisi dompet yang tidak akan pernah dibuka siapa pun,
• akun penerimanya diblokir — dilaporkan dengan 404 user_not_found yang sama.

Batas pembayaran harian

Pemilik bisa menetapkan batas untuk 24 jam terakhir di pengaturan pembayaran aplikasi. Transfer, cek, dan pembayaran dari saldo aplikasi memakai batas yang sama. Jika terlampaui, API mengembalikan 403 daily_cap_exceeded; batch diperiksa sebelum pembayaran pertamanya. Pengembalian dana tidak dihitung dalam batas ini. getMe mengembalikan daily_payout_max_usd_cents dan daily_payout_spent_usd_cents.

Pembatasan pemilik juga bisa menghalangi transfer, cek, dan pengembalian dana (403 verification_required); penghentian sementara mengembalikan 503 merchant_payouts_paused.

Batas frekuensi permintaan

Metode yang memindahkan dana dibatasi per aplikasi, dihitung untuk semua tokennya dan terpisah untuk tiap metode: createInvoice dan createCheck 60 per menit, refundInvoice 30 per menit, transfer 30 per menit, dan transferBatch 10 per menit. updateApp dan createSubscriptionPlan juga memiliki batas; lihat referensi API. Saat menerima rate_limited, tambah jeda sebelum mencoba lagi.

Idempotensi

transfer wajib disertai spend_id yang kamu buat sendiri; createCheck dan refundInvoice juga menerimanya. Mengirim nilai yang sama dengan parameter yang sama akan mengulang hasil yang pertama, bukan memindahkan dana untuk kedua kalinya — jadi permintaan yang timeout aman diulang dengan spend_id yang sama, dan hanya pembayaran yang benar-benar baru yang pakai nilai baru.

Yang tidak dikenai biaya

Tidak ada biaya jaringan di mana pun dalam Merchant API — faktur, transfer, dan cek semuanya diselesaikan di dalam aplikasi, di luar blockchain. Biaya platform bisa berlaku untuk faktur dan pembayaran langganan. Penukaran otomatis opsional memakai penawaran kurs penukaran. Mengisi dompet pembayar dari dompet luar mungkin dikenai biaya oleh dompet atau jaringan tersebut.

⚠️ Jangan hitung sendiri biayanya

Jangan menulis persentasenya sebagai konstanta di kode atau menghitung ulang jumlah bersih dari jumlah penuh. Besaran biaya bisa berubah, dan konstanta yang usang akan merusak pembukuanmu tanpa terlihat. Baca biaya yang tercatat di faktur setiap kali.