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, dan turun otomatis mengikuti volume pembayaran 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 dibatasi oleh minimum dan maksimum per transfer, dihitung sebagai perkiraan setara dolar AS memakai kurs saat itu, bukan angka per aset. Jumlah di luar rentang itu ditolak dengan error yang jelas, jadi tangani amount_too_small dan amount_too_big di integrasimu.

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 frekuensi permintaan

Metode yang memindahkan dana dibatasi per aplikasi (dihitung gabungan untuk semua tokennya): createInvoice dan createCheck 60 per menit, refundInvoice dan transfer 30, transferBatch 10. Metode baca tidak dibatasi. Integrasi yang wajar tidak akan pernah menyentuhnya; loop retry pasti kena — begitu muncul rate_limited, beri jeda sebelum mencoba lagi, jangan mengulang tanpa henti.

Idempotensi

transfer wajib disertai spend_id yang kamu buat sendiri; createCheck dan refundInvoice juga menerimanya. Mengirim nilai yang sama dua kali 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 pada faktur adalah satu-satunya pungutan.

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