# Tambahan Tripay — versi 1.1

Pilihan pembayaran sekarang: transfer manual, Midtrans, dan Tripay. Tripay tersedia untuk donasi program maupun pembayaran zakat, termasuk hasil kalkulator. Integrasi memakai closed payment dan halaman checkout penyedia. Kanal aktif diambil dari akun merchant, bukan daftar statis.

## Instalasi baru
Ikuti PANDUAN.md. Installer menjalankan migrasi tambahan secara otomatis. Setelah login Super Admin, buka **Pengaturan → Tripay**.

## Memperbarui aplikasi versi 1.0 di cPanel
1. Cadangkan database, .env, seluruh kode dan storage/app. Lakukan pembaruan pada waktu sepi.
2. Upload ZIP baru ke folder sementara dan Extract, terpisah dari aplikasi aktif.
3. Salin folder app, resources, routes dan public/assets ke aplikasi aktif. Ganti bootstrap/app.php serta config/services.php dengan versi baru.
4. Salin database/migrations/2026_09_08_000001_create_tripay_payments.php ke folder migrasi aplikasi.
5. Pertahankan **.env, APP_KEY, seluruh storage, dan storage/installed.lock**. Jangan menjalankan installer ulang. Jangan menyalin setup-token.txt ke aplikasi aktif.
6. Hapus berkas cache PHP yang dihasilkan pada bootstrap/cache dan berkas Blade terkompilasi pada storage/framework/views (pertahankan .gitignore). Jangan menghapus storage/app atau sesi donatur.
7. Login sebagai Super Admin, buka **Pengaturan**, lalu klik **Terapkan pembaruan database Tripay**. Tindakan ini menambahkan tabel tripay_payments dan dapat diulang tanpa membuat duplikasi. Tidak menjalankan migrate:fresh dan tidak menghapus transaksi lama.
8. Isi konfigurasi Tripay dan lakukan uji sandbox pada salinan database terpisah.

Tidak ada paket Composer baru untuk integrasi ini. vendor lama versi 1.0 dapat dipertahankan saat update; ZIP lengkap juga memuat dependensi produksi untuk instalasi baru. Jika Anda mengubah kode versi 1.0 sendiri, gabungkan perubahan tersebut sebelum menyalin.

## Konfigurasi akun lembaga
Di **Pengaturan → Tripay**:
- Aktifkan pilihan Tripay.
- Isi **Kode merchant, API Key, dan Private Key** untuk sandbox.
- Untuk produksi, isi tiga kredensial pada bagian produksi secara terpisah.
- Pilih mode untuk tagihan baru. Kunci API/private disimpan terenkripsi dan tidak ditampilkan kembali. Isian kosong mempertahankan nilai.
- Atur Callback URL di akun merchant: **https://domain-anda/webhooks/tripay**.
- Return URL: **https://domain-anda/pembayaran/selesai**.
- Aktifkan kanal pada akun Tripay sesuai kebutuhan lembaga.

Kredensial sandbox dan produksi berbeda. Tagihan menyimpan mode asal sehingga callback lama tetap diperiksa dengan kredensial yang sesuai. Menonaktifkan Tripay menyembunyikan pilihan untuk tagihan baru; callback tagihan yang telah dibuat tetap dapat diproses. Jangan mengganti merchant/kunci mode yang sama selama masih ada tagihan yang perlu ditangani.

Variabel TRIPAY_* pada .env.example merupakan fallback kredensial jika setting dashboard kosong. Aktivasi pilihan pembayaran dilakukan dari dashboard. Tidak ada kredensial asli dalam paket.

## Alur donatur dan biaya
Pilih Tripay, pilih kanal aktif, isi email dan nomor WhatsApp, lalu buat tagihan. Nominal harus berada dalam batas kanal. Email dan nomor kontak diwajibkan untuk Tripay agar dapat digunakan pada kanal yang memerlukan data tersebut.

Tagihan menampilkan:
- nilai donasi/zakat;
- biaya pelanggan dari respons server Tripay;
- total yang harus dibayar;
- kanal dan tautan checkout resmi.

Biaya pelanggan bukan donasi dan tidak menambah dana terkumpul. Biaya merchant dan nilai bersih penerimaan dicatat pada rincian internal Tripay untuk rekonsiliasi. **Biaya ledger masih dicatat petugas satu kali** melalui Penyaluran & biaya; jangan mencatat biaya pelanggan sebagai penerimaan. Untuk zakat, ikuti kebijakan sumber biaya lembaga dan jangan mengurangi kewajiban muzakki tanpa peninjauan amil.

Batas pembayaran mengikuti waktu kedaluwarsa dari Tripay. Kanal yang gagal dimuat tidak ditampilkan; metode lain tetap tersedia. Jika permintaan pembuatan tagihan terputus, aplikasi menyimpan nomor transaksi dan meminta donatur menghubungi petugas. Aplikasi tidak mengulang pembuatan tagihan otomatis. Cocokkan merchant_ref di dashboard Tripay sebelum membuat pembayaran lain. Callback yang datang setelah gangguan dapat memulihkan referensi melalui pemeriksaan server.

## Verifikasi dan status
Callback memeriksa HMAC-SHA256 atas body JSON asli, jenis event, closed payment, referensi, kanal, nominal, biaya dan IDR. Setelah itu, aplikasi mengambil detail transaksi melalui API berautentikasi untuk menentukan status. Redirect browser tidak pernah menandai pembayaran berhasil.

Pencatatan memakai row lock dan kunci ledger unik. Callback ganda tidak menambah pembayaran lagi; callback gagal/kedaluwarsa yang terlambat tidak menurunkan transaksi terbayar. REFUND penuh dicatat terpisah dan idempoten. Refund parsial Tripay otomatis tidak tersedia pada implementasi ini; gunakan prosedur koreksi petugas dengan referensi transfer yang nyata.

Mode sandbox harus diuji pada domain/database terpisah agar data uji tidak masuk statistik produksi.

## Pengujian
Suite versi 1.1: **21 tes, 277 assertion lulus**. Tambahan mencakup request bertanda tangan, kanal aktif, biaya, callback ganda, signature/event/referensi/nominal/mata uang salah, penolakan open payment, ketidakcocokan detail API, gagal/kedaluwarsa/refund, mode asal, pemulihan referensi, kerahasiaan kredensial, validasi email serta pembaruan database tanpa kehilangan program.

Respons Tripay dalam pengujian adalah simulasi HTTP. Transaksi langsung sandbox/produksi, callback publik, batas kanal aktual dan settlement membutuhkan kredensial serta uji akun lembaga.

Dokumentasi protokol: [API Developer Guide resmi Tripay](https://tripay.co.id/developer).
