Konsep#

Halaman ini menjelaskan cara Reader berpikir: kapan tagihan lunas, kapan kedaluwarsa, apa yang terjadi bila HP mati, dan bagaimana transfer telat atau dobel ditangani. Baca halaman ini sebelum menulis kode yang memenuhi pesanan.

Satu prinsip berlaku di seluruh halaman: uang yang sudah masuk atau keluar tidak pernah digagalkan. Reader hanya memutuskan ke catatan mana uang itu ditautkan, dan setiap keputusan bisa dilihat kembali di dashboard.

Tagihan dan payout#

Keduanya punya nominal, kode unik, total, masa berlaku, dan reference_id. Aturan waktu, telat, dobel, dan manual di halaman ini berlaku sama untuk keduanya. Untuk payout, cukup ganti "lunas" menjadi "terkirim".

RAGH tidak memindahkan uang. Payout hanya mencatat transfer yang akan Anda lakukan, lalu membuktikannya dari notifikasi uang keluar.

Kode unik dan total unik#

• Setiap tagihan dan payout mendapat kode unik 1–999 yang ditambahkan ke nominal. Nominal Rp 200.000 dengan kode 123 menjadi total Rp 200.123.
• Yang dijaga unik adalah total per rekening per arah. Dua tagihan di rekening yang sama tidak pernah punya total yang sama selama totalnya masih terkunci. Tagihan di rekening lain boleh punya total yang sama.
• Total dikunci sampai:
  • tagihan pending: kedaluwarsa efektif + masa jeda 48 jam;
  • tagihan lunas: waktu lunas + 48 jam;
  • tagihan dibatalkan: waktu batal + 48 jam.
• Dari kode yang bebas, Reader memilih total yang paling lama tidak dipakai. Transfer yang sangat telat jadi kecil peluangnya nyasar ke tagihan baru.
• Bila semua 999 kode untuk satu nominal di satu rekening sedang terkunci, pembuatan tagihan ditolak dengan 409 unique_code_exhausted. Kapasitas praktisnya sekitar 330 tagihan per hari untuk satu nominal dasar per rekening. Bila sering terjadi, perpendek masa berlaku tagihan, bedakan nominal, atau tambah rekening.

Untuk payout, kode unik juga ditambahkan. Penerima menerima sedikit lebih banyak (paling banyak Rp 999), tidak pernah kurang dari haknya.

Uang masuk dan uang keluar tidak pernah tercampur#

• Setiap notifikasi dibaca dengan pola kalimat yang cocok persis untuk bank itu. Pola itulah yang menentukan arah: masuk (credit) atau keluar (debit). Arah tidak pernah ditebak dari kata kunci lepas.
• Notifikasi yang tidak cocok dengan pola mana pun dicatat parse_failed dan tidak diproses ke arah mana pun.
• Uang masuk hanya dicocokkan ke tagihan. Uang keluar hanya dicocokkan ke payout. Kode unik keduanya terpisah. Uang keluar Rp 150.123 tidak mungkin melunasi tagihan Rp 150.123.
• Uang masuk yang bukan pembayaran, misalnya bunga atau pengembalian dana dari bank, tidak pernah dicocokkan ke tagihan. Pengembalian dana diperiksa terhadap payout (lihat Payout dikembalikan bank).
• Uang keluar di rekening yang payout-nya tidak aktif dianggap pengeluaran pribadi Anda. Mutasinya diabaikan dan dihapus setelah 7 hari.

Status tagihan dan payout#

Tagihan (status):

Payout (status):

Tanda tambahan di data tagihan dan payout:

Rekening terpantau dan tidak terpantau#

Saat internet HP mati, app bank pun tidak menerima notifikasi. Selama itu, Reader tidak bisa melihat apa pun. Karena itu setiap rekening punya status pemantauan.

Rekening tidak terpantau bila salah satu hal ini terjadi:

Rekening dianggap pulih 15 menit setelah semua penyebab beres. Jeda 15 menit memberi waktu bagi notifikasi yang tertahan untuk menyusul.

Pemilik dan admin akun dikabari lewat email (dan WhatsApp, bila nomor HP terisi di profil) saat rekening tidak terpantau, 1 jam kemudian, 6 jam kemudian, dan saat pulih kembali.

Selama tidak terpantau:

• tagihan dan payout pending mendapat confirmation_delayed: true;
• halaman bayar menampilkan "Konfirmasi tertunda. Kalau sudah transfer, jangan transfer lagi.";
• tagihan baru tanpa bank_code diarahkan ke rekening lain yang terpantau, bila ada.

Penahanan batas bayar#

Tagihan tidak pernah kedaluwarsa selama rekeningnya tidak terpantau. Pembeli yang sudah transfer saat HP Anda mati tidak boleh melihat tagihannya kedaluwarsa.

kedaluwarsa efektif = paling akhir di antara:
                        - expires_at
                        - waktu rekening pulih + 15 menit
                      paling lama expires_at + 7 hari

Contoh: tagihan berlaku sampai 14.00. HP mati pukul 13.30 dan menyala lagi pukul 16.00. Rekening pulih pukul 16.15, jadi tagihan baru bisa kedaluwarsa setelah 16.15. Selama 13.30–16.15, status tetap pending dengan confirmation_delayed: true.

Field expires_at di API tetap menunjukkan batas awal. Yang menentukan adalah status.

Masa berlaku tagihan: bawaan 24 jam, bisa diatur 15 menit sampai 7 hari (expires_in_minutes).

Transfer telat: dicatat, tidak digagalkan#

Aturan untuk sistem Anda:

• payment.expired belum final selama masa jeda. Jangan anggap tagihan gagal permanen, dan jangan menghapus pesanan.
• Jangan membatalkan pesanan yang sudah dipenuhi karena event yang datang belakangan.
• Rekomendasi untuk late: true: penuhi pesanannya. Pembeli sudah membayar.

Setelah masa jeda: cocokkan manual#

Transfer yang datang lebih dari 48 jam setelah tagihan selesai tidak lagi dicocokkan otomatis, karena totalnya mungkin sudah dipakai tagihan lain. Mutasinya masuk daftar perlu tindakan sebagai "Mutasi tanpa tagihan", lengkap dengan saran tagihan yang mungkin dimaksud. Cocokkan dari dashboard, menu Mutasi. Setelah dicocokkan, tagihan menjadi lunas dan webhook payment.paid terkirim seperti biasa.

Bayar lagi berarti perpanjang tagihan yang sama#

Bila pembeli ingin membayar tagihan yang sudah kedaluwarsa, perpanjang tagihan yang sama, jangan buat tagihan baru. Kode dan totalnya tetap sama, sehingga transfer yang sempat terkirim tetap cocok.

• Lewat API: POST /api/v1/payments/{id}/extend.
• Lewat API juga: panggil ulang POST /api/v1/payments dengan reference_id dan amount yang sama. Tagihan kedaluwarsa dalam masa jeda dibuka lagi.
• Lewat halaman bayar: pembeli bisa menekan perpanjang 60 menit, bila pengaturan aplikasi Anda mengizinkan perpanjangan (menyala secara bawaan).

Perpanjangan hanya bisa untuk tagihan pending, atau expired yang masih dalam masa jeda.

Uang dobel#

Tagihan lunas tidak pernah berubah karena uang dobel. Refund atau penagihan kembali adalah tanggung jawab Anda.

Bila satu tagihan untuk sebuah reference_id lunas, tagihan lain yang masih pending untuk reference_id yang sama otomatis dibatalkan.

Lunas manual dan verifikasi#

Kadang Anda perlu menandai tagihan lunas sebelum notifikasinya datang, misalnya karena pembeli mengirim bukti transfer.

1. Tandai lunas dari dashboard (menu Transaksi). Aksi ini tidak tersedia lewat API, dan tercatat siapa yang melakukannya.
2. Tagihan menjadi paid dengan match_type: manual_unverified. Webhook payment.paid terkirim dengan mutation: null.
3. Bila notifikasi transfernya datang kemudian, tagihan menjadi terverifikasi (match_type: manual) dan webhook payment.verified terkirim. Notifikasi itu tidak dihitung sebagai uang dobel.
4. Bila dalam 24 jam notifikasinya tidak pernah datang, tagihan masuk perlu tindakan: "Selesai manual belum terverifikasi". Cek mutasi bank Anda. Bukti transfer bisa dipalsukan, notifikasi bank tidak.

Hal yang sama berlaku untuk payout (payout.verified).

Payout: aturan khusus#

• Satu payout = satu transfer. Transfer massal (bulk) tidak didukung.
• Transfer dari app bank rekening sumber, di HP yang dibaca Reader.
• Reader membaca nominal pokok, bukan pokok + biaya transfer antarbank.
• Cek penerima. Bila notifikasi bank memuat nama atau potongan nomor penerima, keduanya dibandingkan dengan recipient. Bila berbeda, payout tetap sent (uangnya memang sudah keluar), tetapi recipient_check: "mismatch" dan kejadiannya masuk perlu tindakan.

Payout dikembalikan bank#

Bila bank mengembalikan transfer (misalnya rekening tujuan tutup), notifikasi pengembalian dana dengan total yang sama dalam masa jeda membuat payout menjadi reversed. Webhook payout.reversed terkirim, dan kejadiannya masuk perlu tindakan. Untuk mentransfer ulang, buat payout baru dengan reference_id yang sama.

Perlu tindakan#

Kejadian yang butuh keputusan Anda dikumpulkan di menu Perlu tindakan di dashboard. Setiap butir diselesaikan dengan memilih salah satu penyelesaian.

Nomor transaksi berprefix#

Setiap tagihan dan payout mendapat nomor transaksi (tx_number) dengan format:

<PREFIX>-<YYMMDD>-<urutan>        contoh: TKO-260928-0042

• PREFIX dipilih per aplikasi saat membuat aplikasi, 3–4 huruf, unik di akun Anda. Dengan prefix, Anda langsung tahu transaksi itu dari produk mana.
• YYMMDD adalah tanggal dibuat (WIB).
• urutan 4 digit, dimulai dari 0001 setiap hari, dan dipakai bersama oleh tagihan dan payout aplikasi yang sama.
• Nomor transaksi tampil di dashboard, webhook, dan halaman bayar, dan bisa dicari di kotak pencarian dashboard.

Kode unik tidak dibagi per produk. Semua aplikasi Anda berbagi kode unik di rekening yang sama. Pembedanya adalah nomor transaksi.

Mode uji dan rekening UJI#

• Kode unik data uji dan data live terpisah, jadi transfer sungguhan tidak pernah melunasi tagihan uji.
• Bila akun belum punya rekening terverifikasi, atau Anda mengirim "bank_code": "UJI", tagihan uji memakai rekening UJI virtual: kode bank UJI, nomor 0000000000, atas nama " (UJI)". Rekening UJI selalu terpantau dan payout-nya aktif.
• Bila akun sudah punya rekening terverifikasi dan Anda tidak mengirim bank_code: "UJI", tagihan uji memakai rekening sungguhan Anda sebagai tujuan, tetapi tetap berstatus data uji.
• Webhook untuk data uji dikirim ke callback_url yang sama, dengan "test": true. Jangan memenuhi pesanan sungguhan dari event uji.

Status mutasi#

Setiap notifikasi yang diterima server menjadi satu mutasi. Kolom match_status menjelaskan apa yang terjadi:

is_match bernilai true bila mutasi tertaut ke tagihan atau payout.