Notifikasi Callback

Smilepayz mengirim notifikasi HTTP POST ke server Anda ketika pesanan pay-in atau penarikan mencapai status akhir. Panduan ini mencakup pengaturan URL callback, pengujian sandbox, verifikasi tanda tangan, dan cara merespons.

Ikhtisar

Callback memungkinkan sistem Anda:

• Menerima pembaruan status pay-in dan penarikan secara asinkron
• Mengonfirmasi hasil pesanan tanpa polling API inquiry
• Memperbarui status pesanan internal setelah tanda tangan diverifikasi

Hanya pesanan API

Callback hanya dikirim untuk pesanan yang dibuat melalui API Pay-in / Pay-out. Pesanan dari Payment Link di backend merchant tidak dapat dihubungkan ke integrasi Anda.

Prasyarat

Sebelum menangani callback, pastikan Anda memiliki:

• URL callback yang dapat diakses publik (http:// atau https://; HTTPS port 443 disarankan)
• Platform Public Key dari sandbox atau produksi di Informasi Integrasi
• Logika server untuk memverifikasi tanda tangan dan mengembalikan SUCCESS

Konfigurasi URL Callback

Sandbox

1. Masuk ke backend merchant.
2. Alihkan toggle atas ke Sandbox.
3. Buka Configuration → API Setting.
4. Di API Notify Address, atur:
   • Payin — URL notifikasi penyelesaian pay-in
   • Withdraw — URL notifikasi penyelesaian penarikan
5. Klik Save.

Retry dan idempotensi

Backend dapat mengulang callback yang gagal. Endpoint Anda harus memverifikasi tanda tangan pada setiap permintaan dan menangani duplikat secara idempoten ( tradeNo / orderNo yang sama tidak boleh diproses dua kali).

Untuk URL produksi dan pengaturan IP whitelist, lihat Informasi Integrasi.

Pengujian Sandbox

Di sandbox Anda dapat memicu callback uji dari daftar pesanan setelah membuat pesanan API.

Langkah 1: Buat pesanan API sandbox

Buat pesanan pay-in melalui API (lihat referensi Pay-in wilayah Anda). Permintaan harus menyertakan paymentMethod yang tidak kosong (misalnya QRIS untuk Indonesia).

Langkah 2: Simulasikan callback

1. Di backend merchant (Sandbox), buka Pay-in Order.
2. Cari pesanan yang Anda buat.
3. Di kolom Operate, klik Set Callback untuk mensimulasikan notifikasi sukses atau gagal.
4. Periksa kolom Callback Status untuk hasil pengiriman.

Metode pembayaran wajib

Jika paymentMethod kosong saat membuat pesanan sandbox, Set Callback mungkin tidak berfungsi. Selalu kirim metode pembayaran yang valid dalam permintaan API.

Produksi

Ketika pembayaran atau disbursement nyata selesai, Smilepayz mengirim callback secara otomatis. Tidak ada aksi manual Set Callback.

Verifikasi Tanda Tangan Callback

Setiap callback menyertakan header tanda tangan. Verifikasi dengan Platform Public Key sebelum memperbarui pesanan.

Header permintaan

Header	Deskripsi
Content-Type	application/json
X-TIMESTAMP	Stempel waktu, mis. 2020-12-17T10:55:00+07:00
X-SIGNATURE	Tanda tangan RSA (Base64)

String untuk ditandatangani

Smilepayz menandatangani dengan kunci privat platform. Anda memverifikasi dengan kunci publik platform:

stringToSign = tradeNo + "|" + X-TIMESTAMP
X-SIGNATURE = SHA256withRSA(smilepayz_private_key, stringToSign)

Langkah verifikasi

1. Baca X-SIGNATURE dan X-TIMESTAMP dari header permintaan.
2. Baca tradeNo dari body JSON.
3. Susun stringToSign sebagai tradeNo + "|" + X-TIMESTAMP.
4. Verifikasi X-SIGNATURE dengan Platform Public Key menggunakan SHA256withRSA.
5. Jika valid, proses pembaruan status; jika tidak, tolak permintaan.

Gunakan checkSha256RsaSignature dari dokumentasi Tools / SDK, atau lihat Otorisasi Tanda Tangan untuk model penandatanganan lengkap.

Body Callback (JSON)

Body POST callback berformat JSON. Field utama meliputi orderNo, tradeNo, merchantId, status, money, dan transactionTime.

Format transactionTime: yyyy-MM-ddTHH:mm:ss (zona waktu wilayah tempat pesanan dibuat).

Daftar field lengkap ada di referensi API Pay-in atau Pay-out wilayah Anda, bagian Notification/Callback → Body Parameters.

Merespons Callback

Setelah verifikasi dan pemrosesan berhasil, kembalikan string teks biasa:

SUCCESS

Jangan mengembalikan JSON atau konten lain. Smilepayz menganggap respons lain sebagai kegagalan dan dapat mengulang pengiriman.

Daftar Periksa Implementasi

1. Konfigurasi URL — Atur alamat notifikasi pay-in dan penarikan di sandbox/produksi.
2. Dapatkan Platform Public Key — Dari Informasi Integrasi.
3. Verifikasi setiap callback — Periksa X-SIGNATURE sebelum mempercayai body.
4. Perbarui status pesanan — Petakan status ke alur kerja internal Anda.
5. Kembalikan SUCCESS — Hanya setelah pembaruan tercatat dengan aman di sisi Anda.

Catatan Penting

• Selalu verifikasi tanda tangan — Jangan percaya body callback yang belum diverifikasi.
• Gunakan kunci publik yang benar — Kunci sandbox dan produksi berbeda.
• Penanganan idempoten — Retry dapat mengirim notifikasi yang sama lebih dari sekali.
• Hanya pesanan API — Pesanan payment link di portal merchant tidak memicu callback integrasi.

Pemecahan Masalah

Masalah	Tindakan
Callback tidak diterima	Pastikan URL notifikasi tersimpan; periksa firewall dan sertifikat HTTPS
Verifikasi tanda tangan gagal	Gunakan Platform Public Key lingkungan yang sama; periksa urutan tradeNo dan X-TIMESTAMP dalam stringToSign
Set Callback tidak ada di sandbox	Buat pesanan via API terlebih dahulu; pastikan paymentMethod tidak kosong
Callback terus diulang	Kembalikan teks SUCCESS dengan HTTP 200 setelah diproses

Dukungan

• Dokumentasi: Referensi API regional dan Otorisasi Tanda Tangan
• Dukungan Teknis: Masalah URL callback dan tanda tangan
• Layanan Pelanggan: Akses akun dan lingkungan