Panduan integrasi
Dokumen ini berlaku untuk lingkungan Sandbox Indonesia. Jangan kirim private key, Client Secret, token, atau kredensial Production melalui alat dokumentasi.
Lingkungan
Gunakan origin Sandbox yang diberikan saat onboarding. Origin Production tidak diizinkan pada Try It. Nominal IDR menggunakan satuan terkecil berupa bilangan bulat.
Autentikasi dan tanda tangan Unipay
Unipay menggunakan RSA SHA-256. Bentuk JSON diratakan dengan notasi titik dan indeks array, field diurutkan secara ASCII, nilai kosong serta sign diabaikan, lalu pasangan digabung sebagai key=value&.... Waktu reqTime menggunakan zona Asia/Shanghai sesuai kontrak platform.
Autentikasi dan tanda tangan SNAP
Token SNAP menandatangani clientId|timestamp dengan RSA SHA-256. Permintaan bisnis menandatangani METHOD:PATH:TOKEN:sha256(rawBody):timestamp dengan HMAC SHA-512. Gunakan /api/v1.0/** sebagai path kanonis; /snap/v1.0/** hanya alias kompatibilitas.
Idempotensi
Gunakan reqId, nomor bisnis, dan X-EXTERNAL-ID yang unik. Retry harus menggunakan payload yang sama. Jika respons jaringan tidak diketahui, lakukan query sebelum membuat transaksi baru.
Callback
Verifikasi tanda tangan sebelum memproses event. Callback dapat dikirim berulang dan harus diproses secara idempoten. Status processing atau tidak dikenal tidak boleh dianggap berhasil.
Error
Pisahkan kegagalan validasi, konfigurasi/routing, penolakan upstream, dan hasil jaringan tidak diketahui. Simpan nomor transaksi platform untuk investigasi tanpa mencatat credential atau payload sensitif.
Pembayaran dan query
Gunakan /unipay/pay untuk membuat pembayaran, kemudian /unipay/query/pay-order atau sinkronisasi terkontrol untuk membaca hasil. Instruksi pembayaran dapat berupa VA, identifier, QR, atau tautan aman sesuai capability.
Gunakan permintaan bertanda tangan /unipay/ping untuk memeriksa verifikasi tanda tangan merchant dan pemilihan aplikasi sebelum mengirim pembayaran. Endpoint ini tidak membuat pesanan pembayaran dan mengembalikan string tanda tangan dari server untuk diagnosis; perlakukan respons tersebut sebagai data diagnostik.
Account inquiry dan transfer
Jalankan /unipay/account-inquiry sebelum transfer bila capability mewajibkannya. bizTransferNo mengikat inquiry dan transfer; referensi upstream tidak dikembalikan ke merchant. Transfer hanya dapat memakai route, Profile, otorisasi, dan akun platform yang sehat.
Kontrak SNAP saat ini juga menyediakan transfer antarbank massal, notifikasi hasil per transaksi, serta pembuatan dan pemeriksaan status pencairan OTC pelanggan. Ikuti mode token dan skema permintaan khusus tiap operasi pada referensi API; ketersediaan tetap bergantung pada route dan capability produk yang disetujui untuk merchant.
Rekening SNAP dan virtual account
/api/v1.0/otp meminta OTP dari penyedia untuk perjalanan rekening pelanggan yang diotorisasi. Operasi virtual account update-va dan update-status memperbarui rekening yang sudah ada dan menyinkronkan status pembayarannya. Empat route QR-MPM cancel/query/refund/status dari snapshot sebelumnya tidak ada dalam kontrak publik saat ini; gunakan hanya operasi yang tercantum pada referensi API versi ini.
Saldo dan ledger
/unipay/query/balance membaca saldo merchant. /unipay/query/entries membaca entri ledger yang tidak dapat diubah. Gunakan keduanya untuk pelaporan; jangan menghitung saldo dari daftar order.
Batasan capability
Refund dan allocation yang ditandai Sandbox-only tidak boleh diuji ke Production. Ketersediaan aktual selalu mengikuti capability, fee, route, dan lingkungan aplikasi merchant.