Panduan Informasi Integrasi

Kumpulkan kredensial API dan konfigurasi integrasi di backend merchant sebelum memanggil API Smilepayz. Sandbox dan produksi menggunakan kredensial dan pengaturan terpisah — selalu kembangkan dan uji di sandbox terlebih dahulu.

Ikhtisar

Anda memerlukan empat jenis informasi:

Item	Lokasi	Digunakan untuk
Merchant ID	Tab Configuration Info	Header X-PARTNER-ID
Merchant Secret	Tab Configuration Info	stringToSign permintaan API
Platform Public Key	Tab Configuration Info	Verifikasi tanda tangan callback
Pasangan kunci RSA merchant	Tab API Setting	Menandatangani permintaan API; unggah public key ke Smilepayz

Prasyarat

• Akun merchant aktif dengan akses backend
• IP publik server yang memanggil API (untuk IP whitelist)
• URL callback HTTPS untuk notifikasi pay-in dan penarikan (disarankan)
• Tempat aman untuk menyimpan Merchant Secret dan private key RSA

Konfigurasi Sandbox

Langkah 1: Buka Configuration sandbox

1. Masuk ke backend merchant.
2. Alihkan toggle atas ke Sandbox.
3. Di sidebar kiri, buka Configuration.

Halaman menampilkan checklist onboarding dan tiga tab di bawahnya.

Langkah 2: Salin API Configuration Keys

Buka tab Configuration Info. Salin dan simpan dengan aman:

• Merchant ID — ID sandbox berprefiks (mis. sandbox-20020)
• Merchant Name
• Merchant Secret — untuk membangun tanda tangan API
• Platform Public Key — untuk memverifikasi callback dari Smilepayz

Gunakan ikon salin di setiap field.

Langkah 3: Konfigurasi API Setting

Buka tab API Setting, lengkapi ketiga bagian, lalu klik Save.

API IP White List

• Masukkan IP publik server yang memanggil API Smilepayz.
• Pisahkan beberapa alamat dengan koma (mis. 192.168.1.1, 192.168.1.2).
• Tekan Enter untuk menambahkan setiap IP sebagai tag.

Panggilan API diblokir tanpa whitelist

Jika IP server tidak masuk whitelist, permintaan API sandbox/produksi mengembalikan error non-whitelist.

API Notify Address

• Payin — URL callback saat pesanan pay-in selesai
• Withdraw — URL callback saat penarikan selesai

HTTPS port 443 disarankan. Lihat Notifikasi Callback untuk penanganan dan retry.

Merchant Public Key

1. Klik Generate RSA Keys — file pasangan kunci diunduh dan public key terisi otomatis.
2. Simpan private key yang diunduh dengan aman di server Anda.
3. Klik Save untuk mendaftarkan public key ke Smilepayz.

Detail: Panduan Generasi Kunci RSA.

Langkah 4: Uji tanda tangan (opsional)

Gunakan tab Signature Test sebelum panggilan API nyata. Model penandatanganan lengkap: Otorisasi Tanda Tangan.

Konfigurasi Produksi

Produksi menggunakan tata letak yang sama dengan penempatan menu dan kredensial berbeda.

Langkah 1: Buka Configuration produksi

1. Masuk ke backend merchant.
2. Pastikan toggle atas Production.
3. Buka Settings → Configuration.

Langkah 2: Salin kredensial produksi

Di Configuration Info, salin:

• Merchant ID (format produksi, tanpa prefiks sandbox-)
• Merchant Name
• Merchant Secret
• Platform Public Key

Lingkungan terpisah

Jangan gunakan ulang secret sandbox, kunci RSA, atau URL callback di produksi.

Langkah 3: Konfigurasi API Setting produksi

Di API Setting, konfigurasi tiga blok yang sama seperti sandbox:

• API IP White List — IP egress server produksi
• API Notify Address — URL callback pay-in dan penarikan produksi (HTTPS)
• Merchant Public Key — generate atau tempel pasangan kunci produksi; klik Save

Simpan setelah perubahan

Selalu klik Save di tab API Setting setelah memperbarui IP whitelist, URL notifikasi, atau public key merchant.

Daftar Periksa Setup

Sandbox

• Beralih ke Sandbox dan buka Configuration
• Salin Merchant ID, Merchant Secret, Platform Public Key
• Tambahkan IP server ke API IP White List
• Atur URL notifikasi Payin dan Withdraw
• Generate kunci RSA, simpan public key, amankan private key
• Jalankan panggilan API uji (lihat Alur Integrasi)

Produksi

• Beralih ke Production dan buka Settings → Configuration
• Salin Merchant ID, Secret, Platform Public Key produksi
• Konfigurasi IP whitelist dan URL callback HTTPS produksi
• Unggah public key merchant produksi dan klik Save
• Verifikasi callback dan checklist go-live di Alur Integrasi

Pemecahan Masalah

Masalah	Tindakan
Error API Merchant non-whitelist	Tambahkan IP egress server ke API IP White List dan Save
Verifikasi tanda tangan gagal	Pastikan Merchant Secret, body minify, dan private key merchant benar
Tanda tangan callback gagal	Gunakan Platform Public Key dari lingkungan yang sama (sandbox vs produksi)
Menu Configuration tidak ditemukan	Di sandbox: Configuration di sidebar kiri; di produksi: Settings → Configuration

Dokumentasi Terkait

• Alur Integrasi
• Otorisasi Tanda Tangan
• Generasi Kunci RSA
• Notifikasi Callback
• Referensi API