PayPal

PayPal adalah salah satu payment gateway internasional tertua dan paling dikenal — mendukung pembayaran dari saldo PayPal user, kartu kredit/debit (tanpa perlu akun PayPal), serta cicilan PayPal Credit/Pay Later. Cocok untuk pembeli internasional yang sudah biasa pakai PayPal di marketplace global.

PayPal dipakai untuk pembayaran internasional (USD, EUR, GBP, dll). PayPal tidak mendukung IDR, jadi mata uang toko Alusio harus diset ke salah satu mata uang yang didukung PayPal.

Prasyarat

• Akun bisnis PayPal — daftar di paypal.com (pilih Business Account, bukan Personal).
• Akun developer di developer.paypal.com (otomatis tersedia setelah login dengan akun PayPal).
• Mata uang toko Alusio sudah diset ke mata uang yang didukung PayPal (USD, EUR, GBP, AUD, SGD, dll).

Langkah 1 — Buat Aplikasi di PayPal Developer

1. Login ke developer.paypal.com.
2. Buka Apps & Credentials. Toggle environment di atas: Sandbox (testing) atau Live (produksi).
3. Klik Create App.
4. Isi nama aplikasi (misal: Alusio Production), pilih Merchant sebagai type, lalu klik Create App.

Langkah 2 — Salin Client ID & Client Secret

1. Di halaman detail aplikasi yang baru dibuat, salin:
   • Client ID — string panjang yang aman dipakai di sisi frontend.
   • Client Secret — klik Show lalu salin. Bersifat rahasia.
2. Pastikan di section Features, opsi Accept payments tercentang (biasanya default aktif).

Catatan: Client ID/Secret Sandbox dan Live berbeda. Pastikan Anda menyalin dari environment yang sesuai dengan mode yang akan dipakai.

Langkah 3 — Atur Webhook

Webhook adalah notifikasi yang dikirim PayPal saat status pembayaran berubah (captured, denied). Tanpa ini, order tidak akan otomatis berubah ke status Paid.

1. Masih di halaman detail aplikasi, scroll ke section Webhooks (atau tab Webhooks).
2. Klik Add Webhook.
3. Isi Webhook URL dengan (ganti alus.io dengan domain instance Alusio Anda):

   https://alus.io/api/webhooks/paypal

4. Pilih events:
   • PAYMENT.CAPTURE.COMPLETED
   • PAYMENT.CAPTURE.DENIED
5. Klik Save.
6. Setelah webhook dibuat, salin Webhook ID yang muncul di daftar webhook. ID ini opsional tapi sangat disarankan untuk verifikasi signature.
7. Ulangi langkah ini di environment Live setelah aplikasi Live dibuat.

Langkah 4 — Pasang Kredensial di Alusio

1. Buka dashboard Alusio, masuk ke Settings → Payments.
2. Pilih tab PayPal.
3. Isi form:
   • Client ID — dari Langkah 2.
   • Client Secret — dari Langkah 2.
   • Webhook ID — dari Langkah 3 (opsional, jika kosong verifikasi signature dilewati).
   • Mode Live — biarkan off untuk Sandbox; aktifkan saat siap menerima pembayaran sungguhan.
4. Klik Simpan Pengaturan PayPal.

Langkah 5 — Uji Transaksi Sandbox

1. Pastikan Mode Live di Alusio masih off dan kredensial yang dipasang adalah Sandbox.
2. Buat akun buyer Sandbox: di developer.paypal.com, buka Sandbox → Accounts dan gunakan salah satu Personal Account default (atau buat baru). Salin email + password buyer.
3. Buka site Anda, tambahkan produk (mata uang USD/EUR/dll) ke cart, lanjut ke checkout, dan pilih PayPal.
4. Anda akan diarahkan ke halaman PayPal Sandbox. Login dengan akun buyer Sandbox dari langkah 2 dan setujui pembayaran.
5. Kembali ke Alusio, buka Orders — status order harus berubah menjadi Paid (via webhook capture).

Langkah 6 — Naik ke Mode Live

1. Di developer.paypal.com, toggle ke Live, lalu ulangi Langkah 1–3 untuk membuat aplikasi Live + webhook Live.
2. Pastikan akun PayPal Business Anda sudah Confirmed dan rekening bank settlement sudah ditambahkan.
3. Di Alusio, ganti Client ID, Client Secret, dan Webhook ID dengan kredensial Live, lalu aktifkan toggle Mode Live.
4. Simpan dan lakukan satu transaksi kecil sebagai verifikasi.

Troubleshooting

Gejala	Penyebab & Solusi
Tab PayPal tidak muncul di checkout	Mata uang toko diset IDR. PayPal hanya bekerja dengan USD, EUR, GBP, AUD, SGD, dll. Ubah di Settings → Currency.
Order tetap Pending setelah customer bayar	Webhook URL salah atau event yang dipilih tidak lengkap. Pastikan PAYMENT.CAPTURE.COMPLETED ada di daftar event di Developer Dashboard.
Error "Invalid client credentials"	Client ID/Secret tidak match dengan environment. Kredensial Sandbox tidak bisa dipakai di Live (dan sebaliknya).
Webhook diterima tapi signature gagal diverifikasi	Webhook ID salah atau dari aplikasi yang berbeda. Pastikan Webhook ID yang dipasang berasal dari webhook yang URL-nya menunjuk ke Alusio. Atau, kosongkan field Webhook ID (Alusio akan skip verifikasi).
Customer dibawa balik ke checkout tapi order kosong	Customer membatalkan di halaman PayPal. Cek log di Activity Dashboard PayPal untuk konfirmasi.

Catatan Keamanan

• Client Secret bersifat rahasia — jangan tampilkan di repo publik atau frontend. Client ID aman dipakai di frontend.
• Jika Client Secret bocor: di developer.paypal.com, buka aplikasi terkait dan klik Generate New Secret, lalu update di Alusio.
• Verifikasi signature webhook PayPal (jika Webhook ID diisi) menggunakan API Verify Webhook Signature milik PayPal — Alusio menolak otomatis request yang gagal verifikasi.