Alur Integrasi

Ikhtisar Integrasi

Panduan integrasi komprehensif ini menyediakan instruksi langkah demi langkah untuk mengintegrasikan dengan platform pembayaran Smilepayz. Proses integrasi dirancang untuk menjadi sederhana dan aman, mendukung berbagai wilayah dan metode pembayaran.

Prasyarat dan Pengaturan Akun

Dokumentasi API Regional

Pilih wilayah target Anda untuk mengakses dokumentasi API khusus:

Wilayah	Link 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

Akuisisi Akun

• Hubungi Staff Smilepayz: Silakan hubungi tim pengembangan bisnis kami untuk mendapatkan akun integrasi Anda
• Verifikasi Akun: Selesaikan proses verifikasi merchant
• Akses Dokumentasi: Terima akses ke dokumentasi API regional dan kredensial

Integrasi Lingkungan Sandbox

Lingkungan sandbox menyediakan lingkungan pengujian yang aman dengan data simulasi untuk pengembangan dan pengujian integrasi.

Langkah 1: Ambil Informasi Integrasi

Akses Backend Merchant

1. Login: Akses Portal Backend Merchant
2. Beralih Lingkungan: Beralih ke tab Sandbox
3. Ambil Kredensial: Dapatkan kredensial sandbox Anda

Kredensial Sandbox

• Merchant ID: Dimulai dengan prefix sandbox di lingkungan sandbox
• Merchant Secret: Digunakan untuk generasi tanda tangan (jangan ubah)
• Platform Public Key: Untuk verifikasi tanda tangan

Catatan Penting

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

Langkah 2: Konfigurasi IP Whitelist dan URL Callback

Konfigurasi IP Whitelist

• Konfigurasi Mandiri: Konfigurasi IP whitelist secara independen di sandbox
• Panduan Referensi: Lihat Konfigurasi IP Sandbox
• IP Pengembangan: Tambahkan alamat IP server pengembangan Anda

Pengaturan URL Callback

• Konfigurasi Backend: Konfigurasi URL callback di Backend Merchant
• Parameter Request: Atau, sertakan callbackUrl dalam parameter request API
• HTTPS Diperlukan: Pastikan URL callback menggunakan protokol HTTPS

Langkah 3: Generasi Pasangan Kunci RSA

Proses Generasi Kunci

1. Generate Kunci: Klik tombol Generate RSA Keys
2. Pembuatan Pasangan Kunci: Sistem menghasilkan private key dan public key RSA
3. Simpan Public Key: Pastikan public key berhasil disimpan
4. Verifikasi: Refresh halaman untuk mengkonfirmasi public key tersimpan

Validasi Pasangan Kunci

• Pencocokan Pasangan: Verifikasi public key yang tersimpan sesuai dengan private key Anda
• Error Tanda Tangan: Pasangan kunci yang tidak cocok akan menyebabkan kegagalan validasi tanda tangan
• Keamanan Kunci: Simpan private key Anda dengan aman dan jangan pernah membagikannya

Peringatan Keamanan

Pastikan public key yang tersimpan sesuai dengan pasangan yang sama dengan private key yang digunakan untuk menandatangani. Kunci yang tidak cocok akan menyebabkan error tanda tangan.

Langkah 4: Implementasi Integrasi API

Konfigurasi Base URL

• Base URL Sandbox: https://sandbox-gateway.smilepayz.com
• Versi API: Gunakan endpoint API v2.0
• HTTPS Saja: Semua komunikasi API menggunakan HTTPS

Integrasi SDK

Kami menyediakan SDK komprehensif dalam berbagai bahasa pemrograman:

Bahasa	Repository	Dokumentasi
Java	Demo Java	Implementasi Java lengkap
C#	Demo C#	Contoh integrasi .NET
PHP	SDK PHP	SDK PHP dan contoh
Python	Demo Python	Panduan integrasi Python
Node.js	Demo Node.js	Contoh JavaScript/Node.js
Golang	Demo Golang	Integrasi bahasa Go

Persyaratan Konfigurasi

• Penggantian Kredensial: Ganti merchant ID, merchant secret, dan private key dengan kredensial aktual Anda
• Variabel Lingkungan: Gunakan variabel lingkungan untuk konfigurasi sensitif
• Penanganan Error: Implementasikan penanganan error komprehensif

Langkah 5: Pembuatan Pesanan dan Penanganan Respons

Pemrosesan Respons Keberhasilan

• Kode Keberhasilan: code = "00" menunjukkan pembuatan pesanan berhasil
• URL Pembayaran: Data mock di sandbox (bukan untuk pembayaran aktual)
• Nomor Pesanan: Identifier pesanan unik untuk pelacakan

Contoh Respons Keberhasilan

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

Pengujian Callback Sandbox

• Callback Manual: Di sandbox, Anda dapat memulai request callback secara manual
• Skenario Pengujian: Uji berbagai skenario pembayaran dan pembaruan status
• Simulasi Error: Uji penanganan error dan kasus edge

Langkah 6: Pemrosesan Request Callback

Verifikasi Tanda Tangan

1. Ambil Public Key: Dapatkan platform public key di sandbox
2. Validasi Tanda Tangan: Verifikasi tanda tangan callback Smilepayz
3. Konfirmasi Respons: Kembalikan SUCCESS ke Smilepayz

Keamanan Callback

• Verifikasi Tanda Tangan: Selalu verifikasi tanda tangan callback
• Validasi Request: Validasi semua parameter callback
• Penanganan Respons: Implementasikan penanganan respons yang tepat

Integrasi Lingkungan Produksi

Lingkungan produksi menangani transaksi nyata dan memerlukan langkah-langkah keamanan tambahan.

Langkah 1: Pengaturan Kredensial Produksi

Perbedaan Lingkungan

• Kredensial Terpisah: Kredensial produksi benar-benar berbeda dari sandbox
• Portal Akses: Login ke Backend Merchant dan beralih ke tab Production
• Tipe Kredensial:
  • Merchant ID: Identifier khusus produksi
  • Merchant Secret: Secret produksi untuk generasi tanda tangan
  • Platform Public Key: Public key produksi untuk verifikasi

Keamanan Produksi

Informasi integrasi produksi benar-benar berbeda dari sandbox. Jangan pernah menggunakan kredensial sandbox di produksi.

Langkah 2: Konfigurasi IP Whitelist dan Callback

Manajemen IP Whitelist

• Persyaratan Keamanan: Merchant tidak dapat mengatur IP whitelist secara independen
• Kontak Dukungan: Hubungi customer service untuk konfigurasi IP whitelist
• Review Keamanan: Semua alamat IP menjalani review keamanan

Konfigurasi URL Callback

• Pengaturan Backend: Konfigurasi URL callback di Backend Merchant
• Parameter Request: Sertakan callbackUrl dalam parameter request API
• HTTPS Wajib: Semua URL callback produksi harus menggunakan HTTPS

Langkah 3: Generasi Kunci RSA Produksi

Proses Generasi Kunci

1. Generate Kunci: Klik tombol Generate RSA Keys
2. Pembuatan Pasangan Kunci: Buat private dan public key RSA produksi
3. Simpan Public Key: Pastikan public key berhasil disimpan
4. Verifikasi: Refresh halaman untuk mengkonfirmasi public key tersimpan

Keamanan Kunci Produksi

• Pencocokan Pasangan Kunci: Verifikasi public key yang tersimpan cocok dengan private key Anda
• Penyimpanan Aman: Implementasikan praktik penyimpanan kunci yang aman
• Rotasi Kunci: Rencanakan rotasi kunci berkala

Langkah 4: Integrasi API Produksi

Base URL Produksi

• Base URL Produksi: https://gateway.smilepayz.com
• Versi API: Gunakan endpoint API v2.0
• Sertifikat SSL: Sertifikat SSL yang valid diperlukan

Implementasi SDK

Gunakan repository SDK yang sama dengan sandbox, tetapi dengan kredensial produksi:

Bahasa	Repository	Catatan Produksi
Java	Demo Java	Implementasi siap produksi
C#	Demo C#	Contoh .NET produksi
PHP	SDK PHP	SDK PHP produksi
Python	Demo Python	Panduan Python produksi
Node.js	Demo Node.js	Contoh Node.js produksi
Golang	Demo Golang	Integrasi Go produksi

Langkah 5: Pemrosesan Pesanan Produksi

Penanganan Respons Produksi

• Transaksi Nyata: Produksi memerlukan pembayaran aktual atau payout yang berhasil
• Kode Keberhasilan: code = "00" menunjukkan pembuatan pesanan berhasil
• URL Pembayaran: URL checkout Smilepayz nyata untuk pembayaran pelanggan
• Variasi Regional: channel yang dikembalikan bervariasi berdasarkan wilayah

Contoh Respons Produksi

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

Informasi Channel Regional

• Variasi Channel: Channel pembayaran berbeda berdasarkan wilayah
• Dokumentasi Referensi: Lihat Model Channel Pembayaran
• Kepatuhan Regional: Pastikan kepatuhan dengan persyaratan regional

Langkah 6: Pemrosesan Callback Produksi

Verifikasi Callback

1. Ambil Public Key: Dapatkan platform public key produksi
2. Validasi Tanda Tangan: Verifikasi tanda tangan callback Smilepayz
3. Konfirmasi Respons: Kembalikan SUCCESS ke Smilepayz

Keamanan Callback Produksi

• Verifikasi Tanda Tangan: Verifikasi tanda tangan wajib untuk semua callback
• Validasi Request: Validasi parameter komprehensif
• Penanganan Error: Penanganan error dan logging yang robust
• Pemantauan: Implementasikan pemantauan dan peringatan callback

Praktik Terbaik Integrasi

Panduan Keamanan

• Manajemen Kredensial: Penyimpanan aman semua kredensial API
• Verifikasi Tanda Tangan: Selalu verifikasi tanda tangan request dan respons
• HTTPS Saja: Gunakan HTTPS untuk semua komunikasi API
• IP Whitelisting: Batasi akses ke alamat IP yang berwenang

Penanganan Error

• Logging Komprehensif: Log semua request dan respons API
• Pemulihan Error: Implementasikan mekanisme retry untuk error sementara
• Pemantauan: Atur pemantauan dan peringatan untuk kesehatan integrasi
• Pengujian: Pengujian menyeluruh di sandbox sebelum deployment produksi

Optimasi Kinerja

• Connection Pooling: Implementasikan connection pooling untuk panggilan API
• Caching: Cache data statis di mana sesuai
• Pemrosesan Async: Gunakan pemrosesan asynchronous untuk callback
• Load Testing: Lakukan load testing sebelum deployment produksi

Dukungan dan Sumber Daya

Dukungan Teknis

• Dukungan 24/7: Dukungan teknis sepanjang waktu tersedia
• Bantuan Integrasi: Bimbingan ahli untuk integrasi kompleks
• Dokumentasi: Dokumentasi API dan panduan komprehensif
• Komunitas: Komunitas developer dan forum

Sumber Daya Pengujian

• Lingkungan Sandbox: Lingkungan pengujian lengkap dengan data simulasi
• Skenario Pengujian: Skenario pengujian komprehensif dan kasus edge
• Data Mock: Data mock yang realistis untuk pengujian
• Tools Validasi: Tools untuk validasi tanda tangan dan pengujian

Kepatuhan dan Keamanan

• Kepatuhan Regional: Kepatuhan terhadap regulasi pembayaran regional
• Standar Keamanan: Praktik keamanan standar industri
• Dukungan Audit: Dukungan untuk audit keamanan dan review kepatuhan
• Sertifikasi: Sertifikasi keamanan dan dokumentasi kepatuhan