Protokol Bandung Version 1.0 Documentation 24 Maret 2010
Protokol Bandung – Documentation
1
Daftar Isi Daftar Isi .................................................................................................................................................. 2 Skenario .................................................................................................................................................. 3 XML RPC .............................................................................................................................................. 3 Target URL ........................................................................................................................................... 3 Lowercase – Case Sensitive................................................................................................................. 4 Synchronous & Asynchronous ............................................................................................................ 4 Pengulangan Transaksi........................................................................................................................ 4 IP Address ........................................................................................................................................... 4 Signature ............................................................................................................................................. 4 Function .................................................................................................................................................. 6 1. Topup .............................................................................................................................................. 6 1.1 Request ..................................................................................................................................... 6 1.2 .Response .................................................................................................................................. 6 2 Cek Status/Inquiry ............................................................................................................................ 7 2.1 Request ..................................................................................................................................... 7 2.2 .Response .................................................................................................................................. 7 3 Balance ............................................................................................................................................. 8 3.1 Request ..................................................................................................................................... 8 3.2 .Response .................................................................................................................................. 8 4 Product ............................................................................................................................................. 9 4.1 Request ..................................................................................................................................... 9 4.2 .Response .................................................................................................................................. 9 5 Echo .................................................................................................................................................. 9 5.1 Request ..................................................................................................................................... 9 5.2 .Response .................................................................................................................................. 9 6 Report ............................................................................................................................................ 10 6.1 Request ................................................................................................................................... 10 6.2 .Response ................................................................................................................................ 10 Appendix ........................................................................................................................................... 11 A.1 Status ...................................................................................................................................... 11 A.2 Operator ................................................................................................................................. 12
Protokol Bandung – Documentation
2
Skenario XML RPC Spesifikasi ini menggunakan standar XML-RPC. Informasi lebih lanjut mengenai XML-RPC, bisa dipelajari di http://www.xmlrpc.com/spec
Target URL URL target menggunakan protokol HTTP atau HTTPS dengan format umum: http://hostname:port/path/to/xmlrpc atau https://hostname:port/path/to/xmlrpc Contoh: HTTP Menggunakan port spesifik 8080 http://server.example.org:8080/xmlrpc http://192.168.1.1:8080/xmlrpc Menggunakan port default 80 http://server.example.org/xmlrpc http://192.168.1.1/xmlrpc
HTTPS Menggunakan port spesifik 8080 https://server.example.org:8080/xmlrpc https://192.168.1.1:8080/xmlrpc Menggunakan port default 443 https://server.example.org/xmlrpc https://192.168.1.1/xmlrpc
Protokol Bandung – Documentation
3
Lowercase – Case Sensitive Semua function, key (parameter) dan value yang dikirim harus dalam bentuk lowercase sebab beberapa system memproses string secara case sensitive. Contoh: SALAH Topup TOPUP BENAR topup
Synchronous & Asynchronous Server dapat memproses topup secara synchronous (proses dahulu,baru merespon) maupun asynchronous (respon dahulu, baru diproses), tergantung implementasi masing-masing. Jika proses terjadi secara synchronous, server harus mengirim status hasil transaksi yang sudah diproses beserta serial number transaksi dari operator (untuk transaksi sukses). Jika proses terjadi secara asynchronous, server mengirim status berupa 100 (pending), 101 (pending/antrian/queueing), atau 300 (approve) tanpa serial number transaksi dari operator. Pihak client harus mengirim inquiry untuk melakukan pengecekan status transaksi tersebut dengan interval 5 detik tiap inquiry, maksimum 2x inquiry. Jika setelah inquiry yang kedua masih belum ada perubahan status menjadi 000 (SUKSES) atau GAGAL (2xx), maka status transaksi tersebut akan dikirim oleh server kepada pihak client melalui function report.
Pengulangan Transaksi Pengulangan transaksi per userid diperbolehkan selama reqid yang dikirimkan juga berbeda.
IP Address IP Address client atau pengirim bisa menggunakan IP statik, maupun IP dinamik tergantung security rule dari pihak server.
Signature Password atau PIN tidak dikirim, melainkan menggunakan signature yang di-generate menggunakan algoritma hash MD5. signature = md5(pin+reqid) Contoh: Jika PIN adalah ‘123456’ dan reqid adalah 100 maka signaturenya adalah: signature = md5(‘123456100’) = ‘46dd4ef947c3224427e3e9d4a0bb5ea1’
Protokol Bandung – Documentation
4
Protokol Bandung – Documentation
5
Function 1. Topup Function topup digunakan untuk transaksi isi pulsa. Function ini dipanggil oleh client, dieksekusi oleh pihak server. MethodName: topup 1.1 Request Key reqid productid msisdn userid signature trxtime
Type[length] String[20] String[10] String[20] String[32] String[32] ISO8601
Description ID transaksi dari server pengirim Kode produk Nomor handphone UserID pengirim MD5(pin+reqid) Waktu transaksi dikirim dalam WIB (GMT +7)
1.2 .Response Key reqid respid status
Type[length] String[20] String[20] String[3]
resptime sn balance price message info
ISO8601 String String[10] String[10] String[255] String[255]
Description ID transaksi dari server pengirim ID transaksi dari server penerima Status transaksi 00x: Sukses 1xx:Pending 2xx:Gagal 300: Approve Lihat tabel A.1 Status Waktu transaksi diproses Serial number Saldo Harga Pesan hasil proses transaksi Info tambahan
Protokol Bandung – Documentation
6
2 Cek Status/Inquiry Function status digunakan untuk cek status transaksi atau inquiry dari pihak client ke server. MethodName: status 2.1 Request Key reqid userid signature
Type[length] String[20] String[32] String[32]
Description ID transaksi dari server pengirim UserID pengirim MD5(pin+reqid)
2.2 .Response Key reqid respid status
Type[length] String[20] String[20] String[3]
resptime sn balance price message info
ISO8601 String String[10] String[10] String[255] String[255]
Description ID transaksi server pengirim ID transaksi dari server penerima Status transaksi 00x: Sukses 1xx:Pending 2xx:Gagal 300: Approve Lihat tabel A.1 Status Waktu transaksi diproses Serial number Saldo Harga Pesan hasil proses transaksi Info tambahan
Protokol Bandung – Documentation
7
3 Balance Function balance digunakan untuk mendapatkan saldo terakhir atau sisa deposit. MethodName: balance 3.1 Request Key reqid userid signature
Type[length] String[20] String[32] String[32]
Description ID transaksi dari server pengirim UserID pengirim MD5(pin+reqid)
3.2 .Response Key reqid respid status
Type[length] String[20] String[20] String[3]
resptime balance message info
ISO8601 String[10] String[255] String[255]
Description ID transaksi server pengirim ID transaksi dari server penerima Status transaksi 00x: Sukses 1xx:Pending 2xx:Gagal 300: Approve Lihat tabel A.1 Status Waktu transaksi diproses Saldo Pesan hasil proses transaksi Info tambahan
Protokol Bandung – Documentation
8
4 Product Function product digunakan untuk cek status produk dan harga per operator. MethodName: product 4.1 Request Key reqid userid signature operator
Type[length] String[20] String[32] String[32] String
Description ID transaksi dari server pengirim UserID pengirim MD5(pin+reqid) Nama operator
4.2 .Response Key reqid respid status
Type[length] String[20] String[20] String[3]
Description ID transaksi server pengirim ID transaksi dari server penerima Status request Lihat tabel A.1 Status Waktu transaksi diproses Array yang berisi item dalam tipe struct. Tiap item memiliki elemen product dan price.
resptime products
info
ISO8601 array of struct { product: string price: string } String[255]
Info tambahan
5 Echo Function echo digunakan untuk cek apakah server sedang beroperasi. Fungsi ini hanya mengirim satu parameter message dalam tipe string. Server merespon fungsi echo dengan mengirim kembali pesan teks dari pengirim. MethodName: echo 5.1 Request Key message
Type[length] String
Description Pesan teks pengirim
5.2 .Response Key message
Type[length] String
Description Pesan teks pengirim
Protokol Bandung – Documentation
9
6 Report Function report dikirim oleh server kepada client (pengirim transaksi) berisi informasi pengiriman status topup terakhir. Pihak client merespon dengan string status yang hanya berfungsi sebagai ACK, tidak dicek/diproses oleh server. Fungsi ini bersifat opsional, sebagai alternatif jika proses di server memakan waktu lebih lama maka client tidak perlu mengirim inquiry. Mirip dengan fungsi reversal, bedanya pada status yang dikirim bisa sukses atau gagal. Fungsi ini membutuhkan informasi host atau URL target yang disediakan oleh client. MethodName: report 6.1 Request Key reqid respid status
Type[length] String[20] String[20] String[3]
resptime sn balance price message info
ISO8601 String String[10] String[10] String[255] String[255]
Description ID transaksi server pengirim ID transaksi dari server penerima Status transaksi 00x: Sukses 1xx:Pending 2xx:Gagal 300: Approve Lihat tabel A.1 Status Waktu transaksi diproses Serial number Saldo Harga Pesan hasil proses transaksi Info tambahan
6.2 .Response Key status
Type[length] String
Description ACK
Protokol Bandung – Documentation
10
Appendix A.1 Status Status Description 000 Sukses, SN Transaksi berhasil, serial number tercantum 001 Sukses, No SN Transaksi berhasil, serial number belum tersedia 100 Pending timeout Transaksi sudah diterima, menunggu diproses 101 Pending antrian Transaksi sudah diterima, menunggu antrian 200 Gagal – produk kosong Transaksi gagal karena produk kosong 201 Gagal - gangguan operator Transaksi gagal karena problem di operator 202 203 204 205 206 207 208 209 210 211 212 213 214 300
Gagal - gangguan server Transaksi gagal karena problem di server Gagal - saldo habis Transaksi gagal karena saldo tidak cukup Gagal - nomor tujuan salah Transaksi gagal karena MSISDN salah/invalid Gagal - kode produk salah Transaksi gagal karena kode produk salah/invalid Gagal - salah format Transaksi gagal karena format MSISDN salah Gagal - otentikasi Transaksi gagal karena userid/pin salah Gagal - duplikasi Transaksi gagal, ditolak karena sudah pernah dikirim/diulang Gagal – unknown/belum didefinisikan Transaksi gagal, sebab belum diketahui, cek di web report atau hubungi customer service Gagal - cross region Transaksi gagal, ditolak karena transaksi lintas region Gagal – invalid signature Transaksi gagal, signature salah/invalid Gagal – IP diblokir Transaksi gagal, IP pengirim diblokir Gagal – user diblokir Transaksi gagal karena userid pengirim diblokir oleh sistem Gagal – request expired Transaksi gagal karena request dari pengirim expired Approve Transaksi sudah diterima, belum diproses, saldo sudah dipotong
Protokol Bandung – Documentation
User Action
Cek inquiry Tunggu report Cek inquiry Cek web report atau hubungi customer service Hubungi customer service Alihkan transaksi Cek web report atau hubungi customer service Cek web report atau hubungi customer service Koreksi MSISDN dan kode produk Koreksi kode produk atau hubungi customer service Koreksi MSISDN dan kode produk Koreksi userid atau pin Cek inquiry Cek web report atau hubungi customer service
Koreksi PIN Cek IP, Hubungi customer service Hubungi customer service Koreksi setting date/time pengirim Gagalkan Cek inquiry
11
A.2 Operator Value telkomsel indosat xl telkom esia fren three axis ceria smart
Product Simpati, As Mentari, IM3, StarOne XL Flexi Esia Fren Three Axis Ceria Smart
Protokol Bandung – Documentation
Description P.T. Telkomsel P.T. Indosat P.T. Excel Axiata P.T. Telkom/Flexi P.T. Bakrie Telecom/Esia P.T. Mobile-8 P.T. Hutchison Indonesia/Three P.T. Axis P.T. Sampoerna Telecom/ceria P.T. Smart Telecom
12
