Siklus hidup tagihan
Tagihan berjalan dari pembuatan hingga ditutup atau kedaluwarsa. Bagian ini menjelaskan status yang bisa dialaminya, cara berpindah antarstatus, dan apa yang dapat dilakukan merchant di setiap langkah.
Status tagihan
| Status | Nilai API | Deskripsi | Masuk pencarian pembayaran |
|---|---|---|---|
| Belum dibayar (Unpaid) | unpaid | Tagihan diterbitkan, batas waktu pembayaran belum lewat, belum ada pembayaran masuk | Ya |
| Dibayar (Paid) | paid | Pembayaran ditemukan dan dicocokkan dengan tagihan | Tidak |
| Kedaluwarsa (Expired) | expired | Batas waktu pembayaran sudah lewat, tidak ada pembayaran masuk | Ya, selama satu jam lagi setelah kedaluwarsa |
| Dibatalkan (Canceled) | canceled | Tagihan dibatalkan oleh merchant secara manual atau lewat API | Tidak |
Transisi status
- Pembuatan tagihan. Tagihan langsung mendapat status Belum dibayar.
- Belum dibayar → Dibayar. Pembayaran dengan jumlah persis sesuai tagihan masuk, atau merchant mencocokkan pembayaran secara manual.
- Belum dibayar → Kedaluwarsa. Batas waktu pembayaran lewat tanpa ada pembayaran masuk.
- Belum dibayar → Dibatalkan. Merchant membatalkan tagihan.
- Kedaluwarsa → Dibayar. Pembayaran masuk dalam satu jam setelah kedaluwarsa dan ditemukan otomatis, atau merchant mencocokkannya secara manual.
- Dibatalkan. Status akhir; tidak ada jalan kembali.
Tagihan berstatus Dibayar juga tidak berubah status—tidak bisa dibayar lagi atau dibatalkan.
Batas waktu pembayaran
Batas waktu ditetapkan saat pembuatan tagihan dan berkisar dari 30 menit hingga 12 jam. Nilai yang diizinkan: 30 menit, 1 jam, 3 jam, 6 jam, 12 jam.
Sebelum batas waktu, pembeli melihat formulir pembayaran dan dapat membayar tagihan. Setelah lewat, tagihan berpindah ke Kedaluwarsa dan formulir pembayaran tidak lagi menawarkan pembayaran.
Kedua ekstrem punya harganya. Batas waktu pendek berisiko di jaringan lambat—pembeli bisa tidak sempat. Batas waktu panjang memperlebar selisih antara kurs saat pembuatan tagihan dan kurs saat pembayaran.
Jendela pencarian pembayaran
Pencarian pembayaran berlanjut satu jam lagi setelah batas waktu pembayaran—untuk mengantisipasi jaringan lambat, tempat transaksi bisa terkonfirmasi setelah tagihan resmi kedaluwarsa. Selama itu pembeli melihat tagihan sebagai kedaluwarsa, tetapi begitu pembayaran dengan jumlah tepat masuk, tagihan otomatis berpindah ke Dibayar beserta semua notifikasinya.
Dari sini aturan untuk integrator: jangan menolak notifikasi pembayaran karena batas waktunya sudah lewat—pemeriksaan itu memangkas sebagian pembayaran nyata.
Membatalkan tagihan
Anda dapat membatalkan tagihan jika ada kesalahan di dalamnya. Pembatalan memerlukan dua syarat:
- Tagihan belum dibayar—artinya, berstatus Belum dibayar
- Belum ada yang membuka halaman pembayaran tagihan; penghitung tampilan nol
Syarat kedua melindungi dari pembatalan tagihan yang sudah dilihat pembeli dan mungkin mulai dibayar.
Pembatalan tidak dapat dibatalkan kembali. Tagihan yang dibatalkan dikeluarkan dari pencarian pembayaran, dan pembayaran tidak dapat dicocokkan dengannya bahkan secara manual. Jika pembayaran masih mungkin terjadi, tunggu batas waktunya lewat alih-alih membatalkan—tagihan kedaluwarsa masih bisa ditutup dengan pembayaran.
Apa yang dikunci saat pembuatan dan apa yang dihitung ulang saat pembayaran
Saat pembuatan tagihan, layanan mengonversi jumlah fiat menjadi kripto dengan kurs terkini dan mengunci jumlah hasilnya untuk tagihan itu. Jumlah inilah yang dilihat pembeli, dan inilah yang dicari layanan di on-chain. Kurs tidak lagi memengaruhinya: berapa pun waktu berlalu, pembeli membayar persis jumlah yang dikunci.
Pada saat pembayaran, jumlah akuntansinya dihitung ulang:
| Field | Apa yang terjadi |
|---|---|
amountFiat | Jumlah asli tagihan dalam mata uang fiat. Tidak pernah berubah |
amountFiatUSD | Ditimpa dengan jumlah yang benar-benar diterima, dikonversi ke USD dengan kurs pada saat pembayaran |
commissionFiatUSD | Dihitung ulang dari nilai amountFiatUSD yang baru menurut tarif proyek |
Karena pergerakan kurs, nilai-nilai ini bisa berbeda dari nilai awal bahkan saat pembayarannya tepat. Untuk rekonsiliasi dengan pesanan di toko Anda, gunakan amountFiat—satu-satunya jumlah yang tetap tidak berubah.
Notifikasi sepanjang hidup tagihan
Notifikasi diatur per proyek. Tagihan memiliki dua notifikasi:
- Pembayaran masuk (Incoming payment). Dikirim ke email dan Telegram saat transaksi masuk apa pun terdeteksi di dompet Anda, terlepas dari cocok atau tidaknya dengan tagihan.
- Tagihan dibayar (Invoice paid). Dikirim ke email, Telegram, dan Webhook URL begitu tagihan berpindah ke Dibayar—baik pada pencocokan otomatis maupun manual.
Ini memberi aturan diagnostik sederhana: jika notifikasi pembayaran masuk tiba tetapi notifikasi tagihan dibayar tidak menyusul, pembayaran tidak cocok karena selisih jumlah dan memerlukan penanganan manual.
Mengembalikan pembeli ke situs toko
Di pengaturan proyek, Anda dapat menetapkan dua URL tempat pembeli kembali dari halaman pembayaran:
- URL sukses (Successful URL)—pengalihan otomatis setelah tagihan dibayar
- URL gagal (Unsuccessful URL)—pengalihan otomatis saat tagihan kedaluwarsa atau dibatalkan dibuka
Setiap URL diaktifkan terpisah. Jika URL tidak diisi, pembeli tetap berada di halaman pembayaran dan melihat status tagihan.
Parameter uid—identifikasi tagihan untuk pembeli—ditambahkan ke URL: https://example.com/order/success?uid=AFhygKX21ecd. Toko menggunakannya untuk menemukan pesanan dan menampilkan halamannya sendiri kepada pembeli.
Mendarat di URL tersebut tidak mengonfirmasi pembayaran—pembeli bisa membuka tautannya secara manual. Kirim pesanan berdasarkan webhook atau setelah memeriksa status tagihan lewat API.