Menerima pembayaran lewat faktur

Faktur adalah cara kamu meminta pembayaran dari pengguna Telegram. Buat satu lewat API, kirim linknya ke pembayar, dan saldo aplikasimu bertambah begitu dia mengonfirmasi.

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 saldonya — seketika, tanpa biaya jaringan. Pembayar yang saldonya tidak cukup bisa membayar faktur itu pakai dana dari dompet luar; fakturnya selesai otomatis begitu transfernya masuk, dan di sisimu hasilnya sama saja.
4. Kamu dapat pemberitahuan. Webhook invoice_paid terpicu, dan jumlahnya masuk ke saldo aplikasimu.
5. Penuhi pesanannya. Tidak perlu menunggu apa pun lagi; pembayarannya sudah final pada titik itu.

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 dunia nyata.

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 supaya pembayaran yang masuk langsung ditukar ke satu aset saja — berguna kalau saldomu ingin tetap dalam stablecoin tanpa perlu menukarnya sendiri.

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.

Faktur yang belum dibayar bisa dibatalkan dengan deleteInvoice.

Pengembalian dana

refundInvoice mengembalikan jumlah penuh faktur yang sudah dibayar — atau sebagiannya saja — dari saldo aplikasimu ke siapa pun yang membayarnya, termasuk pembayar anonim, tanpa membuka siapa mereka. Pengembalian sebagian menumpuk sampai jumlah penuhnya; fakturnya mencatatnya di refunded_amount. 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 TgCryptoPay-API-Signature — HMAC-SHA256 atas body mentah permintaannya, dengan kunci SHA-256 dari token API-mu — sebelum menganggap pembayaran itu sah, lalu lakukan deduplikasi berdasarkan update_id supaya percobaan ulang tidak mengirim pesanan yang sama dua kali.