Alur Integrasi

Ikhtisar

Panduan ini memandu Anda melalui integrasi Smilepayz lengkap—dari mendapatkan akun hingga go-live. Alurnya sama untuk setiap wilayah; hanya kredensial dan beberapa endpoint yang berbeda.

Sebelum Memulai

Dapatkan Akun

• Hubungi Pengembangan Bisnis: Hubungi tim kami untuk mendapatkan akun integrasi. Registrasi mandiri tidak tersedia.
• Selesaikan Verifikasi: Selesaikan verifikasi merchant untuk menerima kredensial dan akses dokumentasi API regional.

Temukan Dokumentasi API Regional

Setiap wilayah memiliki mata uang dan metode pembayaran sendiri. Pilih wilayah Anda:

Wilayah	Dokumentasi	Mata Uang	Metode Pembayaran
Brasil	Dok API Brasil	BRL	PIX, Transfer Bank
Chile	Dok API Chile	CLP	CASHIER_CL, Transfer Bank
Kolombia	Dok API Kolombia	COP	CASHIER_CO, Transfer Bank
India	Dok API India	INR	UPI, Transfer Bank
Indonesia	Dok API Indonesia	IDR	QRIS, Virtual Account
Meksiko	Dok API Meksiko	MXN	SPEI, Transfer Bank
Peru	Dok API Peru	PEN	CASHIER_PE, Transfer Bank
Filipina	Dok API Filipina	PHP	GCASH, Transfer Bank
Thailand	Dok API Thailand	THB	QRPAY, Transfer Bank
Vietnam	Dok API Vietnam	VND	E-wallet, VietQR, Transfer Bank
Mesir	Dok API Mesir	EGP	FAWRY, kode bank
USDT	Dok API USDT	USDT	USDT_TRC20, USDT_ERC20, USDT_BEP20

Alur Integrasi

Bangun dan uji di sandbox terlebih dahulu—menggunakan data simulasi, tanpa uang sungguhan. Enam langkah yang sama berlaku untuk produksi; lihat Go Live (Produksi) untuk perbedaannya.

Langkah 1: Dapatkan Kredensial

1. Masuk ke Portal Backend Merchant.
2. Beralih ke tab Sandbox.
3. Salin kredensial Anda:
   • Merchant ID — ID sandbox diawali dengan prefix sandbox.
   • Merchant Secret — digunakan untuk menandatangani permintaan; jangan ubah atau bagikan.
   • Platform Public Key — digunakan untuk memverifikasi callback Smilepayz.

Pemberitahuan

Kredensial sandbox hanya untuk pengujian dan tidak dapat digunakan di produksi.

Langkah 2: Konfigurasi IP Whitelist & Callback URL

• IP Whitelist: Atur sendiri di sandbox. Tambahkan IP server pengembangan—lihat Konfigurasi IP Sandbox.
• Callback URL: Konfigurasi di Backend Merchant, atau kirim callbackUrl per permintaan. Harus menggunakan HTTPS.

Langkah 3: Buat Pasangan Kunci RSA

1. Klik Generate RSA Keys di backend.
2. Simpan public key, lalu refresh halaman untuk memastikan tersimpan.
3. Jaga keamanan private key dan jangan pernah membagikannya.

Penting

Public key yang disimpan harus sesuai dengan private key yang Anda gunakan untuk menandatangani. Kunci yang tidak cocok menyebabkan error tanda tangan.

Langkah 4: Integrasikan API

Base URL (sandbox): https://sandbox-gateway.smilepayz.com · Versi API: v2.0 · HTTPS saja.

Mulai dari salah satu demo SDK kami:

Bahasa	Repositori
Java	Java Demo
C#	C# Demo
PHP	PHP SDK
Python	Python Demo
Node.js	Node.js Demo
Golang	Golang Demo

Ganti merchantId, merchantSecret, dan privateKey demo dengan milik Anda. Simpan rahasia di variabel lingkungan, bukan di kode sumber.

Langkah 5: Buat Pesanan

Respons code 00 berarti pesanan berhasil dibuat. Gunakan orderNo yang dikembalikan untuk melacak. Di sandbox, paymentUrl adalah data mock dan tidak dapat menerima pembayaran nyata.

{
  "code": "00",
  "channel": {
    "paymentUrl": "https://sandbox-gateway.smilepayz.com/cashier/#/loading?tradeNo=T1112001925061115234920979"
  },
  "orderNo": "S200192eeacf6ed4f74406900c8f1039",
  "responseCode": "2009000",
  "message": "Success"
}

Untuk menguji pembaruan status dan penanganan error, picu callback secara manual di sandbox.

Langkah 6: Tangani Callback

1. Ambil platform public key.
2. Verifikasi tanda tangan callback—selalu, sebelum memproses data.
3. Kembalikan SUCCESS untuk mengonfirmasi penerimaan.

Go Live (Produksi) {#going-live-production}

Setelah pengujian end-to-end di sandbox selesai, beralih ke produksi. Alurnya identik—hanya hal-hal berikut yang berbeda:

	Sandbox	Produksi
Kredensial	Dari tab Sandbox	Set terpisah dari tab Production
Base URL	https://sandbox-gateway.smilepayz.com	https://gateway.smilepayz.com
IP Whitelist	Self-service	Diserahkan ke Customer Service
Payment URL	Data mock	Checkout nyata, bervariasi per wilayah
Dana	Simulasi	Uang sungguhan

Untuk go live:

• Dapatkan kredensial produksi dari tab Production di Backend Merchant. Sepenuhnya terpisah dari sandbox—jangan dicampur.
• Serahkan IP whitelist ke Customer Service; Anda tidak dapat mengaturnya sendiri di produksi. Konfigurasi callback URL produksi sama seperti sandbox.
• Buat pasangan kunci RSA produksi dan refresh untuk memastikan public key tersimpan.
• Arahkan integrasi ke https://gateway.smilepayz.com dengan kredensial produksi.
• Tangani respons: channel yang dikembalikan bervariasi per wilayah—lihat Model Saluran Pembayaran. Ambil public key produksi untuk memverifikasi callback live.

Penting

Produksi menangani dana nyata. Jangan pernah menggunakan kredensial sandbox di produksi.

Praktik Terbaik

• Lindungi rahasia: Jangan simpan kredensial di kode sumber; gunakan variabel lingkungan atau secrets manager.
• Verifikasi setiap callback: Selalu validasi tanda tangan sebelum memproses data callback.
• Gunakan HTTPS dan IP whitelisting: Enkripsi semua lalu lintas dan batasi ke IP yang diotorisasi.
• Log dan pantau: Catat permintaan, respons, dan callback untuk troubleshooting dan audit.
• Uji sebelum peluncuran: Jalankan alur lengkap di sandbox sebelum go-live.

Dukungan

• Dokumentasi: Referensi API dan panduan integrasi di situs ini.
• Dukungan Teknis: Hubungi tim kami untuk bantuan integrasi dan troubleshooting.
• Pengembangan Bisnis: Pembukaan akun, onboarding regional, dan syarat komersial.