Stripe

Di admin: Finance › Payment channels › Stripe (/payments/stripe). Sakelar dan biaya: Finance › Payment channels › Fees & limits (/payments/fees).

Fungsi

Stripe menerima pembayaran kartu untuk top-up wallet. Dengan akun yang sama, Anda juga dapat menawarkan Apple Pay, Google Pay, Link, dan Alipay, serta memungkinkan pelanggan menyimpan kartu untuk top-up otomatis. Gunakan ini sebagai saluran utama untuk pelanggan internasional.

Persyaratan

Item	Persyaratan
Akun Stripe	Akun Stripe yang dapat menerima pembayaran dalam USD. Alipay ditagihkan dalam JPY dan harus diaktifkan oleh Stripe untuk akun Anda.
Kunci	Secret key (sk_live_... atau sk_test_...) dan publishable key (pk_live_... atau pk_test_...). Formulir hanya menerima kunci dengan prefiks tersebut.
Jaringan	Panel Anda harus dapat dijangkau melalui HTTPS dari internet (Stripe memanggil webhook) dan harus dapat menjangkau api.stripe.com pada port 443.
Domain (hanya wallet)	Domain sisi pelanggan harus menyajikan /.well-known/apple-developer-merchantid-domain-association — NexCMP menanganinya untuk Anda.
Dependensi	Tidak ada.

Akun Stripe bersama

NexCMP hanya memproses event webhook untuk pembayaran yang dibuatnya sendiri, sehingga Anda dapat menggunakan akun Stripe yang juga melayani aplikasi lain.

Siapkan infrastruktur

Di sisi Stripe:

1. Masuk ke Stripe Dashboard. Aktifkan atau nonaktifkan Test mode untuk menentukan apakah Anda sedang melakukan uji coba atau beralih ke live. Kunci dari satu mode tidak akan pernah berfungsi pada mode lainnya.
2. Buka Developers › API keys. Salin Publishable key serta tampilkan dan salin Secret key. Jaga kerahasiaan secret key tersebut.
3. (Opsional) Buka Settings › Payment methods dan aktifkan Alipay jika Anda ingin menawarkannya.
4. Anda tidak harus membuat webhook secara manual — NexCMP dapat membuatnya untuk Anda (lihat langkah 5 di bawah). Jika Anda lebih memilih untuk membuatnya secara manual, buat endpoint di Developers › Webhooks dengan URL dan event yang tercantum di Webhook.

Hubungkan di NexCMP

1. Buka Finance › Payment channels › Stripe (/payments/stripe).
2. Pada kartu API keys, pilih Mode (live atau test), tempel Secret key dan Publishable key.
3. Klik Save. Kunci tersebut ditulis ke file konfigurasi di server yang hanya dapat dibaca oleh akun layanan NexCMP. Kunci tidak pernah dikirim kembali ke browser; setelahnya halaman hanya menampilkan 4 karakter terakhir.
4. Klik Check. Dialog akan melaporkan koneksi, mode, saldo yang tersedia dan tertunda, ID akun, apakah pembebanan diaktifkan, apakah webhook ada, dan apakah Alipay tersedia. Garis merah menandakan bagian tersebut memerlukan perhatian.
5. Pada kartu Webhook, klik Create webhook dan konfirmasi. NexCMP meminta Stripe untuk membuat endpoint dengan setiap event yang diperlukan dan mengisi Webhook signing secret (whsec_...) secara otomatis. URL yang telah terisi sebelumnya di dalam field adalah https://<your-domain>/v1/billing/stripe/webhook, misalnya https://cloud.example.com/v1/billing/stripe/webhook.
6. Buka Fees & limits (/payments/fees), biarkan Card (Stripe) tetap aktif, atur Stripe fee % dan Stripe fixed fee (cents) sesuai tarif asli Anda, lalu klik Save channels & fees. Lihat Payment channels.

Webhook

Banner merah "Missing webhook_secret" akan tetap muncul sampai signing secret disimpan. Tanpa itu, isi ulang Stripe tidak dicatat, meskipun Stripe telah mengambil uangnya.

Item	Nilai
URL	https://<your-domain>/v1/billing/stripe/webhook
Event	checkout.session.completed, payment_intent.succeeded, payment_intent.payment_failed, charge.refunded, charge.dispute.created, charge.dispute.closed, radar.early_fraud_warning.created, refund.updated, refund.failed
Tanda Tangan	Header Stripe Stripe-Signature, HMAC-SHA256, toleransi 300 detik. Permintaan dengan tanda tangan yang buruk akan mendapatkan HTTP 400.
Idempotensi	Setiap ID event disimpan sekali; pengiriman berulang tidak akan pernah mengkreditkan saldo dua kali.

Jika Anda meningkatkan dari rilis yang mendaftarkan lebih sedikit event, klik Create webhook lagi — endpoint lama akan tetap disimpan, jadi hapus secara manual di Stripe Dashboard setelahnya.

Baris 24h events dan Latest event pada kartu Webhook memberi tahu Anda apakah Stripe menjangkau panel. Event individual dicantumkan di Payment channels › Gateway events (/payments/events, tab Stripe), di mana setiap event dapat dilihat (Payload) atau diputar ulang (Replay).

Apple Pay, Google Pay, dan Link

1. Pada kartu Wallets (Apple Pay · Google Pay · Link) & Alipay, field Customer app Domain registered with Stripe telah terisi otomatis dengan nama host situs Anda (misalnya cloud.example.com).
2. Klik Register / verify domain dan konfirmasi. NexCMP mendaftarkan domain di domain metode pembayaran Stripe dan meminta Stripe untuk memvalidasinya.
3. Hasilnya menampilkan status dari Apple Pay, Google Pay, dan Link. Apple Pay hanya ditampilkan ketika statusnya adalah active.
4. Di Fees & limits, biarkan Apple Pay · Google Pay · Link tetap aktif.

Apple Pay tetap tidak aktif

Apple Pay memerlukan file asosiasi domain untuk merespons HTTP 200 pada domain publik Anda. Jika Anda menggunakan Cloudflare atau proksi lain di depan, jangan blokir /.well-known/.

Alipay

Alipay bersifat opsional. Aktifkan di Stripe Dashboard › Settings › Payment methods, klik Check dan tunggu hingga dialog menunjukkan bahwa Alipay tersedia, lalu aktifkan Alipay (Stripe, JPY display) di Fees & limits. Atur Alipay fee %, Alipay fixed fee, ¥/USD rate (50–500), dan FX spread % (0–20). Perbarui nilai tukar ¥/USD secara berkala; halaman akan memperingatkan saat usianya lebih dari 7 hari.

Verifikasi

1. Dalam mode pengujian, masuk ke portal sebagai pelanggan uji, buka Billing, klik Deposit, pilih Card, dan bayar minimum menggunakan kartu uji Stripe 4242 4242 4242 4242 (tanggal masa depan apa pun, CVC apa pun).
2. Saldo bertambah dalam hitungan detik dan pembayaran muncul di bawah Finance › Billing › Top-ups dengan status Completed.
3. Buka Payment channels › Gateway events › Stripe: Anda seharusnya melihat checkout.session.completed atau payment_intent.succeeded beserta waktu pemrosesan.
4. Kembali ke halaman Stripe, 24h events bernilai di atas 0.

Sebelum beralih ke mode produksi, ubah Mode ke live, tempelkan kunci produksi, dan klik Create webhook lagi (webhook untuk mode uji dan mode produksi terpisah).

Batas & catatan

• Jumlah dan mata uang. Dompet menggunakan USD. Pembayaran kartu, dompet, dan tautan ditagihkan dalam USD; Alipay ditampilkan kepada pelanggan dalam JPY dan dikonversi sesuai kurs Anda.
• Biaya. Biaya asli Stripe tidak terbaca kembali secara otomatis; persentase biaya yang Anda tetapkan menentukan apa yang dilihat pelanggan dan berapa yang dikreditkan ke dompet. Pilih Customer pays top-up fee di Fees & limits untuk membebankan biaya di luar jumlah pengisian.
• Kartu tersimpan. Saat pelanggan mencentang Save card for auto top-up, kartu disimpan di Stripe, bukan di server Anda. Lihat Saved payment methods.
• Pengembalian dana. Mengembalikan dana ke kartu adalah proses dua langkah: admin membuat permintaan pengembalian dana untuk pembayaran yang telah selesai (Finance › Billing › Top-ups, tindakan pengembalian dana pada pembayaran) lalu menyetujuinya di bawah Finance › Payouts › Card refunds (/billing/payouts). Pengembalian dana Alipay bersifat asinkron; yang gagal (refund.failed) akan mengembalikan jumlah yang ditahan ke dompet.
• Sengketa. Pada charge.dispute.created NexCMP memblokir akun pelanggan, menghentikan layanan prabayar mereka (tidak ada yang dihapus) dan mengirimkan peringatan admin. Jika Anda menang (charge.dispute.closed), jumlah tersebut dikreditkan kembali ke dompet.
• Pembayaran tertunda. Jika webhook tidak pernah tiba, NexCMP memeriksa sendiri pembayaran yang tetap tertunda selama lebih dari 10 menit terhadap Stripe dan menyelesaikannya. Pembayaran yang lebih lama dari 7 hari akan diabaikan.
• Resellers dapat menghubungkan akun Stripe mereka sendiri (webhook https://<their-domain>/v1/billing/stripe/webhook/r/<id>); lihat Resellers.

Pemecahan Masalah

Gejala	Penyebab	Solusi
"Secret key harus diawali dengan sk_live_/sk_test_"	Kunci yang ditempel salah	Tempel kunci rahasia dari Developers › API keys.
"Secret key tidak cocok dengan mode live/test"	Mode dan kunci tidak cocok	Buat Mode agar cocok dengan awalan kunci tersebut.
"Publishable key harus diawali dengan pk_"	Kunci salah	Gunakan publishable key.
Pemeriksaan menyatakan koneksi gagal	Kunci salah, kunci dicabut, atau server tidak dapat menjangkau api.stripe.com	Tempel ulang kunci; uji dengan curl -I https://api.stripe.com dari server.
Banner merah "Missing webhook_secret"	Signing secret belum disimpan	Klik Create webhook atau tempel whsec_... secret dari Stripe Dashboard dan Save.
Uang terpotong tetapi saldo tidak berubah	Webhook tidak dikirim atau tanda tangan gagal	Periksa apakah URL berakhiran /v1/billing/stripe/webhook, secret cocok dengan endpoint, dan putar ulang event di Gateway events. Di Stripe, buka endpoint dan lihat percobaan pengiriman (HTTP 400 berarti signing secret salah).
"Create webhook" gagal	URL bukan HTTPS atau tidak dapat dijangkau	Gunakan domain publik https:// Anda.
Status Apple Pay tidak aktif	Domain belum divalidasi	Klik Register / verify domain lagi setelah file asosiasi domain merespons 200.
Alipay tidak tersedia di dialog Check	Belum diaktifkan di Stripe	Aktifkan di Stripe Dashboard, lalu klik Check.
Pelanggan tidak melihat formulir kartu	Card (Stripe) nonaktif atau tidak ada secret key	Nyalakan di Fees & limits dan simpan kunci.