Dokumentasi API Payment Transaksi

Api payment adalah jalur utama yang di gunakan untuk mengelolah sistem pembayaran dan menjembatani antara user dengan payment gateway. Dengan menggunakan REST API ini semua aplikasi yang tidak terpasang pada sistem bisa menyingkronisasikan sendiri sistem pembayaran lisensi kode mereka.

Sebelum masuk ke tahap transaksi, anda harus memahami tujuan dan kegunaan API Payment. Api payment di buat dengan tujuan untuk melakukan tindakan otomatis tanpa keterlibatan manusia. Kegiatan otomatis tersebut meliputi pembuatan invoice tagihan, periksa pembayaran, memberikan laporan pembayaran sukses, menggenerate lisensi kode dengan batas waktu yang di tentukan, dan mampu memberikann informasi mengenai kapan lisensi berakhir.

aplikasi ini bisa di akses dengan method parameter POST. Dengan rest api /gets/payment?tindakan=AKSI dengan parameter aksi URL seperti pada tabel di bawah ini. Host default saat ini hanya https://ryanid.my.id

Nilai Aksi	Method	Kegunaan
kode_bank	GET	Mendapatkan kode bank untuk pembayaran
cek_lisensi	GET	Permintaan cek Lisensi
buat_tagihan	GET	Membuat invoice untuk pembayaran
cek_fee	GET	Menghitung Fee Gateway

Membuat sebuah fungsi cURL yang akan di gunakan untuk berkomunikasi dengan server RyanID. Berikut ini kodenya, kode ini harus di sertakan pada setiap program yang menjalankan perintah komunikasi dengan protokol HTTP.

function req_url($url, $data=null, $referer=null){
$ag = 'Mozilla/5.0 (Linux; Android 7.1.2; Redmi 5A Build/N2G47H; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/64.0.3282.137 Mobile Safari/537.36';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_USERAGENT, $ag);

if ($data){
curl_setopt($ch, CURLOPT_POST, true);
$headers = array("Content-Type: application/x-www-form-urlencoded");
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
}


if ($referer){
curl_setopt($ch, CURLOPT_REFERER, $referer);
} else {
curl_setopt($ch, CURLOPT_REFERER,"https://".$_SERVER['HTTP_HOST']);
}
$rest= curl_exec ($ch);
curl_close ($ch);
return $rest;
}

Ini tidak tersedia secara publik, hanya tersedia untuk aplikasi internal saja. Anda akan mendapati error seperti ini jika di akses tanpa otorisasi. Jadi server harus mencatat whitelist ip yang di gunakan dalam berkomunikasi.

{
    "hasil": "error",
    "alasan": "Alamat ip anda 182.1.231.235 harus di tambahkan dalam whitelis dulu."
}

Mendapatkan kode Bank

Kode bank di gunakan sebagai identifikasi jenis pembayaran yang ingin di gunakan untuk membayar tagihan. Kode ini sangat penting, oleh karena itu sebelum membuat permintaan tagihan anda harus mengambil data berupa kode bank. Pengambilan gunakan HTTP/GET 2.0 dengan parameter di atas menjadi /gets/payment?tindakan=kode_bank

{"MYBVA":"Maybank Virtual Account","PERMATAVA":"Permata Virtual Account","BNIVA":"BNI Virtual Account","BRIVA":"BRI Virtual Account","MANDIRIVA":"Mandiri Virtual Account","SMSVA":"Sinarmas Virtual Account","MUAMALATVA":"Muamalat Virtual Account","CIMBVA":"CIMB Virtual Account","SAMPOERNAVA":"Sahabat Sampoerna Virtual Account","ALFAMART":"Alfamart","ALFAMIDI":"Alfamidi","QRISC":"QRIS (Customizable)"}

Rest Api menghasilkan data dalam format JSON, data di atas merupakan array key. Dalam proses nya key di butuhkan untuk membuat tagian invoice baru, sedangkan value merupakan deskripsi hanya untuk di tampilkan kepada konsumen. Sehingga konsumen bisa memahami mau pilih metode pembayaran apa.

Membuat sebuah INVOICE untuk membayar lisensi

Sebelum lisensi di terbitkan aplikasi pelanggan harus membuat sebuah invoice, invoice adalah sebuah data identifiksi pembayaran yang di buat berdasarkann data masukan. Ada beberapa parameter yang harus di penuhi sebelum melakukann pembuatan invoice. Parameter ini harus di penuhi agar sistem bisa membuat permintaan ke Gateway.

Gateway atau payment gateway adalah pihak ketiga yang membantu melakukan otomatisasi pembayaran dengan layanan perbankan. Berikut ini adalah contoh susunan kode permintaan untuk menggenerate tagihan secara otomatis. HTTP/POST 2.0 /gets/payment?tindakan=buat_tagihan

Parameter	Opsi	Nilai
nama	Wajib	Nama lengkap pelangan
email	Wajib	Alamat Email lengkap pelanggan
hp	Wajib	Nomor HP pelanggan
harga	Opsional	Harga paket lisensi, default 50000
bank	Wajib	Kode key dari kode_bank
return_url	Wajib	HTTP URL redirect setelah payment
callback	Wajib	HTTP URL kami akan mengirim data json

$return_url = "https://aplikasi.com/bayar/sukses";
$host = "/gets/payment?tindakan=buat_tagihan";
$data = "item_name=BerlanggananServer&nama=Ryan&[email protected]&hp=08515844xxxx&bank=ALFAMART&return_url=".$return_url;
$hasil = req_url($host, $data); echo $hasil;

{
    "hasil": "sukses",
    "invoice_license": "APITG1670383858",
    "exp_time": "1670512649",
    "photo": null,
    "instruksi": "<p><b>Pembayaran via ALFAMART<\/b><\/p><p>1). Datang ke Alfamart<\/p>\n\n<p>2). Sampaikan ke kasir ingin melakukan pembayaran Plasamall<\/p>\n\n<p>3). Berikan kode bayar (<b>733512241979683<\/b>) ke kasir<\/p>\n\n<p>4). Bayar sesuai jumlah yang diinfokan oleh kasir<\/p>\n\n<p>5). Simpan struk bukti pembayaran Anda<\/p>\n\nSilakan datang ke kasir Alfamart terdekat di tempat anda, sampaikan ke kasir anda ingin membayar <u>Plasamall<\/u> dan berikan kode pembayaran dibawah ini:<br><br>\n\nKODE BAYAR :  <b>733512241979683<\/b><\/p>\n\n<i>Bayar Sebelum Rabu 07 Desember 2022, 09:51<\/i>",
    "telegram_msg": "Silakan datang ke kasir Alfamart terdekat di tempat anda, sampaikan ke kasir anda ingin membayar <u>Plasamall<\/u> dan berikan kode pembayaran dibawah ini:\n\nKODE BAYAR :  <b>733512241979683<\/b>\n\n<i>Bayar Sebelum Rabu 07 Desember 2022, 09:51<\/i>"
}

Simpan kode invoice lisensi di server anda, kode ini akan di generated sebagai lisensi aktif setelah anda melakukna pembayaran. Dan digunakan juga saat pengecekan lisensi secara manual.

Webhook dan cek lisensi manual

Setelah pembayaran berhasil kami akan menghubungi server anda dan mengirimkan data dalam format json melalui HTTP Header. Pastikan server anda bisa di akses lewat jaringan internet, jika server anda masih belum menerima informasi mengenai lisensi aktif anda bisa melakukan cek manual dengan Rest /gets/payment?tindakan=cek_lisensi

Berikut ini adalah data yang kami kirimkan melalui respon header setelah menerima pembayaran dari anda. Data ini merupakan sertifikat lisensi dan masa berlakunya, tidak ada kode rahasian di sini. Hanya ada kode validasi dan masa berlaku dari lisensi program anda.

Setelah Bayar maka server akan mengirim data ke URL callback

{
    "data": {
        "id": "13",
        "exp_time": "1672811891",
        "price": "60000",
        "code": "XXB3",
        "status": "berlaku",
        "dibuat": "2022-12-07"
    },
    "status": "Lisensi masih berlaku.",
    "validate": "ok"
}

Jika status pembayaran tidak di terima, gagal, atau tagihan kadaluarsa maka server kami akan mengirimkan ping berikut ini, status update nya bisa REFUND, FAILED

{"update": "REFUND", "invoice_license": "XXB3",}

Jika anda membutuhkan cek manual anda bisa melakukan permintaan data ke alamat cek lisensi. Dalam cek lisensi terdapat tanggal expired, pastikan sistem anda di buat untuk mengikuti tanggal expired tersebut. Berikut ini ada contoh untuk memeriksa lisensi.

$kode_lisensi = "EAA78B0IVBSCYQP";
$host = "/gets/payment?tindakan=cek_lisensi&code=".$kode_lisensi;
$hasil = req_url($host); echo $hasil;

{
    "data": {
        "id": "5",
        "exp_time": "1672752884",
        "price": "50000",
        "code": "APITG1670295174",
        "status": "berlaku",
        "dibuat": "2022-12-06"
    },
    "status": "Lisensi masih berlaku.",
    "validate": "ok"
}

Dengan adanya dokumentasi ini semua aplikasi yang sudah ada bisa ikut menyesuakan sendiri dengan sistem pembayaran. Namun lisensi hanya bisa di generate oleh server payment, aplikasi tersebut msih tetap bisa membuat lisensi kode mereka sendiri jika program sistem nya di buat demikian.

Karena kode lisensi hanya berupa teks json. Tujuan penggunaan lisensi kode adalah untuk mengumpulkan pendanaan dari masing-masing pengguna atas dasar penggunaan sumber daya server yang di beli pada layanan pihak ketiga.

Adapun sumber daya yang kami maksud meliputi nama domain, biaya server, dan biaya maintenance. Untuk server penggunaan RAM, CPU, dan STORAGE nya tidak perlu di ragukan. Karena semua aplikasi yang berjalan di install pada server yang menggunakan sumber daya cukup besar 50% lebih besar dari kebutuhan.

Dengan menggunakan satu server sentral sehingga bisa menghemat biaya berlangganan. Kalau satu aplikasi menggunakan server mandiri sudah pasti biaya untuk sewa fasilitas server sangat besar.

Sementara itu 20% biaya operasional yang di bayarkan oleh pelanggan di gunakan untuk menggaji para stack developer serta teknisi IT yang bekerja menjaga server tetap berjalan 24 jam tanpa downtime. Sementara sisanya menjadi kredit 100% untuk membayar fasilitas server.

RyanID Tertarik pada teknologi, full stack developer at netzku.com