PayPal

Lokasi di admin: Finance › Payment channels › PayPal (/payments/paypal). Tombol aktif/nonaktif dan biaya terdapat di Finance › Payment channels › Fees & limits (/payments/fees).

Fungsi

Memungkinkan pelanggan mengisi saldo USD mereka menggunakan saldo PayPal, rekening bank, atau kartu yang disimpan di PayPal. Pelanggan juga dapat mengizinkan NexCMP mengingat akun PayPal mereka untuk automatic top-up. Gunakan bersamaan dengan Stripe bagi pelanggan yang lebih menyukai PayPal.

Persyaratan

Item	Persyaratan
Akun PayPal	Akun Business PayPal yang dapat menerima USD.
Aplikasi REST	Satu aplikasi REST di PayPal Developer Dashboard (Apps & Credentials) yang menyediakan Client ID dan Client secret. Gunakan tab Sandbox untuk pengujian, Live untuk produksi.
Jaringan	HTTPS dapat dijangkau dari Internet (PayPal memanggil webhook) dan akses keluar ke api-m.paypal.com (live) atau api-m.sandbox.paypal.com (sandbox), port 443.
Izin	Aplikasi REST memerlukan kemampuan refund dan webhooks. Dialog Check menunjukkan apakah kedua cakupan tersebut ada.
Dependensi	Tidak ada.

Siapkan infrastruktur

1. Masuk ke developer.paypal.com dengan akun Business Anda dan buka Apps & Credentials.
2. Pilih Sandbox (pengujian) atau Live, lalu Create App. Beri nama misalnya "NexCMP".
3. Salin Client ID dan Secret dari aplikasi tersebut.
4. Untuk pengujian, gunakan Testing Tools › Sandbox Accounts untuk menemukan atau membuat akun sandbox Personal (pembeli).
5. Anda tidak perlu membuat webhook sendiri; NexCMP membuatnya dengan tombol Create webhook.

Hubungkan di NexCMP

1. Buka Finance › Payment channels › PayPal (/payments/paypal).
2. Di API keys, pilih Mode: live (uang riil, api-m.paypal.com) atau sandbox (api-m.sandbox.paypal.com).
3. Tempel Client ID (setidaknya 20 karakter) dan Client secret.
4. Klik Check. Ini menguji kredensial yang Anda ketik (penyimpanan tidak diperlukan) dan melaporkan koneksi, App ID, mode, apakah cakupan pengembalian dana dan webhook tersedia, serta berapa lama masa aktif token.
5. Klik Save.
6. Pada kartu Webhook, konfirmasikan bahwa URL-nya adalah https://<your-domain>/v1/billing/paypal/webhook (harus berupa https), lalu klik Create webhook dan konfirmasikan. NexCMP meminta PayPal untuk membuat atau memperbarui webhook dengan 11 peristiwa dan menyimpan Webhook ID yang dikembalikan. Tombol ini menggunakan kunci yang disimpan — simpan terlebih dahulu jika Anda baru saja mengubahnya.
7. Klik Check lagi: baris Webhook seharusnya bertuliskan "exists, 11 events".
8. Buka Fees & limits, aktifkan PayPal, atur PayPal fee % (default 4.4) dan PayPal fixed fee (cents) (default 30) sesuai tarif Anda, lalu klik Save channels & fees.

Webhook events

NexCMP mendaftarkan 11 peristiwa berikut: CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.PENDING, PAYMENT.CAPTURE.DECLINED, PAYMENT.CAPTURE.REFUNDED, PAYMENT.CAPTURE.REVERSED, CUSTOMER.DISPUTE.CREATED, CUSTOMER.DISPUTE.UPDATED, CUSTOMER.DISPUTE.RESOLVED, RISK.DISPUTE.CREATED, CHECKOUT.PAYMENT-APPROVAL.REVERSED.

Setiap webhook diverifikasi dengan memanggil API verifikasi tanda tangan PayPal, disimpan sekali, dan diproses secara idempoten. NexCMP tidak pernah mempercayai jumlah dalam badan webhook: sebelum mengkreditkan tangkapan, ia mengambil data tangkapan dari PayPal.

Verifikasi

1. Biarkan Mode pada sandbox. Di portal, buka Billing › Deposit, pilih PayPal, klik Continue on PayPal (atau tombol PayPal) dan masuk dengan akun pembeli sandbox.
2. Setujui pembayaran tersebut. Anda akan kembali ke portal, saldo akan bertambah, dan pembayaran akan muncul di bawah Finance › Billing › Top-ups sebagai Completed.
3. Buka Payment channels › Gateway events › PayPal & USDT: PAYMENT.CAPTURE.COMPLETED tercantum di sana.
4. Jika semuanya berjalan lancar, ubah Mode ke live, masukkan kredensial live, Save, lalu Create webhook kembali (webhook sandbox dan live terpisah).

Batas & catatan

• Bagaimana pembayaran diselesaikan. Pesanan dibuat dalam USD; setelah pelanggan menyetujuinya, server akan mengambilnya (ID permintaan idempoten) dan mengkreditkan dompet tepat satu kali. Webhook dan pekerjaan rekonsiliasi yang berjalan setiap 10 menit bertindak sebagai jaring pengaman jika pelanggan menutup peramban.
• Pesanan tertunda dan terbengkalai. Pesanan dapat tetap terbuka selama 12 jam. Seorang pelanggan dapat memiliki paling banyak 5 pesanan tertunda (server merespons too_many_pending, HTTP 429). Pesanan yang masih belum diambil setelah 24 jam ditandai gagal.
• Tidak ada webhook yang dikonfigurasi. Panel merespons HTTP 503 untuk setiap webhook PayPal hingga ID Webhook disimpan. Pengambilan yang dilakukan melalui portal dan rekonsiliasi 10 menit tetap mengkreditkan dompet, tetapi tidak ada yang dilaporkan oleh webhook PayPal (sengketa, pembatalan, pengambilan terlambat) yang akan diterapkan — klik Create webhook.
• Akun PayPal tersimpan. Ketika pelanggan memilih untuk menyimpan PayPal (atau menyelesaikan deposit pertama, yang mengaktifkan automatic top-up), PayPal menyimpan token pembayaran di brankasnya. NexCMP hanya menyimpan pengenal dan email PayPal. Lihat Saved payment methods.
• Pengembalian dana dan sengketa ditangani seperti Stripe: permintaan pengembalian dana disetujui di bawah Finance › Payouts › Card refunds; sengketa akan memblokir akun pelanggan dan menghentikan layanan prabayar mereka hingga Anda menyelesaikannya.
• Biaya. Biaya PayPal tidak dibaca kembali; persentase dan biaya tetap yang Anda konfigurasikan menentukan apa yang dilihat pelanggan dan apa yang dikreditkan. Tarif sebenarnya bergantung pada negara Anda (formulir menyarankan 4.4 % untuk Vietnam dan 3.49 % untuk AS).

Pemecahan Masalah

Gejala	Penyebab	Solusi
"Client ID terlalu pendek"	Kurang dari 20 karakter ditempelkan	Salin Client ID lengkap tersebut.
"URL webhook harus https"	URL diketik dengan http://	Gunakan domain publik https:// Anda.
Pemeriksaan melaporkan galat koneksi	Mode salah (kunci live di sandbox atau sebaliknya), secret salah, tidak ada akses keluar	Sesuaikan Mode dengan jenis kunci; uji curl -I https://api-m.paypal.com dari server.
Cakupan pengembalian dana / webhook menampilkan "no"	Aplikasi REST tidak memiliki fitur tersebut	Aktifkan fitur pada aplikasi di PayPal Developer Dashboard.
Banner "Kunci PayPal disetel, TANPA webhook"	Webhook ID hilang	Klik Create webhook.
"Webhook not found" dalam Pemeriksaan	Webhook telah dihapus di PayPal atau milik aplikasi lain	Klik Create webhook lagi.
Pelanggan diberitahu bahwa PayPal menolak pembayaran	PayPal menolak sumber pendanaan tersebut	Minta pelanggan untuk memilih sumber pembayaran lain.
Pelanggan melihat "Too many pending requests"	5 pesanan aktif	Tunggu hingga kedaluwarsa atau selesaikan pesanan tersebut.
Tombol PayPal tidak ada	PayPal nonaktif di Fees & limits atau belum dikonfigurasi	Aktifkan dan simpan kredensial.