Troubleshooting integrasi: 10 kesalahan umum dan cara memperbaikinya

Kebanyakan masalah integrasi bukan bug. Biasanya itu kesalahan pengaturan kecil yang mudah diperbaiki asal tahu di mana melihatnya. Mulailah dari API logs di dashboard: setiap request dari server Anda tercatat di sana, beserta jawaban PAYWISE dan error.code-nya.

1. Key tidak ada atau terpotong

Error: INVALID_API_KEY. Kirim header persis seperti Authorization: Bearer <key>, dengan key yang tersalin utuh. Hati-hati dengan spasi atau baris baru yang ikut tersalin.

2. Sandbox key di live, atau live key di sandbox

Key pw_test_… hanya melihat pembayaran sandbox, dan pw_live_… hanya melihat pembayaran live. Jika Anda mencari pembayaran dengan key yang salah, hasilnya NOT_FOUND. Simpan key di pengaturan environment dan cek key mana yang dipakai server Anda.

3. IP server Anda tidak diizinkan

Error: IP_NOT_ALLOWED. Key memiliki daftar IP yang diizinkan dan request datang dari alamat lain. Pesan error menunjukkan IP yang dilihat PAYWISE: tambahkan IP itu di halaman API Keys. Server di balik load balancer atau hosting baru sering berganti IP keluar.

4. Return URL bukan salah satu website Anda

Error: RETURN_URL_NOT_ALLOWED. return_url wajib memakai https:// dan domainnya harus salah satu website aktif Anda (atau subdomainnya). Tambahkan domainnya di Website & Webhook.

5. Memakai ulang ID pesanan dengan nominal baru

Error: DUPLICATE_REFERENCE. Pengiriman ulang dengan data yang sama aman dan mengembalikan pembayaran yang lama. Nominal baru butuh merchant_reference baru. Baca cara kerja idempotency.

6. URL webhook tidak bisa dijangkau

Webhook harus dikirim ke alamat https:// publik. localhost dan alamat IP privat akan ditolak. Gunakan Kirim webhook uji lalu cek responsnya di Riwayat pengiriman. Jika firewall Anda hanya menerima alamat tertentu, izinkan IP pengirim yang tertera di halaman webhook.

7. Signature tidak pernah cocok

Hitung HMAC-SHA256 dari body request mentah, persis seperti yang diterima, dengan webhook secret Anda. Mem-parse JSON lalu meng-encode-nya lagi akan mengubah isinya dan merusak signature. Pastikan juga Anda memakai secret yang terbaru: setelah "Buat secret baru", secret lama langsung tidak berlaku. Coba nilainya di alat signature pada dokumentasi, dan baca verifikasi signature webhook.

8. Server Anda lambat atau membalas error

Balas webhook dengan HTTP 2xx secepatnya, lalu kerjakan proses yang lambat (email, update stok) setelahnya. Selain 2xx akan dikirim ulang, sehingga bisa terlihat seperti event ganda. Proses setiap event satu kali saja, berdasarkan referensi pembayarannya.

9. Percaya halaman kembali, bukan webhook

Pelanggan yang kembali ke website Anda belum tentu sudah membayar. Tandai pesanan lunas hanya berdasarkan webhook payment.paid yang valid, atau setelah mengecek pembayaran lewat API.

10. Terlalu banyak request

Error: RATE_LIMITED (lebih dari 60 request per menit dengan satu key). Jangan cek status pembayaran terus-menerus tanpa jeda: tunggu webhook, dan kirim ulang dengan jeda yang makin lama.

Masih buntu?

Buat tiket di menu Bantuan dengan waktu request, error.code, dan website Anda, atau hubungi kami di Telegram @paywise_asia. Lihat cara mendapat bantuan cepat.