MERCHANT
MANUAL VERSION 2.0
http://www.payglobalone.com/downloads/merchant-manual-2.0.pdf
-1-
DAFTAR ISI DAFTAR ISI......................................................................................................................1 PENDAHULUAN................................................................................................................2 DAFTAR AKUN MERCHANT PG-1 ......................................................................................4 AKTIVASI FITUR MERCHANT ...........................................................................................7 STATUS TRANSAKSI .......................................................................................................8 PAYMENT APPROVAL/REJECTION ................................................................................10 PENGATURAN SETTLEMENT ..........................................................................................11 INTEGRASI TOKO ONLINE DENGAN PG-1..........................................................................12 INSTANT PAYMENT NOTIFICATION.................................................................................23 PG-1 API ACCESS ...........................................................................................................26 MEMAHAMI PENGGUNAAN API PG-1 ..........................................................................27 CARA MEMBUAT REQUEST SIGNATURE ....................................................................28 MELAKUKAN PEMANGGILAN API PG-1.......................................................................29 DAFTAR API PG-1.......................................................................................................29
-1-
PENDAHULUAN Jika Anda memiliki sebuah toko online (website e-commerce) di Internet dan ingin agar dapat menerima pembayaran secara online, Pay Global One dapat menjadi pilihan yang tepat untuk Anda. Beberapa keuntungan yang dapat Anda peroleh dengan menjadi merchant PG-1 antara lain: Dapat meng-otomasi bisnis Anda sehingga Anda dapat lebih fokus kepada model bisnis inti Anda Memperluas potensi pelanggan Anda ke seluruh member aktif PG-1 Pembayaran diterima menggunakan mata uang lokal, sehingga dapat mengurangi resiko kerugian akibat nilai tukar mata uang Biaya operasional yang sangat ringan menjadikan bisnis Anda semakin menarik dan efektif Kemudahan dalam pengaturan dan pengawasan penerimaan pembayaran dari pembeli Dll
Ada aturan dasar yang harus Anda ikuti untuk menjadi merchant PG-1, yaitu Anda TIDAK BOLEH menjalankan jenis-jenis bisnis berikut: Perjudian Pengundian Kupon Berhadiah Pornografi Money Game (Arisan, MLM tanpa produk yang jelas, dll) Usaha yang illegal atau bertentangan dengan hukum yang berlaku di negara beroperasinya PayGlobalOne
PG-1 memiliki hak untuk memblok pembayaran ke akun merchant Anda apabila bisnis yang Anda jalankan termasuk salah satu dari bisnis terlarang diatas, termasuk menutup akun dan memberikan informasi detail mengenai akun Anda kepada pihak yang berwajib jika dibutuhkan.
Berikut ini tabel perbedaan secara umum antara akun Merchant dan Buyer PG-1:
-2-
Fitur
Merchant
Buyer
Dapat menerima pembayaran
Ya
Tidak
Dapat mendaftarkan toko online
Ya
Tidak
Butuh verifikasi alamat
Ya
Tidak
Fitur settlement ke rekening bank
Ya
Tidak
-3-
DAFTAR AKUN MERCHANT PG-1 Akun Merchant PG-1 merupakan akun PG-1 yang dapat Anda gunakan untuk menerima pembayaran dari seluruh member PG-1. Akun ini memiliki semua fitur yang dimiliki oleh Akun Buyer PG-1 ditambah dengan fitur-fitur penerimaan pembayaran serta pengelolaan toko dan transaksi. Dengan menggunakan akun ini, memungkinkan Anda untuk menjual barang dan menerima pembayaran secara online. Anda dapat melakukan registrasi akun Merchant PG-1 dengan cara sebagai berikut: 1. Kunjungi website PG-1 di https://secure.payglobalone.com/, dan klik link Free Sign Up Here, lalu pilih Merchant Account 2. Registrasi tahap 1 – Your Personal Detail Pada proses registrasi tahap 1 ini Anda di minta untuk mengisi data-data pribadi Contact Person bisnis Anda. Data ini harus diisi dengan informasi yang benar, terutama Primary Email, Identity Card Number (Nomor KTP), dan Correspondence Address. Primary Email akan
dipergunakan untuk
mengirimkan notifikasi dan konfirmasi akun PG-1 Anda. Primary Email juga akan dipergunakan sebagai identitas Authentifikasi akun PG-1 Anda. Identity Card Number harus tepat sama dengan nama lengkap yang didaftarkan. Correspondence Address harus valid dan tidak boleh berupa PO. BOX, karena kami akan mengirimkan surat berisikan kode aktivasi ke alamat terkait untuk mengaktifkan fitur merchant akun PG-1 Anda.
-4-
3. Registrasi tahap 2 – Settlement Bank Account Pada tahap ini, Anda diminta mendaftarkan rekening bank yang akan digunakan untuk menerima settlement pembayaran di akun merchant PG-1 Anda. Pastikan Anda meng-input informasi rekening bank yang valid, karena untuk keamanan, informasi tersebut tidak akan dapat dirubah lagi setelah pendaftaran.
4. Registrasi tahap 3 – Input Security Detail Pada tahap ini, Anda diminta untuk menentukan password yang akan Anda gunakan untuk keperluan Authentikasi akun PG-1 Anda. Untuk keamanan akun PG-1 Anda, buatlah password dengan kombinasi angka, huruf, dan karakter unik tetapi familiar bagi Anda. Disamping itu, pada tahap ini Anda juga perlu menentukan PIN sebagai kode Otorisasi setiap kali melakukan transaksi. Pada tahap ini juga terdapat beberapa kolom pertanyaan dan jawaban yang akan ditanyakan secara acak oleh sistem PG-1 untuk situasisituasi khusus (lupa password, reset PIN, dsb). Contoh pertanyaan pengaman yang baik dipergunakan: Question Custom 1 : Pernah jatuh parah dan dijahit di? Answer 1 : Lutut kiri
-5-
Pada saat melakukan registrasi harap diperhatikan baik-baik seluruh data yang Anda masukkan, jangan sampai melakukan kesalahan dalam pengisian email, password, PIN, Security dan Answer Question serta data-data lainnya. Isilah dengan data yang valid. Pay Global One tidak bertanggung jawab terhadap kerugian atau kesulitan yang ditimbulkan akibat kesalahan dalam pengisisan data-data tersebut.
-6-
AKTIVASI FITUR MERCHANT Pada saat Anda mendaftar akun Merchant PG-1, Anda akan diminta untuk menginput alamat korespondensi, dimana alamat tersebut digunakan untuk mengirimkan kode aktivasi fitur merchant PG-1. Silakan tunggu beberapa hari kerja, Anda akan menerima surat yang berisi kode aktivasi. Setelah menerima kode aktivasi, silakan login ke akun merchant PG-1 Anda dan klik menu “Activate Merchant Feature”, dan ketik kode aktivasi yang Anda terima untuk mengaktifkan fitur-fitur merchant PG-1.
Form input kode aktivasi fitur Merchant PG-1
-7-
STATUS TRANSAKSI Yang dimaksud dengan transaksi disini yaitu transaksi pembayaran dari pembeli kepada merchant. Setiap transaksi memiliki sebuah status, dan di PG-1 ada 4 buah status transaksi yang mungkin terjadi, antara lain:
1. ISSUED Status ini terjadi pada saat pembeli berhasil melakukan pembayaran kepada merchant. Pada tahap ini, saldo Gollar pembeli akan berkurang dan ditahan oleh sistem PG-1 (merchant belum menerima pembayaran) 2. CONFIRMED Status ini terjadi pada saat pembeli mengakui atau melakukan konfirmasi atas pembayaran yang dilakukan. Setelah pembayaran diakui, maka pembeli tidak dapat membatalkan lagi pembayaran terkait 3. APPROVED Status ini terjadi pada saat merchant mengakui pembayaran yang dilakukan oleh pembeli. Pada tahap ini saldo Gollar merchant akan bertambah 4. REJECTED Status ini terjadi apabila merchant membatalkan pembayaran. Pada tahap ini, saldo Gollar yang dipergunakan untuk membayar transaksi akan dikembalikan ke dalam akun PG-1 pembeli
Untuk memahami ke-4 status diatas, silakan lihat diagram berikut ini:
ISSUED
CONFIRMED
REJECTED
APPROVED
-8-
Berikut ini merupakan rangkuman apa yang harus dilakukan untuk masing-masing status transaksi:
Status
Buyer
ISSUED
Melakukan
Merchant pembayaran
pada -
halaman pembayaran PG-1. CONFIRMED
Untuk transaksi > 1 juta Anda harus melakukan otorisasi pembayaran dengan cara input Kode Otorisasi yang dikirimkan ke email.
APPROVED
-
Approve
pembayaran dari menu
pada menu “Pending Payments” setelah login ke merchant PG-1 REJECTED
-
Reject
pembayaran
pada
menu
“Pending Payments” setelah login ke merchant PG-1
-9-
PAYMENT APPROVAL/REJECTION Setiap kali Anda menerima pembayaran dari pembeli, Anda akan menerima notifikasi melalui email merchant/webstore yang sudah didaftarkan. Langkah selanjutnya yaitu Anda perlu melakukan approval / rejection terhadap pembayaran terkait melalui menu “Pending Payments” setelah login ke akun merchant PG-1 Anda. Pembayaran yang sudah di approve, tidak dapat di cancel kembali, begitu pula sebaliknya. Pada saat approve / cancel, Anda perlu melakukan otorisasi menggunakan PIN Anda.
Form Payment Approval/Rejection
- 10 -
PENGATURAN SETTLEMENT Settlement merupakan jadwal pemindahan saldo balance Gollar akun merchant PG-1 Anda ke rekening bank settlement yang Anda daftarkan. Settlement akun merchant PG-1 Anda dilakukan secara otomatis oleh sistem PG-1. Perhitungan Settlement dilakukan pada hari operasional staff kami (kondisi normal: Senin – Jumat), satu hari sekali antara pukul 8 pagi sampai pukul 12 siang. Jika akun merchant Anda belum disertakan pada jadwal settlement hari tertentu, maka akan diikutkan pada perhitungan settlement hari operasional selanjutnya. Anda dapat memilih satu diantara 2 metode settlement yang disediakan dari menu “Manage Settlement”: 1. Setiap minggu pada hari tertentu (Senin – Jumat) 2. Jika saldo Gollar akun merchant PG-1 Anda mencapai nilai minimal tertentu
Form pengaturan metode settlement akun merchant PG-1
- 11 -
INTEGRASI TOKO ONLINE DENGAN PG-1 Pada menu fitur merchant, Anda dapat menemukan menu ”Manage Store”. Menu ini digunakan untuk mendaftarkan toko online Anda sehingga dapat terintergrasi dengan sistem pembayaran online PG-1. Yang perlu Anda lakukan yaitu klik tombol ”Add New Store” untuk mendaftarkan toko online Anda dan ikuti tahap berikut ini: 1. Input
URL
lengkap
webstore
Anda
(misalnya:
http://www.myonlinewebstore.com/) , lalu klik tombol Verify
2. PG-1 akan memastikan terlebih dahulu, apakah Anda benar pemilik webstore terkait. Ada 2 cara yang dapat Anda pilih antara lain: a. Mengupload sebuah HTML file ke server hosting Anda (Simple) Untuk contoh diatas, silakan download file HTML dengan cara klik link “this HTML verification file”, dan upload file tersebut ke root domain hosting Anda. Untuk melakukan pengecekan silakan klik URL yang diberikan pada point ke-3. Selanjutnya klik tombol “Verify” untuk melakuan proses verifikasi.
Instruksi verifikasi webstore dengan upload file HTML
- 12 -
b. Menambahkan DNS record pada konfigurasi domain Anda (Advanced) Misalnya untuk contoh diatas (domain: myonlinewebstore.com) Anda perlu menambahkan record DNS dengan tipe TXT untuk host: payglobalone._verify dengan value: payglobalone-site-verification=19e204fc3f-5dd85cb7d0f2dd3c0f9d79e4fec3cdb9
Selanjutnya klik tombol “Verify” untuk melakuan proses verifikasi.
Instruksi verifikasi webstore dengan menambah record DNS domain
3. Selanjutnya Anda perlu mengisi form integrasi toko online Anda sebagai berikut:
- 13 -
a. Store ID Store ID merupakan ID toko online yang telah Anda daftarkan di PG-1. ID ini digenerate otomatis oleh PG-1 dan digunakan sebagai identitas toko online Anda. b. Store Main Page URL Merupakan URL halaman utama toko online Anda yang sudah didaftarkan (akan ditampilkan pada halaman pembayaran). c. Store Name Isi dengan nama toko online Anda (akan ditampilkan pada halaman pembayaran). d. Store Email (Optional) Input alamat email khusus untuk toko online terkait jika ada. Email ini digunakan untuk menerima notifikasi pembayaran pada toko terkait. Jika dikosongkan notifikasi akan dikirimkan ke email merchant. e. Unpaid Transaction Wait Isi dengan angka satuan hari untuk memberikan toleransi kepada pembeli dalam menyelesaikan pembayaran nya. Minimum toleransi hari adalah 1 hari, jadi apabila dalam 1 hari pembeli tidak menyelesaikan pembayaran nya maka transaksi terkait akan otomatis dibatalkan dan pembeli harus melakukan checkout ulang untuk mengulang transaksi nya. f. Successful URL Input dengan URL pada webstore Anda untuk mengarahkan user setelah melakukan pembayaran pada halaman pembayaran PG-1. g. Cancel URL Input dengan URL pada webstore Anda untuk mengarahkan user apabila mengklik link ”Cancel Payment” pada halaman pembayaran PG-1. h. Payment Notification URL (IPN) Input dengan URL pada webstore Anda yang berisikan skrip untuk menerima notifikasi instant dari PG-1 setiap kali terjadi pembayaran pada webstore terkait. Untuk lebih detail mengenai IPN akan dibahas pada topik selanjutnya. i. Banner Pilih file gambar yang ingin dijadikan logo webstore Anda pada halaman pembayaran PG-1. - 14 -
i. Auto approve all payment Centang jika Anda ingin seluruh pembayaran untuk webstore terkait di-approve secara otomatis (tidak dapat dicancel kembali). j. Add successful URL above in successful payment email Centang jika Anda ingin menyertakan Successful URL pada email notifikasi pembayaran berhasil yang dikirimkan oleh PG-1 ke pembeli (biasanya Successful URL berupa link download, dll).
Setelah berhasil mendaftarkan toko online Anda, langkah selanjutnya adalah membuat tombol bayar untuk webstore Anda. Silakan klik tombol “Pay Button” pada daftar webstore yang sudah terdaftar di akun merchant Anda, seperti gambar dibawah ini:
Daftar toko online terdaftar di akun merchant PG-1
Ada 3 jenis tombol yang dapat Anda buat melalui tool yang disediakan di firtur merchant PG-1, antara lain: 1. Pay Now Button (Tombol Pembayaran) Pay Now button digunakan untuk membuat tombol pembayaran untuk suatu item tertentu. Tombol ini biasanya diletakkan pada halaman detail item terkait.
- 15 -
Isi form yang disediakan lalu klik tombol submit. Selanjutnya copy dan paste kode HTML yang di-generate oleh PG-1 ke halaman detail item terkait. Umumnya tombol ini digunakan jika hanya ada sedikit jenis item yang dijual.
a. Payment Description Isi dengan deskripsi pembayaran PG-1. Deskripsi ini akan tampil pada halaman pembayaran dan histori transaksi. b. Payment Price Isi dengan nilai pembayaran yang diinginkan (dalam satuan IDR). c. Encrypt the button Untuk meningkatkan keamanan (mencegah perubahan informasi pada tombol yang Anda buat), silakan centang field ini agar informasi yang terkandung pada tombol pembayaran di enkripsi oleh PG-1.
- 16 -
d. Choose Button Image Pilih gambar tombol yang Anda inginkan. Anda juga dapat menggunakan gambar tombol yang Anda buat sendiri dengan cara klik ”Use custom image” dan input URL ke file gambar tombol yang diinginkan. 2. Add to Cart Button (Tombol Masukkan Keranjang Belanja) Tombol ini digunakan untuk menyediakan fitur shopping cart / keranjang belanja pada webstore Anda jika belum tersedia (misalkan webstore Anda hanya menggunakan halaman statis). Dengan tombol ini, pembeli dapat berbelanja beberapa item sekaligus dalam 1 kali checkout dan pembayaran. Umumnya tombol ini digunakan apabila Anda menjual banyak jenis item di webstore Anda. Tombol Add to Cart ini biasanya diletakkan pada halaman detail item. Setiap kali pembeli klik tombol ini, item terkait akan dimasukkan ke dalam keranjang belanja webstore Anda di PG-1, dari sana pembeli dapat melakukan checkout dan pembayaran atas item-item yang ingin dibeli. Isi form yang disediakan lalu klik tombol submit. Selanjutnya copy dan paste kode HTML yang di-generate oleh PG-1 ke halaman detail item terkait.
- 17 -
a. Item Name Isi dengan nama item yang dijual. b. Item Unique Code Isi dengan kode item yang dijual. Kode ini harus bersifat unik (tidak boleh sama) untuk item yang berbeda. c. Item Price Isi dengan harga item yang dijual (dalam satuan IDR). d. Need Physical Delivery Jika item yang dipesan membutuhkan pengiriman secara fisik ke alamat tertentu, silakan centang field ini. Jika item terkait dibeli oleh buyer, maka pada saat checkout, buyer akan diminta untuk input alamat pengiriman, sehingga Anda dapat melakukan pengiriman ke alamat terkait. e. Encrypt the button Untuk meningkatkan keamanan (mencegah perubahan informasi pada tombol yang Anda buat), silakan centang field ini agar informasi yang terkandung pada tombol pembayaran di enkripsi oleh PG-1. f. Choose Button Image Pilih gambar tombol yang Anda inginkan. Anda juga dapat menggunakan gambar tombol yang Anda buat sendiri dengan cara klik ”Use custom image” dan input URL ke file gambar tombol yang diinginkan.
3. View Shopping Cart Button Tombol ini digunakan agar pembeli dapat melihat kembali item-item yang sudah dimasukkan ke dalam keranjang belanja mereka sebelum melakukan checkout. Umumnya tombol ini di tampilkan di semua halaman webstore (cenderung di bagian header), agar pembeli setiap saat dapat melakukan checkout pada itemitem yang ingin dibelinya.
Kirim form yang disediakan dengan klik tombol submit. Selanjutnya copy dan paste kode HTML yang di-generate oleh PG-1 ke webstore Anda.
- 18 -
a. Encrypt the button Untuk meningkatkan keamanan (mencegah perubahan informasi pada tombol yang Anda buat), silakan centang field ini agar informasi yang terkandung pada tombol pembayaran di enkripsi oleh PG-1. b. Choose Button Image Pilih gambar tombol yang Anda inginkan. Anda juga dapat menggunakan gambar tombol yang Anda buat sendiri dengan cara klik ”Use custom image” dan input URL ke file gambar tombol yang diinginkan.
- 19 -
MEMBUAT TOMBOL PEMBAYARAN DINAMIS Jika toko online Anda hanya menjual beberapa item saja dan jarang terjadi perubahan harga, maka tidak menjadi masalah untuk membuat tombol pembayaran PG-1 melalui tools yang telah disiapkan oleh PG-1 pada merchant area untuk setiap item yang Anda jual. Namun bagaimana jika webstore Anda menjual ratusan, bahkan ribuan item, dan perubahan harga sering kali terjadi? Jika setiap item harus dibuat satu-per satu tombol pembeliannya dan harus diperbaruhi secara manual apabila ada perubahan harga, maka Anda akan direpotkan dalam hal teknis padahal seharusnya Anda lebih berkonsentrasi pada penjualan produk Anda.
Untuk kasus ini, Anda membutuhkan solusi lain yaitu sebuah tombol pembayaran yang bersifat dinamis, dimana parameter yang terkandung didalam tombol pembayaran tersebut dapat mengikuti perubahan yang terjadi pada item yang Anda jual secara otomatis. Contoh kasus lainnya yang juga membutuhkan solusi yang sama yaitu apabila toko online Anda sudah memiliki keranjang belanja sendiri, dimana nilai total dari keranjang belanja tersebut tentunya akan berubah-ubah sesuai dengan item yang dibeli oleh pelanggan Anda.
Untuk membuat sebuah tombol pembayaran yang dinamis, membutuhkan pengetahuan sederhana mengenai pemrograman web. Anda dapat mempelajari tutorial-tutorial yang banyak tersedia di Internet, atau Anda dapat menyerahkannya kepada pihak yang memang sudah ahli di bidang pemrograman web.
Tombol pembayaran PG-1 sebenarnya merupakan kode HTML form sederhana. Berikut ini merupakan contoh kode HTML untuk tombol pembayaran PG-1:
Semua parameter pada tombol pembayaran PG-1 dapat diisi dengan nilai yang dinamis sesuai dengan pembayaran yang akan dilakukan dari website toko online Anda. Anda dapat menggunakan berbagai bahasa pemrograman web (PHP, ASP, JSP, atau lainnya) sesuai dengan script yang Anda gunakan untuk toko online Anda. Silakan lihat keterangan pada tabel dibawah ini untuk mengetahui nilai apa yang seharusnya diinput pada setiap parameter tombol pembayaran PG-1 diatas:
merchant Parameter ini diisi dengan email utama akun Merchant PG-1 Anda. store-id Parameter ini diisi dengan ID webstore Anda yang sudah berhasil didaftarkan di akun merchant Anda. trans-id (Optional) Parameter ini bersifat optional, biasanya digunakan jika Anda memanfaatkan fitur IPN (Instant Payment Notification) di PG-1. Parameter ini diisi dengan nomor invoice terkait di database webstore Anda, sehingga pada saat PG-1 mengirimkan IPN ke webstore Anda, script handler di webstore Anda dapat mengetahui pembayaran atas invoice apa yang sudah berhasil diterima. amount Parameter ini diisi dengan nilai pembayaran yang akan dilakukan oleh pembeli (dalam mata uang IDR). Biasanya diisi dengan nilai pembayaran yang dicantumkan pada shopping cart webstore Anda.
- 21 -
description Diisi dengan deskripsi pembayaran yang akan dilakukan oleh pembeli. Biasanya disertakan nomor invoice atau deskripsi yang bersifat informatif atas pembayaran terkait. cancel-url (Optional) Parameter ini bersifat optional, jika tidak diisi maka secara default akan menggunakan settingan Cancel URL di webstore Anda yang terdaftar di PG-1. URL ini digunakan untuk mengembalikan pembeli ke halaman webstore Anda apabila pembeli terkait meng-klik link “Cancel Payment“ pada halaman pembayaran PG-1. Pada saat link di klik, PG-1 akan mengirimkan beberapa parameter dengan nilai berupa JSON string terkait dengan pembayaran yang ingin dibatalkan pembeli antara lain: o trans-id Berisi informasi nomor invoice, contoh: [“INV-12345”] o amount Berisi informasi jumlah pembayaran, contoh: [“200000”] success-url (Optional) Parameter ini bersifat optional, jika tidak diisi maka secara default akan menggunakan settingan Success URL di webstore Anda yang terdaftar di PG-1. URL ini digunakan untuk mengembalikan pembeli ke halaman webstore Anda setelah menyelesaikan pembayaran dari halaman pembayaran PG-1. Pada saat pembeli klik tombol “Back to Webstore”, PG-1 akan mengirimkan beberapa parameter dengan nilai berupa JSON string terkait dengan pembayaran yang dilakukan antara lain: o trans-id Berisi informasi nomor invoice, contoh: [“INV-12345”] o amount Berisi informasi jumlah pembayaran, contoh: [“200000”] - 22 -
INSTANT PAYMENT NOTIFICATION IPN (Instant Payment Notification) merupakan sebuah fitur yang disediakan oleh PG1 agar Anda dapat memproses pesanan yang sudah dibayar oleh customer Anda secara otomatis. Dengan fitur ini, PG-1 akan mengirimkan notifikasi secara realtime kepada webstore Anda pada saat terjadi pembayaran dari customer, sehingga webstore Anda dapat melakukan pemrosesan secara otomatis.
Pada saat mendaftarkan webstore Anda di akun merchant, terdapat field “Payment Notification URL”, dimana field tersebut diisi dengan URL script pada webstore Anda untuk menghandle IPN dari PG-1. IPN dikirimkan oleh PG-1 menggunakan HTTP POST request. Adapun parameter yang dikirimkan antara lain:
version Versi IPN yang dikirimkan oleh PG-1. Contoh: 1.0 buyer Email utama akun PG-1 pembeli. Contoh:
[email protected] merchant Email utama akun merchant PG-1. Contoh:
[email protected] trans-id Nomor Invoice webstore untuk pembayaran terkait. Contoh: INV-12345 trx-id Nomor transaksi pembayaran PG-1. Contoh: JG334-2KJHK-21HS3-KLSS2-9SDSG amount Nilai pembayaran yang dilakukan oleh buyer. Contoh: 200000
- 23 -
status Status pembayaran terkait. Contoh: confirmed/approved/rejected/refunded confirmed Status ini dikirim apabila pembayaran telah disetujui oleh pembeli dan berhasil diproses. approved Status ini dikirim apabila pembayaran telah di setujui oleh merchant. Setelah pembayaran disetujui, balance Gollar Merchant akan bertambah sesuai dengan nilai pembayaran. rejected Status ini dikirimkan apabila pembayaran ditolak oleh merchant. Setelah ditolak, pembayaran terkait akan dikembalikan ke balance Gollar pembeli. refunded Status ini dikirimkan apabila sebagian dari nilai pembayaran di-refund oleh merchant (melalui API). Parameter amount akan berisi nilai pembayaran yang di-refund. description Deskripsi status pembayaran. Contoh: Payment has been confirmed successfully
Script handler IPN PG-1 di webstore Anda dapat memproses pesanan sesuai dengan status IPN yang dikirimkan oleh PG-1. Untuk menghindari penyalahgunaan, pastikan melakukan pencocokan nomor invoice dan nilai pembayaran yang dilakukan untuk mendapatkan data pesanan yang sesuai, dan pastikan IPN dikirimkan dari sever PG-1 dengan IP: 202.78.195.237. Berikut ini contoh sederhana IPN handler yang dibuat menggunakan PHP:
if($_SERVER[‘’] == ‘202.78.195.237’) { switch($_POST[‘status’]) { case ‘confirmed’: // Jika status pembayaran confirmed, lakukan sesuatu disini break;
- 24 -
case ‘approved’: // Jika status pembayaran approved, lakukan sesuatu disini break; case ‘rejected’: // Jika status pembayaran rejected, lakukan sesuatu disini break; case ‘refunded’: // Jika status pembayaran refunded, lakukan sesuatu disini break; } }
Anda dapat melihat history IPN yang dikirimkan oleh PG-1 melalu menu “Manage Store”, lalu klik tombol IPN pada toko yang Anda inginkan:
- 25 -
PG-1 API ACCESS PG-1 API Access merupakan akses yang diberikan PG-1 terhadap beberapa web service transaksi untuk melakukan beberapa aksi terhadap transaksi pembayaran yang Anda terima. Anda dapat mengaktifkan API PG-1 melalu menu “Manage Store”, lalu klik tombol “API Access” pada list toko yang telah didaftarkan pada akun merchant PG-1 Anda. Setelah Anda mengaktifkan API Access untuk webstore terkait, Anda akan mendapatkan “API Access Key” dan “API Secret Key” untuk mengakses service PG-1. Untuk keamanan Anda juga dapat membatasi hanya IP tertentu saja yang dapat mengakses API untuk webstore Anda.
API Access Key digunakan sebagai identitas akses API untuk webstore terkait, sedangkan API Secret Key digunakan untuk pembuatan signature untuk memastikan request API hanya dapat dikirimkan oleh webstore Anda sendiri. Untuk mencegah penyalahgunaan, jangan memberitahukan API Secret Key kepada pihak yang tidak berkepentingan. Jika sampai API Secret Key diketahui pihak lain, silakan klik “Disable API Access”, lalu lakukan enable kembali, maka Anda akan memperoleh API Access Key & API Secret Key yang baru.
- 26 -
MEMAHAMI PENGGUNAAN API PG-1 Setelah mengaktifkan fitur API Access untuk webstore terkait di akun merchant PG-1, Anda dapat langsung mengakses API PG-1 dari webstore Anda. Pemanggilan API PG1 sebenarnya hanya request HTTP (POST/GET) biasa yang diamankan dengan HTTP Basic Authentication. Setiap API membutuhkan parameter masing-masing yang dikirim melalui HTTP Request (POST/GET). Untuk HTTP Basic Authentication, Anda perlu menyertakan Username dan Password sebagai berikut: Username Untuk Username, gunakan API Access Key yang Anda dapatkan untuk webstore Anda. Password Untuk Password, Anda perlu membuat Signature dari parameter request pemanggilan API untuk dipergunakan sebagai password. Request Signature ini merupakan hash key yang dibentuk menggunakan algoritma tertentu dimana didalamnya menyertakan parameter request dan API Secret Key. Signature ini akan mengamankan request Anda dari usaha penyalahgunaan, karena hanya website Anda saja yang menyimpan API Secret Key untuk membuat Signature yang valid. Pada bagian berikut dari artikel ini, Anda akan diinformasikan mengenai cara & algoritma untuk membuat Request Signature.
Selain Username dan Password diatas, setiap pemanggilan API PG-1 Anda juga perlu menyertakan 2 parameter berikut ini (disamping parameter spesifik lainnya yang dibutuhkan masing-masing API): trx-id Parameter ini merupakan identitas setiap transaksi di PG-1 yang ingin Anda proses lebih lanjut menggunakan API PG-1. Anda memperoleh akan trx-id melalui IPN PG-1, sesaat setelah pembayaran dilakukan oleh pembeli. ts Parameter ini berisi waktu saat Anda mengirimkan request API PG-1. Waktu ditentukan menggunakan zona waktu GMT (Greenwich Mean Time), dan format ISO 8601 (Contoh: 2012-11-10T23:59:59Z) - 27 -
Respon dari API PG-1 akan berupa JSON string, dimana didalamnya akan terdapat attribut ”success” yang berisikan nilai true atau false, yang menandakan apakah request API berhasil dieksekusi atau tidak. Contoh Respon API: {"description":
"The
Payment
Transaction
has
been
approved
successfully", "success": true, "version": "1.0"}
CARA MEMBUAT REQUEST SIGNATURE Isi dengan signature yang di-generate menggunakan kombinasi API Secret Key dengan parameter request yang akan dikirimkan. Berikut ini algoritma yang dapat digunakan untuk membuat Request Signature (dalam bahasa pemrograman PHP): i. Tentukan parameter yang ingin dikirim untuk pemanggilan API. $param['merchant'] = '
[email protected]'; $param['store-id'] = '100000'; $param['trx-id'] = 'K9SKD242-028SNBAS-CS0A82J1-8852HS02'; $param['ts'] = '2011-09-09T01:02:16Z';
ii. Urutkan data parameter berdasarkan nama parameternya secara ascending (a-z) berdasarkan nama parameter. uksort($param, 'strnatcmp');
iii. Format parameter menjadi bentuk URL dimana setiap parameter dipisah dengan karakter & dan baik nama parameter dan nilainya di-encode sesuai format RFC 3986. foreach ($param as $k => $v) { $v = trim($v); if($url != '') $url .= '&'; $url .= rawurlencode($k).'='.rawurlencode($v); }
iv. Buat signature dengan menggunakan algoritma encoding base64 dan sha256 hash untuk url request (RFC 3986) dan API Secret Key. $secret = '3qyDv3MZ1gqXM5kes6766TW2daS8u8ZKevKfKbdQ'; $signature = rawurlencode(base64_encode(hash_hmac('sha256',$url, $secret,true)));
- 28 -
MELAKUKAN PEMANGGILAN API PG-1 Kami sudah menyiapkan library untuk beberapa bahasa pemrograman yang dapat Anda gunakan (dokumentasi dan cara penggunaan disertakan). Anda dapat mendownload API PG-1 library di: http://www.payglobalone.com/downloads/pg1-library-2.0.zip
DAFTAR API PG-1 Berikut ini daftar beberapa API PG-1 yang dapat Anda akses: Approve Payment API ini digunakan untuk melakukan approval terhadap transaksi pembayaran dari pembeli. URL Akses: https://secure.payglobalone.com/api/v1/approve-payment.act Basic Authentication: API Access Key & Request Signature Parameter: o merchant Email utama akun merchant PG-1 Anda o store-id ID Toko yang terhubung dengan API Access Key o trx-id ID Transaksi PG-1 yang ingin di-approve o ts Waktu pengiriman request dengan zona GMT dan format ISO 8601 Contoh Respon Berhasil: {"description":"Payment Transaction has been approved successfully", "success":true, "version":"1.0"}
Reject Payment API ini digunakan untuk melakukan penolakan/rejection terhadap transaki pembayaran dari pembeli (misalnya karena ketidaktersediaan stok, dll).
- 29 -
URL Akses: https://secure.payglobalone.com/api/v1/reject-payment.act Basic Authentication: API Access Key & Request Signature Parameter: o merchant Email utama akun merchant PG-1 Anda o store-id ID Toko yang terhubung dengan API Access Key o trx-id ID Transaksi PG-1 yang ingin di-reject o ts Waktu pengiriman request dengan zona GMT dan format ISO 8601 Contoh Respon Berhasil: {"description":"Payment Transaction has been rejected successfully", "success":true, "version":"1.0"}
Refund Payment API ini digunakan untuk mengembalikan sebagian dari total nilai transaksi pembayaran kepada pembeli. URL Akses: https://secure.payglobalone.com/api/v1/refund-payment.act Basic Authentication: API Access Key & Request Signature Parameter: o merchant Email utama akun merchant PG-1 Anda o store-id ID Toko yang terhubung dengan API Access Key o trx-id ID Transaksi PG-1 yang ingin di-refund. Status dari transaksi terkait harus berada pada posisi Confirmed (BELUM di Approve/Reject)
- 30 -
o description Alasan pengembalian sebagian pembayaran. Isi dari parameter ini akan ditampilkan pada histori transaksi pembeli. o amount Nilai Gollar yang akan dikembalikan kepada pembeli. Isi dari parameter ini tidak dapat melebihi nilai pembayaran yang tersisa. o ts Waktu pengiriman request dengan zona GMT dan format ISO 8601 Contoh Respon Berhasil: {"description":"Payment
Refund
has
been
processed
successfully",
"success":true, "version":"1.0"}
Check Payment API ini digunakan untuk mendapatkan status dan informasi untuk transaksi pembayaran terkait. URL Akses: https://secure.payglobalone.com/api/v1/check-payment.act Basic Authentication: API Access Key & Request Signature Parameter: o merchant Email utama akun merchant PG-1 Anda o store-id ID Toko yang terhubung dengan API Access Key o trx-id ID Transaksi PG-1 yang ingin di-cek o ts Waktu pengiriman request dengan zona GMT dan format ISO 8601 Contoh Respon Berhasil: {"trx-status":"approved/rejected/confirmed", "original-amount":71000, "fee":2000, "received-amount":69000, "success":true,"version":"1.0"}
- 31 -
Split Payment API ini digunakan untuk membagikan pembayaran yang diterima dari pembeli, ke member-member PG-1 lainnya. Fitur ini akan bermanfaat untuk meng-otomasi pembayaran untuk pihak ke-3 (misalnya: pembayaran komisi, pembayaran ongkos kirim ke kurir, pembayaran ke vendor, dll). URL Akses: https://secure.payglobalone.com/api/v1/split-payment.act Basic Authentication: API Access Key & Request Signature Parameter: o merchant Email utama akun merchant PG-1 Anda o store-id ID Toko yang terhubung dengan API Access Key o trx-id ID Transaksi PG-1 yang ingin di-split. Status transaksi harus Approved dahulu sebelum dapat di-split. o target (dapat muncul lebih dari 1 kali) Parameter ini berisi string dengan format JSON, dengan attribut sbb: target Email utama akun PG-1 yang akan menerima pembagian pembayaran description Deskripsi/keterangan terkait dengan pembagian pembayaran. Informasi ini akan ditampilkan pada histori transaksi penerima type Jenis pembagian pembayaran. Diisi dengan nilai: gollar atau reward. Pembagian pembayaran akan masuk ke saldo Gollar/Reward penerima sesuai dengan jenis yang ditentukan pada parameter ini.
- 32 -
amount Sebagian nilai dari pembayaran yang ingin dibagikan kepada penerima. Contoh: {"target":
"
[email protected]",
"description":
"Commission
1", "type": "gollar", "amount": 2000}
o ts Waktu pengiriman request dengan zona GMT dan format ISO 8601 Contoh Respon Berhasil: {"description":"Payment
Split
has
been
processed
successfully",
"success":true, "version":"1.0"}
Batch Process Dalam kasus tertentu Anda akan membutuhkan eksekusi beberapa API sekaligus dalam satu kali pemanggilan, dimana jika salah satu API gagal dieksekusi, maka secara otomatis API lainnya akan dibatalkan (TIDAK akan ada perubahan yang dijalankan). URL Akses: https://secure.payglobalone.com/api/v1/batch-process.act Basic Authentication: API Access Key & Request Signature Parameter: o merchant Email utama akun merchant PG-1 Anda o store-id ID Toko yang terhubung dengan API Access Key o action (dapat muncul lebih dari 1 kali) Parameter ini berisi string dengan format JSON, dengan attribut sbb: action Berisikan jenis action yang ingin dilakukan. Nilai yang valid antara lain: approve, reject, refund, split.
- 33 -
Parameter API terkait Diisi dengan parameter yang dibutuhkan untuk masing-masing api (selain parameter: merchant, store-id, dan ts) dalam format JSON. Contoh: {"action":
"approve",
"trx-id":
"K9SKD242-028SNBAS-
CS0A82J1-8852HS02"}
o ts Waktu pengiriman request dengan zona GMT dan format ISO 8601 Contoh Respon Berhasil: {"description":
"Batch
Actions
has
"success": true, "version": "1.0"}
- 34 -
been
processed
successfully",
