Menerima pembayaran lewat faktur

Faktur adalah cara kamu meminta pembayaran dari pengguna Telegram. Buat satu lewat API, kirim linknya ke pembayar, dan pembayaran yang berhasil menambah saldo aplikasimu setelah dipotong biaya merchant.

Alurnya

1. Buat fakturnya dengan createInvoice, sertakan aset dan jumlahnya (atau harga dalam fiat — lihat di bawah).
2. Kirim linknya ke pembayar dari response-nya. Begitu dibuka, dia sampai di layar Bayar faktur dalam aplikasi.
3. Dia mengonfirmasi lalu membayar dari saldo — langsung, tanpa biaya jaringan. Pembayar yang saldonya tidak cukup bisa mendanai faktur dari dompet luar jika pilihan itu tersedia. Pembayaran otomatis membutuhkan saldo yang cukup dan sudah masuk sebelum tenggat pembayaran, serta tidak adanya pembatasan pembayaran keluar. Deposit saja bukan bukti bahwa faktur sudah dibayar.
4. Kamu mendapat pemberitahuan. Jika URL webhook sudah diatur, event invoice_paid masuk antrean setelah pembayaran. Aplikasimu menerima jumlah pembayaran setelah dipotong biaya.
5. Penuhi pesanan. Verifikasi tanda tangan webhook terlebih dahulu, cocokkan faktur dengan pesanan, dan pastikan statusnya paid. Kamu juga bisa memeriksa status lewat getInvoices; tidak perlu menunggu konfirmasi blockchain tambahan.

Kalau lebih suka polling daripada webhook, getInvoices mengembalikan daftar fakturmu beserta statusnya saat ini. Webhook lebih cepat; polling cuma cadangan.

Harga dalam mata uang fiat

Faktur bisa dipatok dalam kripto, atau dalam mata uang fiat dengan daftar aset yang kamu terima. Pembayar lalu membayar dengan aset apa pun yang dia punya dari daftar itu, dihitung memakai kurs saat pembayaran. Ini pilihan yang biasa dipakai toko yang katalognya dipatok dalam mata uang fiat.

Kalau kamu ingin memberi harga yang pasti, rate_lock_seconds mengunci kurs sejak faktur dibuat untuk jangka waktu terbatas — pembayar melihat persis jumlah yang sudah terkunci, dan risiko pergerakan kurs selama menit-menit itu kamu yang tanggung. Detailnya ada di referensi faktur.

Kamu juga bisa mengatur swap_to agar pembayaran masuk ditukar ke satu aset jika penukaran tersedia. Jika tidak bisa dijalankan, pembayaran tetap berhasil dalam aset awal; periksa is_swapped dan field swapped_*.

Opsi faktur yang berguna

• description — ditampilkan ke pembayar di layar Bayar faktur.
• hidden_message — baru terbuka untuk pembayar setelah dia membayar. Ini cara mengirim kode, kunci, atau link tanpa jalur pengiriman terpisah.
• payload — string bebas milikmu sendiri, dikirim balik lewat webhook. Taruh ID pesananmu di sini.
• expires_in — batas waktu; setelah lewat, fakturnya tidak bisa dibayar lagi.
• paid_btn_name / paid_btn_url — tombol yang dilihat pembayar setelah membayar, untuk mengembalikannya ke bot, channel, atau halaman produkmu.
• open_amount — tanpa jumlah tetap; pembayar yang mengisinya saat membayar. Bentuk yang pas untuk donasi dan tip.

Deskripsi, konten tersembunyi, dan tombol setelah pembayaran mungkin tidak ditampilkan kepada pembayar sampai kontennya disetujui. Jangan mengandalkan konten itu langsung terlihat setelah faktur dibuat.

Faktur yang belum dibayar bisa dibatalkan dengan deleteInvoice.

Pengembalian dana

refundInvoice mengembalikan kripto yang benar-benar dibayarkan — atau sebagiannya saja — dari saldo aplikasimu ke siapa pun yang membayarnya, termasuk pembayar anonim, tanpa membuka siapa mereka. Total pengembalian sebagian tidak boleh melebihi jumlah kripto yang awalnya dibayarkan; faktur mencatatnya di refunded_amount. Untuk faktur fiat, pengembalian memakai paid_asset dan paid_amount, bukan nilai fiat. Aplikasimu harus memiliki saldo yang cukup dalam aset pembayaran awal, termasuk setelah penukaran otomatis. Sertakan spend_id supaya percobaan ulang setelah timeout mengulang hasil yang sama, bukan mengembalikan dana dua kali. Biaya platform tidak ikut kembali.

⚠️ Periksa tanda tangan webhook sebelum memenuhi pesanan

Siapa pun bisa mengirim POST ke webhook URL-mu. Periksa header TgPayCrypto-API-Signature — HMAC-SHA256 atas body mentah permintaannya, dengan kunci SHA-256 dari token API utamamu — sebelum menganggap pembayaran itu sah, lalu lakukan deduplikasi berdasarkan update_id supaya percobaan ulang tidak mengirim pesanan yang sama dua kali.