---
title: Stripe
description: Hubungkan Stripe ke NexCMP untuk pembayaran kartu, Apple Pay, Google Pay, Link, dan Alipay — kunci API, webhook, pendaftaran domain, dan pembayaran uji.
url: https://nexcmp.com/id/docs/billing/stripe/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Stripe

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

## Fungsi {#what-it-does}

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](https://nexcmp.com/id/docs/billing/auto-top-up/). Gunakan ini sebagai saluran utama untuk pelanggan internasional.

## Persyaratan {#requirements}

| 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. |

::: info 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 {#prepare-the-infrastructure}

Di sisi Stripe:

1. Masuk ke [Stripe Dashboard](https://dashboard.stripe.com). 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](#webhook).

## Hubungkan di NexCMP {#connect-in-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](https://nexcmp.com/id/docs/billing/payment-channels/#switches-and-fees-fees-limits).

![Halaman Stripe dengan mode, kunci rahasia, dan kunci publik yang diisi dengan nilai contoh](https://nexcmp.com/id/docs/images/billing/stripe-01-keys.webp)


### Webhook {#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 {#apple-pay-google-pay-and-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.

![Kartu Wallet yang menampilkan domain terdaftar serta status Apple Pay, Google Pay, dan Link](https://nexcmp.com/id/docs/images/billing/stripe-03-wallets.webp)

::: tip 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}

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 {#verify}

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 {#limits-notes}

- **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](https://nexcmp.com/id/docs/billing/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](https://nexcmp.com/id/docs/customers/resellers/).

## Pemecahan Masalah {#troubleshooting}

| 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. |