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 3% dari jumlah faktur sebelum tingkat biaya berdasarkan volume diterapkan. Besaran biaya yang berlaku untukmu bergantung pada tingkat biaya yang diatur dan volume faktur terbayar dalam 30 hari terakhir:

Dua aturan ini lebih penting daripada angkanya:

• Biaya ditentukan dan dikunci saat pembayaran. Perubahan besaran biaya setelahnya tidak pernah menyentuh faktur yang sudah dibayar.
• Tingkat biayamu bisa berubah mengikuti volume. Volume pembayaran yang lebih besar dalam 30 hari terakhir bisa memindahkanmu ke tingkat yang lebih rendah, otomatis. Tidak perlu mengajukan apa pun dan tidak ada yang perlu diatur.

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 dikenai biaya di sisi merchant; tiap pembayaran melaporkan angkanya sendiri di field charge.fee pada webhook subscription_charged.

Batas transfer

transfer memiliki minimum dan maksimum per transfer, dinyatakan dalam nilai setara dolar AS, bukan jumlah tersendiri untuk tiap aset. Tangani amount_too_small dan amount_too_big di integrasimu jika jumlah ditolak karena batas tersebut.

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 bukan pengguna aplikasi ini — 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.

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: 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. Tingkat dan besaran biaya bisa berubah, dan konstanta yang usang akan merusak pembukuanmu tanpa terlihat. Baca biaya yang tercatat di faktur setiap kali.