Bill Payment
Introduction
Fitur ini memungkinkan anda untuk dapat melakukan aktivitas pembelian / pembayaran tagihan seperti pulsa, PLN, PDAM, BPJS, dan lain-lain. Dalam proses, ESPAY menjadi pihak ketiga dimana menjadi perantara antara user (Merchant) dan Provider.
Authentication
Setiap request harus akan diverivikasi dengan cara basic auth, jadi pada setiap request yang dikirim harus menyertai header Authorization dengan value Basic diikuti dengan username dan password dengan format username:password yang telah di encode dengan Base64 Encoding
Contoh :
Username: Aladdin
Password: Smelana
Format sebelum di encode : Aladdin:Smelana
Hasil Base64 encoding :
QWxhZGRpbjpTbWVsYW5h
Header yang dikirim :
Authorization : Basic
QWxhZGRpbjpTbWVsYW5h
Setiap Authentication yang gagal akan menerima header http 401
Signature Validation
Semua request yang masuk ke system espay akan mengalami validasi Signature. Signature dikirim pada tiap request dengan parameter signature. Setiap signature akan dihash dengan menggunakan algoritma sha256. Signature akan dibuat dengan menggambungkan beberapa value dari parameter value sebelumnya serta dengan sebuah key yang diberikan oleh espay. Format penggambungan signature berbeda tiap service. setiap parameter akan dimulai,dipisahkan, dan diakhiri dengan tanda ##. Setelah digambungkan semua value harus dirubah menjadi uppercase. Urutan pengambungan signature adalah seperti berikut
- Service Bill Inquiry
- Sender id
- Order id
- Product code
- Rq uuid
- Key
(Bill Inquiry : ##sender_id##order_id##product_code##rq_uuid##key##)
- Service Bill Payment
- Sender id
- Order id
- Product code
- Amount
- Rq uuid
- Key
(Bill payment : ##sender_id##order_id##product_code##amount##rq_uuid##key##)
- Service Inquiry Bill Payment Status
- Sender id
- Referensi ID
- Rq uuid
- Key
- Service Get Balance
- Sender ID
- Rq uuid
- Key
Contoh genarete signature
Format awal
##SGOPLUS##142921023##STCKAI##sgoplus201711aa##keyforsignature##
Dirubah ke uppercase
##SGOPLUS##142921023##STCKAI##SGOPLUS201711AA##KEYFORSIGNATURE##
Kemudian di has dengan algortitma sha256 menjadi
6767aa419fe1fbf8f8896c7a0857b5cea41a7e4f407262f0fc82a914137a9401
IP Whitelist Registration
Bill Inquiry & Bill Payment
- Bill Inquiry
Bill Inquiry dilakukan melalui webservice dengan menggunakan protokol REST. Client akan mengirimkan sejumlah nilai atau parameter dalam bentuk HTTP POST ke biller dengan tujuan untuk melakukan inquiry transaksi atau mendapatkan data dari transaksi seperti jumlah yang harus dibayarkan atau detail transaksi lainnya.
API URL |
Development : https://sandbox-api.espay.id/rest/biller/inquirytransaction |
Production: https://api.espay.id/rest/biller/inquirytransaction |
Format message yang dikirimkan harus dalam bentuk URL encoded.
Keterangan untuk setiap field di dalamnya yaitu:
BILL INQUIRY REQUEST DATAName Field | Attribute | Mandatory | Keterangan |
rq_uuid | ANS 255 | Ya | Request Identifier. ID unik untuk mengidentifikasi request message tersebut dengan message lainnya.
Formula : sender_id + unique ID Contoh : SENDERID123ABC-DEF456 |
rq_datetime | ANS 19 | Ya | Tanggal dan waktu di server aplikasi client pada saat message di kirim.
Format : YYYY-MM-DD HH:MM:SS Contoh : 2014-12-17 12:30:45 |
sender_id | ANS 50 | Ya | Identitas unik client yang terdaftar di Espay. (Akan diberikan untuk masing client). |
password | ANS 3 | Ya | Password akses client yang terdaftar di Espay. (Akan ditentukan sesuai perjanjian). |
order_id | ANS 64 | Ya | ID Transaksi. Bisa berupa nomor handphone, nomor kartu kredit, customer id, dll. |
product_code | ANS 16 | Ya | Kode produk yg disupport. Lihat table Daftar Produk. |
additional_data | ANS 999 | Tidak | Data pendukung yang diperlukan untuk produk tertentu dalam format JSON. Detailnya dapat dilihat di halaman Bill Inquiry dan Bill Payment additional data |
signature | ANS 999 | Ya | Signature |
Setelah melakukan request dengan contoh diatas, client akan mendapatkan response dari biller seperti pada dibawah ini :
- BILL INQUIRY RESPONSE DATA
Nama Field | Attribute | Mandatory | Keterangan |
rq_uuid | ANS 255 | Ya | Request Identifier. ID unik untuk mengidentifikasi message tersebut dengan message lainnya.
Formula : sender_id + unique ID Contoh : SENDERID123ABC-DEF456 |
rs_datetime | ANS 19 | Ya | Tanggal dan waktu di server aplikasi server pada saat response message di kirim
Format : YYYY-MM-DD HH:MM:SS Contoh : 2014-12-17 12:30:45 |
error_code | ANS 4 | Ya | Kode kesalahan. 0000 = Sukses, selain itu gagal. |
error_desc | ANS 128 | Ya | Deskripsi kesalahan jika ada |
order_id | ANS 64 | Ya | ID Transaksi. Bisa berupa nomor handphone, nomor kartu kredit, customer id, dll. |
amount | NUM 17 | Ya | Jumlah yang harus dibayar. Terdapat default 2 digit desimal. Contoh : 10000000 = 100.000,00 |
bill_amount | NUM 17 | Tidak | Jumlah yang harus dibayar sebelum ditambahkan admin_fee. Terdapat default 2 digit desimal. Contoh : 10000000 = 100.000,00 |
admin_fee | NUM 17 | Tidak | Biaya admin fee jika ada. Terdapat default 2 digit desimal. Contoh : 10000000 = 100.000,00 |
description | ANS 128 | Tidak | Keterangan transaksi |
data | ANS 999 | Ya | Detail data transaksi dari biller dalam format JSON. Data ini dinamis berdasarkan produk yang di inquiry. Detailnya dapat dilihat di halaman Bill Inquiry dan Bill Payment data |
- Bill Payment
Bill Payment dilakukan melalui webservice dengan menggunakan protokol REST. Client mengirimkan sejumlah nilai atau parameter dalam bentuk HTTP POST ke biller dengan tujuan untuk memberikan payment notifikasi kepada biller bahwa telah terjadi transfer sejumlah amount ke rekening biller tersebut sebagai bentuk pembayaran / pembelian / transaksi yang dilakukan oleh client
API URL |
Development : https://sandbox-api.espay.id/rest/biller/paymentreport |
Production: https://api.espay.id/rest/biller/paymentreport |
Format message yang dikirimkan harus dalam bentuk URL encoded.
Keterangan untuk setiap field didalamnya yaitu:
BILL PAYMENT REQUEST DATANama Field | Attribute | Mandatory | Keterangan |
rq_uuid | ANS 255 | Ya | Request Identifier. ID unik untuk mengidentifikasi request message tersebut dengan message lainnya. Formula : sender_id + unique ID Contoh : SENDERID123ABC-DEF456 |
rq_datetime | ANS 19 | Ya | Tanggal dan waktu di server aplikasi client pada saat message di kirim. Format : YYYY-MM-DD HH:MM:SS Contoh : 2014-12-17 12:30:45 |
sender_id | ANS 50 | Ya | Identitas unik client yang terdaftar di Espay. (Akan diberikan untuk masing client). |
channel_code | ANS 32 | Tidak | Code channel yang digunakan oleh client, sebagai pembeda aplikasi client |
password | ANS 32 | Ya | Password akses client yang terdaftar di Espay. (Akan ditentukan sesuai perjanjian). |
order_id | ANS 64 | Ya | ID Transaksi. Bisa berupa nomor handphone, nomor kartu kredit, customer id, dll. |
product_code | ANS 16 | Ya | Kode produk yg disupport. Lihat table Daftar Produk. |
amount | NUM 17 | Ya | Jumlah yang harus dibayar atau didebet. Terdapat 2 digit decimal. Contoh : 35000000 = 350.000,00 |
data | ANS 999 | Ya | Detail data transaksi dari biller dalam format JSON. Sesuai dengan hasil inquiry (jika ada). Detailnya dapat dilihat di halaman Bill Inquiry dan Bill Payment data |
additional_data | ANS 999 | Tidak | Data pendukung yang diperlukan untuk produk tertentu dalam format JSON. Detailnya dapat dilihat di halaman Bill Inquiry dan Bill Payment additional data |
signature | ANS 999 | Ya | Signature |
Setelah melakukan request dengan contoh diatas, client akan mendapatkan response dari biller seperti pada dibawah ini:
BILL PAYMENT RESPONSE DATANama Field | Attribute | Mandatory | Keterangan |
rq_uuid | ANS 255 | Ya | Request Identifier. ID unik untuk mengidentifikasi message tersebut dengan message lainnya. Formula : sender_id + unique ID Contoh : SENDERID123ABC-DEF456 |
rs_datetime | ANS 19 | Ya | Tanggal dan waktu di server aplikasi server pada saat response message di kirim Format : YYYY-MM-DD HH:MM:SS Contoh : 2014-12-17 12:30:45 |
error_code | ANS 4 | Ya | Kode kesalahan. 0000 = Sukses, selain itu gagal |
error_desc | ANS 128 | Tidak | Deskripsi kesalahan jika ada |
order_id | ANS 64 | Ya | ID Transaksi. Bisa berupa nomor handphone, nomor kartu kredit, customer id, dll |
description | ANS 128 | Tidak | Keterangan transaksi |
data | ANS 999 | Ya | Detail data transaksi yang telah dibayar dari biller dalam format JSON. Detailnya dapat dilihat di halaman Bill Inquiry dan Bill Payment data |
Inqury Bill Payment Status
Dilakukan melalui webservice dengan protokol REST. Client mengirimkan sejumlah nilai/parameter dalam bentuk HTTP POST ke sistem ESPAY untuk mendapatkan transaksi yang telah selesai.
API URL
Development : https://sandbox-api.espay.id/rest/billertools/gettransactioninfo
Production: https://api.espay.id/rest/billertools/gettransactioninfo
Format message yang dikirimkan harus dalam bentuk URL encoded. Keterangan untuk setiap field dalam HTTP POST message tersebut:
Get Payment Status Request Data:Nama Field | Attribute | Mandatory | Keterangan |
rq_uuid | ANS 255 | Ya | Request Identifier. ID unik untuk mengidentifikasi request message tersebut dengan message lainnya. Formula : sender_id+ Unique ID Contoh: ESPAY123ABC-456DEF |
rq_datetime | ANS 19 | Ya | Tanggal dan waktu di server aplikasi client pada saat message di kirim. Format : YYYY-MM-DD HH:MM:SS Contoh: 2017-12-17 12:22:32 |
sender_id | AN...32 | Ya | Identitas unik client yang terdaftar di Espay. (Akan diberikan untuk masing client) |
password | AN...32 | Ya | Password akses client yang terdaftar di Espay. (Akan ditentukan sesuai perjanjian) |
signature | ANs...128 | Ya | Signature |
ref_id | AN...32 | Ya | Referensi ID yang didapatkan di Bill Payment API |
Setelah melakukan request dengan contoh diatas, client akan mendapatkan response. Dengan contoh sebagai berikut :
Get Payment Status Response Data:Nama Field | Attribute | Mandatory | Keterangan |
rq_uuid | ANS 255 | Ya | Request Identifier. ID unik untuk mengidentifikasi request message tersebut dengan message lainnya. Formula : sender_id+ Unique ID Contoh: ESPAY123ABC-456DEF |
rq_datetime | ANS 19 | Ya | Tanggal dan waktu di server aplikasi client pada saat message di kirim. Format : YYYY-MM-DD HH:MM:SS Contoh: 2017-12-17 12:22:32 |
error_code | ANS...4 | Ya | Error Code(lihat Tabel Error) |
error_desc | AN...32 | Ya | Keterangan Error |
product_code | ANs...16 | Tidak | Kode produk |
order_id | AN...64 | Tidak | Order ID / Payment ID |
Get Biller Products
Get Biller Products dilakukan melalui webservice dengan menggunakan protokol REST. Client akan mengirimkan sejumlah nilai/parameter dalam bentuk HTTP POST untuk mendapatkan daftar produk yang disupport.
API URL |
Development : https://sandbox-api.espay.id/rest/billertools/getregisteredproducts |
Production : https://api.espay.id/rest/billertools/getregisteredproducts |
Format message yang dikirimkan harus dalam bentuk URL encoded. Keterangan untuk setiap field dalam HTTP POST message tersebut:
Get Biller Product Request Data:Nama Field | Attribute | Mandatory | Keterangan |
rq_uuid | ANS 255 | Ya | Request Identifier. ID unik untuk mengidentifikasi request message tersebut dengan message lainnya. |
rq_datetime | ANS 19 | Ya | Tanggal dan waktu di server aplikasi client pada saat message di kirim. Format : YYYY-MM-DD HH:MM:SS Ex : 2014-12-17 12:30:45 |
sender_id | AN 32 | Ya | Identitas unik client yang terdaftar di Espay. (Akan diberikan untuk masing client) |
password | AN 32 | Ya | Password akses client yang terdaftar di Espay. (Akan ditentukan sesuai perjanjian)) |
Setelah melakukan request dengan contoh diatas, client akan mendapatkan response JSON dari biller. Dengan contoh sebagai berikut :
Get Biller Product Response Data:Nama Field | Attribute | Mandatory | Keterangan |
rq_uuid | ANS 255 | Ya | Request Identifier. ID unik untuk mengidentifikasi request message tersebut dengan message lainnya. |
rq_datetime | ANS 19 | Ya | Tanggal dan waktu di server aplikasi client pada saat message di kirim. Format : YYYY-MM-DD HH:MM:SS Ex : 2014-12-17 12:30:45 |
error_code | ANS 4 | Ya | Kode kesalahan. 0000 = Sukses, selain itu gagal. |
error_desc | ANS 128 | Tidak | Deskripsi kesalahan jika ada. |
product | ANs 16 | Tidak | Produk yang di support. Lihat table daftar produk |
Get Balance
Get Balance dilakukan melalui webservice dengan menggunakan protokol REST. Client akan mengirimkan sejumlah nilai/parameter dalam bentuk HTTP POST untuk mendapatkan informasi saldo.
API URL |
Development : https://sandbox-api.espay.id/rest/billertools/getbalance |
Production : https://api.espay.id/rest/billertools/getbalance |
Format message yang dikirimkan harus dalam bentuk URL encoded. Keterangan untuk setiap field dalam HTTP POST message tersebut:
Get Balance Request Data:Nama Field | Attribute | Mandatory | Keterangan |
rq_uuid | ANS 255 | Ya | Request Identifier. ID unik untuk mengidentifikasi request message tersebut dengan message lainnya. |
rq_datetime | ANS 19 | Ya | Tanggal dan waktu di server aplikasi client pada saat message di kirim. Format : YYYY-MM-DD HH:MM:SS Ex : 2014-12-17 12:30:45 |
sender_id | AN 32 | Ya | Identitas unik client yang terdaftar di Espay. (Akan diberikan untuk masing client) |
password | AN 32 | Ya | Password akses client yang terdaftar di Espay. (Akan ditentukan sesuai perjanjian) |
signature | AN 32 | Ya | Signature diperlukan untuk validasi oleh penjual |
Setelah melakukan request dengan contoh diatas, client akan mendapatkan response JSON dari biller. Dengan contoh sebagai berikut :
Get Balance Response Data:Nama Field | Attribute | Mandatory | Keterangan |
rq_uuid | ANS 255 | Ya | Request Identifier. ID unik untuk mengidentifikasi message tersebut dengan message lainnya. Formula : sender_id + unique ID Contoh : SENDERID123ABC-DEF456 |
rs_datetime | ANS 19 | Ya | Tanggal dan waktu di server aplikasi server pada saat response message di kirim Format : YYYY-MM-DD HH:MM:SS Contoh : 2014-12-17 12:30:45 |
error_code | ANS 4 | Ya | Kode kesalahan. 0000 = Sukses, selain itu gagal |
error_desc | ANS 128 | Tidak | Deskripsi kesalahan jika ada |
balance | Total saldo yang ada pada akun |
Get Provider Phone Number
Get Provider Phone Number dilakukan melalui webservice dengan menggunakan protokol REST. Client akan mengirimkan sejumlah nilai/parameter dalam bentuk HTTP POST untuk mendapatkan informasi provider.
API URL |
Development : hhttps://sandbox-api.espay.id/rest/billertools/getmno |
Production : https://api.espay.id/rest/billertools/getmno |
Format message yang dikirimkan harus dalam bentuk URL encoded. Keterangan untuk setiap field dalam HTTP POST message tersebut:
et Provider Phone Number Request Data:Nama Field | Attribute | Mandatory | Keterangan |
rq_uuid | ANS 255 | Ya | Request Identifier. ID unik untuk mengidentifikasi request message tersebut dengan message lainnya. |
rq_datetime | ANS 19 | Ya | Tanggal dan waktu di server aplikasi client pada saat message di kirim. Format : YYYY-MM-DD HH:MM:SS Ex : 2014-12-17 12:30:45 |
sender_id | AN 32 | Ya | Identitas unik client yang terdaftar di Espay. (Akan diberikan untuk masing client) |
password | AN 32 | Ya | Password akses client yang terdaftar di Espay. (Akan ditentukan sesuai perjanjian) |
phone_num | AN 15 | Ya | Nomor handphone Contoh: +6281284620888 / 6281284620888 / 081284620888 |
Setelah melakukan request dengan contoh diatas, client akan mendapatkan response. Dengan contoh sebagai berikut :
Get Provider Phone Number Response Data:Nama Field | Attribute | Mandatory | Keterangan |
rq_uuid | ANS 255 | Ya | Request Identifier. ID unik untuk mengidentifikasi message tersebut dengan message lainnya. Formula : sender_id + unique ID Contoh : SENDERID123ABC-DEF456 |
rs_datetime | ANS 19 | Ya | Tanggal dan waktu di server aplikasi server pada saat response message di kirim Format : YYYY-MM-DD HH:MM:SS Contoh : 2014-12-17 12:30:45 |
error_code | ANS 4 | Ya | Kode kesalahan. 0000 = Sukses, selain itu gagal |
error_desc | ANS 128 | Tidak | Deskripsi kesalahan jika ada |
operator | Detail operator yang dituju |
Table Error
Response Code | Description |
0000 | COMPLETED SUCCESFULLY |
9999 | SUSPECT / TIMEOUT |
802 | MAX/MIN PAYMENT AMOUNT EXCEEDED |
801 | TRANSACTION ERROR, INQUIRY DATA NOT FOUND |
800 | INSUFFICIENT FUNDS |
614 | TIDAK DAPAT MELAKUKAN TRANSAKSI PADA PUKUL TERTENTU |
612 | UNABLE TO PROCESS TRANSACTION, PLEASE TRY AGAIN LATER |
611 | TRANSACTION DECLINE, PLEASE CONTACT YOUR ADMINISTRATOR |
610 | ANDA BISA MELAKUKAN TRANSAKSI YANG SAMA SETELAH 5 MENIT |
601 | IP ADDRESS REJECTED / UNREGISTERED |
406 | INQUIRY DATA IS INVALID |
405 | PRODUCT DENIED |
404 | PRODUCT NOT AVAILABLE |
403 | AMOUNT IS NOT SET |
300 | INQUIRY NOT AVAILABLE |
210 | DUPLICATE UUID |
205 | INVALID REQUEST |
040 | BILLER SYSTEM MALFUNCTION |
09 | REQUEST IN PROGRESS |
13 | TXN AMT IS DIFFER WITH TOTAL BILL AMT |
14 | PAYMENT NBR NOT FOUND |
15 | NO SUCH ISSUER |
17 | SERVICE UNAVAILABLE (MAINTENANCE) |
18 | DISPUTE |
22 | SUSPECTED MALFUNCTION |
34 | SUSPECTED FRAUD |
36 | RESTRICTED |
60 | CARD ACCEPTOR CONTACT ACQUIRER |
61 | TRANSACTION EXCEEDS APPROVAL AMOUNT LIMIT |
64 | ORIGINAL AMOUNT INCORRECT |
65 | EXCEED FREQUENCY LIMIT |
66 | CARD ACCEPTOR, CALL ACQUIRER SECURITY |
67 | HOT CARD RETAIN CARD |
68 | LATE RESPONSE FROM BILLER |
72 | VOUCHER / DENOM NOT AVAILABLE |