--- title: PayPal description: Hubungkan PayPal ke NexCMP untuk pengisian saldo dompet — kredensial aplikasi REST, webhook, pengujian sandbox, dan akun PayPal yang disimpan. url: https://nexcmp.com/id/docs/billing/paypal/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # 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 {#what-it-does} 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](https://nexcmp.com/id/docs/billing/auto-top-up/). Gunakan bersamaan dengan [Stripe](https://nexcmp.com/id/docs/billing/stripe/) bagi pelanggan yang lebih menyukai PayPal. ## Persyaratan {#requirements} | 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 {#prepare-the-infrastructure} 1. Masuk ke [developer.paypal.com](https://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 {#connect-in-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:///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**. ![Halaman PayPal dengan mode sandbox dan kredensial contoh yang dimasukkan](https://nexcmp.com/id/docs/images/billing/paypal-01-keys.webp) ### Webhook events {#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 {#verify} 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 {#limits-notes} - **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](https://nexcmp.com/id/docs/billing/auto-top-up/)), PayPal menyimpan token pembayaran di brankasnya. NexCMP hanya menyimpan pengenal dan email PayPal. Lihat [Saved payment methods](https://nexcmp.com/id/docs/billing/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 {#troubleshooting} | 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. |