PAYOUT ALTPAY V2 - DOKUMENTASI TERBARU 19 OKTOBER 2026

PERUBAHAN UTAMA
1. Perintah login merchant sekali dengan email/password + kode 2FA opsional.
2. Token diverifikasi dengan GET payout lalu disimpan terenkripsi di server.
   Password dan kode 2FA tidak disimpan. Token tidak dicetak ke terminal/browser.
3. Token tersimpan diprioritaskan di atas ALTPAY_PAYOUT_TOKEN lama dari .env.
4. GET /api/user/withdraw memakai query token, POST memakai body JSON sesuai PDF.
5. Migration menerima tabel altpay_withdrawals yang sebelumnya dibuat lewat SQL.
6. Metode GOPAY/QRIS terpilih sesuai withdrawal; kolom bank aktif hanya untuk bank.
7. Validasi amount - charge = final_amount. Data tidak konsisten diblokir tanpa
   mengubah saldo atau nominal diam-diam.
8. Pratinjau menampilkan saldo tersedia, minimum, biaya, dan nominal bersih tujuan.

CARA REPLACE
Backup file dan DB. Gabungkan seluruh isi folder app, config, database, resources,
routes dan tests dari paket ini ke ROOT proyek Laravel yang berisi artisan.
Ganti file dengan nama sama; jangan hapus folder/file lain di proyek.
Paket berisi file lengkap yang perlu ditambah/diganti, bukan seluruh proyek Laravel.

routes/web.php dan app/Console/Kernel.php berasal dari source ZIP awal Anda, dengan
penambahan payout. Jika ada perubahan lain di hosting setelah upload source awal,
gabungkan perubahan tersebut sebelum replace kedua file itu.
Jangan menimpa .env Anda. .env.payout.example hanya contoh konfigurasi alternatif.

Di terminal hosting, jalankan dari root proyek:
php artisan optimize:clear
php artisan migrate --path=database/migrations/2026_10_19_000001_create_altpay_withdrawals_table.php --force
php artisan config:cache
php artisan view:cache
php artisan route:list --name=withdraw.altpay

Migration menambahkan kolom legacy payout yang belum ada dan tabel audit. Jika
altpay_withdrawals sudah dibuat dengan SQL versi sebelumnya, tabel/data dipakai
kembali, bukan dihapus. Kolom status tabel withdrawals harus mendukung processing.
Jangan memakai migrate:fresh atau menghapus tabel audit.

ALTERNATIF DATABASE TANPA TERMINAL
Di phpMyAdmin, pilih DB yang dipakai Laravel lalu jalankan file:
sql/setup_altpay_payout.sql
Script hanya menambahkan tabel/kolom yang belum ada dan memeriksa selisih nominal.
Tidak mengubah nominal, status withdrawal atau saldo user.

LANGKAH 0 - DAPATKAN TOKEN (PILIH SATU CARA)
A. REKOMENDASI, MELALUI TERMINAL HOSTING
php artisan altpay:payout-login

Isi email dan password akun Dashboard AltPay Anda, BUKAN akun admin Laravel.
Isian password tersembunyi. Bila 2FA aktif, isi kode enam digit yang sedang berlaku;
kalau tidak aktif, tekan Enter. Password tidak dikirim lewat argumen shell/history.
Command melakukan:
- POST HTTPS /api/user/login dengan email/password/code opsional.
- Mengambil data.token, bukan data.user.apiKey.
- Membandingkan apiKey merchant login dengan key pay-in jika tersedia pada respons.
- GET HTTPS /api/user/withdraw untuk memastikan token diterima.
- Menyimpan token terenkripsi dengan APP_KEY di:
  storage/app/private/altpay/payout-token.enc (izin file 0600).

Jalankan command dengan user hosting yang sama dengan proses PHP aplikasi agar
file dapat dibaca. Direktori privat ini tidak boleh ditempatkan di public web root.
APP_KEY harus dipertahankan agar token tersimpan tetap dapat dibaca.
Command tidak menyimpan email/password/code dan tidak membuat pengajuan payout.

Menurut dokumentasi terbaru, token stateless tanpa expiry; cukup login sekali.
Jika token ditolak/dicabut, jalankan command login kembali. Tidak ada auto-login
atau retry transfer dengan password tersimpan.

B. TANPA LOGIN COMMAND
Login Dashboard AltPay di browser -> F12 -> Application -> Local Storage -> domain
Dashboard -> salin nilai pg_token. Atau gunakan POST HTTPS /api/user/login sendiri.
Tambahkan token tersebut ke .env:
ALTPAY_PAYOUT_TOKEN="TOKEN_DATA_TOKEN_ATAU_PG_TOKEN"
Jangan tambahkan Bearer, jangan memakai key oto_pg_/alt_pg_, dan jangan decode token.
Setelah mengubah .env, jalankan config:clear lalu config:cache bila terminal tersedia.

PENTING: jika token terenkripsi dari cara A sudah ada, cara A selalu diprioritaskan.
Mengedit .env saja tidak mengganti token tersimpan; jalankan login command lagi.
Token tidak boleh dibagikan dalam chat, screenshot, kode frontend, atau repository.

PENGGUNAAN
Admin -> Pending / Processing Withdraw.
- Metode awal mengikuti GOPAY/QRIS di data withdrawal, selain itu Bank.
- Cocokkan nama/kode bank dengan format yang diterima provider, bukan nama label
  metode internal yang belum tentu sama.
- Verifikasi nama rekening. Nama profil hanyalah nilai awal, bukan hasil inquiry.
- Nomor tujuan memakai snapshot withdrawal, bukan input bebas dari browser.
- Klik Pratinjau payout AltPay, periksa biaya tambahan dan nominal diterima tujuan.
- Centang persetujuan lalu kirim satu kali.
- Status lokal processing; Cek Status membaca hasil GET terautentikasi.
- PENDING/PROCESSING tetap processing. COMPLETED menjadi approved.
- REJECTED mengembalikan amount bruto user tepat satu kali dan menjadi rejected.

BIAYA DAN SALDO
final_amount adalah nominal yang diajukan ke AltPay, bukan janji nominal bersih
setelah biaya AltPay. Provider memotong withdraw_fee_percent dari amount pengajuan.
Contoh: amount bruto 25.000, charge aplikasi 7.500 -> final_amount 17.500.
Jika biaya AltPay 2% (CONTOH), tujuan menerima 17.150, asalkan nominal memenuhi
minimum serta saldo tersedia. Kode mengambil minimum dan persentase dari GET,
tidak hardcode 2% atau 50.000.
Jika bisnis menjanjikan penerima mendapat final_amount utuh, kebijakan biaya perlu
disepakati sebelum penggunaan; paket ini tidak menerapkan gross-up otomatis.
Fee pecahan Rupiah diblokir karena PDF tidak menjelaskan aturan pembulatannya.

Dana pay-in masuk antrean settlement H+1. Menurut PDF, dana menjadi tersedia esok
pukul 00.00 waktu sistem provider; jangan memakai balance_pending untuk payout.
PDF tidak menyebut zona waktu server, jadi kode memakai saldo yang dikembalikan API.

REKONSILIASI
php artisan altpay:payouts-reconcile --limit=25
Kernel menjalankan pengecekan setiap dua menit. Scheduler hosting harus aktif:
* * * * * cd /path/proyek && php artisan schedule:run >> /dev/null 2>&1
Ganti path/PHP sesuai hosting. Jangan tambahkan cron duplikat jika sudah aktif.
Tanpa scheduler, Cek Status manual tetap tersedia.

TIMEOUT / UNCERTAIN
PDF belum mendokumentasikan external_id/idempotency key untuk POST payout.
Sebelum HTTP dikirim, claim tersimpan dan withdrawal dikunci processing.
Paket tidak melakukan auto-retry POST setelah error/timeout. Jangan kirim ulang,
transfer manual, reset status, atau refund sebelum hasil transfer dipastikan.

Jika ID respons hilang, cocokkan Dashboard AltPay: waktu, metode, bank, rekening,
nama, amount, fee dan net_amount. Setelah minimal dua menit, masukkan ID pengajuan
yang tepat pada daftar lalu centang pernyataan rekonsiliasi. Kode memverifikasi
ulang melalui GET dan mengunci gateway_id unik. Jangan mengaitkan transfer lain
yang kebetulan memiliki rekening/nominal identik. PDF tidak memberi korelasi
external_id; konfirmasi identitas pengajuan tetap menjadi tanggung jawab operator.
Jika support memastikan tidak ada pengajuan, pemulihan memerlukan audit developer;
paket tidak menyediakan tombol reset yang berisiko menggandakan transfer.

BATASAN DAN VALIDASI
- Seluruh request baru dilindungi middleware admin, POST/CSRF untuk aksi web.
- Token hanya dipakai backend. GET mengirim query token secara server-to-server;
  hindari pencatatan URL lengkap di proxy, debugger HTTP atau monitoring.
- Respons/error login tidak ditampilkan mentah; diagnostik tidak mencetak password,
  token, body provider atau rekening.
- Callback pay-in dan gateway lama tetap memakai source awal. PDF menyebut callback
  internal provider, tidak mendokumentasikan webhook payout merchant tersendiri.
  Karena itu paket memakai GET riwayat, bukan webhook payout baru yang ditebak.
- ID yang tidak muncul dalam riwayat atau normalisasi nama/kode bank berbeda
  ditahan untuk rekonsiliasi; kode tidak menebak kecocokan penerima.
- Tidak mengubah otomatis withdrawal lama yang nominalnya tidak konsisten.
- Periksa HASIL_VALIDASI.txt untuk tes yang benar-benar dijalankan.

UJI YANG BISA ANDA JALANKAN
Client standalone (tanpa Laravel/vendor, tanpa jaringan):
php tests/Standalone/AltpayPayoutClientTest.php

Suite integrasi Laravel lengkap (HTTP fake + SQLite in-memory terisolasi):
php artisan test --filter=AltpayPayoutSafetyTest
Source upload tidak menyertakan artisan/composer/vendor/schema DB asli sehingga
suite integrasi dan transaksi live belum dijalankan di lingkungan pembuatan paket.
