dokumen api sistem pembayaran · 2020. 10. 15. · 1 catatan revisi versi dokumen tanggal perubahan...

Dokumen API Sistem Pembayaran

1

Catatan Revisi

Versi Dokumen Tanggal

Perubahan

Deskripsi Perubahan

1.0.1 2020-08-21 1. Jenis angka diubah menjadi decimal (12,2)

2. Aturan enkripsi tanda tangan data diubah dari MD5

menjadi AES

1.0.2 2020-09-02 1. Aturan enkripsi tanda tangan data diubah dari AES

menjadi HEX

1.0.3 2020-10-12 1. Aturan enkripsi tanda tangan data diubah dari HEX

menjadi SHA256

2

1. Ikhtisar Dokumen

1.1. Pengantar

1.2. Target Audience

Target utama pembaca dokumen ini adalah implementor teknis merchant. Sebagian konten

juga dapat menjadi rujukan untuk pihak manajemen dan maupun operasional merchant.

1.3. Rule Definition

1.3.1. Payment Type

Jenis Pembayaran Kode

Kartu Kredit (Mendukung Refund) CreditCard

Internet Banking InternetBanking

Virtual Account MaybankVA,

BTNVA,BNIVA,CIMBVA,PermataVA

Convenience Store ConvenienceStore,INDOStore

DANA(Mendukung refund) DANAWALLET

OVO (Pada saat pembayaran, pengguna perlu

mengakses App OVO untuk melakukan

transaksi pembayaran. )

OVOWALLET

AKULAKU AKULAKUWALLET

DOKU DOKUWALLET

SMS payment(HCPT adalah TRI) TELKOMSEL_M,HCPT,XL,INDOSAT

Catatan:

1. Kode ConvenienceStore merujuk ke Alfamart.

2. Link H5 disediakan oleh DANA Wallet. Ada kemungkinan ketidakcocokan dengan sistem

Android. Jika ada masalah, silahkan hubungi tim teknis kami, mereka dapat memberikan

code penyesuaian.

3

1.3.2. Satuan Uang

Nominal angka dalam satuan Rupiah, dengan dua angka desimal dipisah dengan titik seperti

10.25

1.3.3. Cara Mengenkripsi

1. Penggabungan Data:

Asumsi seluruh data yang akan di-submit dan diterima disebut Dataset M. Nama parameter

dari Dataset M disortir dari kecil ke besar (aturan sortir karakter), disusun menjadi parameter

URL yang valid (seperti key1=value1&key2=value2...) kemudian digabung menjadi sebuah

string yang bernama StringA.

Perlu diketahui beberapa aturan berikut:

⚫ Nama parameter diurut dari kecil ke besar (disortir berdasarkan karakter ASCII)

⚫ Apabila nilai dari parameter kosong, maka tidak perlu ikut dienkripsi.

⚫ Di dalam string awal (stringA), apabila nama parameter dan nilai parameter menggunakan

data original, maka tidak perlu dilakukan URL Encode.

⚫ Nilai signature dari respon sistem tidak menyertakan sign dalam proses enkripsi. Nilai

enkripsi yang dihasilkan perlu dicocokkan dengan nilai sign.

2. Enkripsi Data

Pada stringContent dipasangkan dengan key akan mendapatkan string bernama

stringSignTemp . Kemudian lakukan operasi enkripsi SHA256 pada stringSignTemp untuk

mendapatkan nilai Tanda signValue .

3. Contoh

Asumsi berikut adalah format data yang akan di-submit:

{

"amount":"100.00",

"mchId":"0010001",

"mobilePhone":"16666666666",

"outTradeNo":"1562129320015",

"channel":"CreditCard",

"notifyUrl":"https://www.google.com",

"tradeType":"pay.submit",

"email":"[email protected]"

}

4

Langkah 1: Ubah format di atas menjadi pasangan key=value, kemudian sortir berdasarkan

nama parameter secara ASCII sehingga menjadi begini:

stringA="amount=100.00&channel=CreditCard&[email protected]&mchId=0010001&

mobilePhone=16666666666&notifyUrl=https://www.google.com&outTradeNo=1562129320

015&tradeType=pay.submit&";

Langkah 2: Gabungkan API key：

stringSignTemp="stringA&key=192006250b4c09247ec02edce69f6a2d"

sign=DigestUtils.sha256Hex(stringSignTemp)="5f5cbc684f9b1b86428fe575b9a9412e4caf2055

13c54be807e6423e1d63c99b"

Hasil akhir data adalah sebagai berikut：

{

"amount":"100",

"mchId":"0010001",

"mobilePhone":"16666666666",

"outTradeNo":"1562129320015",


"sign":"5f5cbc684f9b1b86428fe575b9a9412e4caf205513c54be807e6423e1d63c99b",


"tradeType":"pay.submit",

"email":"[email protected]"

}

2. Aturan Interaksi Data and Kerahasiaan

Data

Metode Submit Submit data dengan metode POST，pasangkan

Content-Type”application/json; charset=utf-8” pada form.

Format Baik data yang di-submit maupun diterima dalam format JSON

Encoding Karakter Diseragamkan dengan encoding karakter UTF-8

Format Nominal Jumlah dalam format rupiah Indonesia, dengan dua angka di belakang

koma.

Algoritma Signature SHA256

Syarat Signature

Perlu adanya verifikasi nilai pada signature pada saat me-request

maupun menerima data. Untuk info selengkapnya cek subbab Digital

Signature.

Logika Kondisional Pertama-tama cek kode return, baru cek return value, terakhir cek status

transaksi.

5

3. API Transaksi

3.1 Ordering Interface

3.1.1. Parameter Request

Nama Field Variabel Tipe Data Mandatori Deskripsi

Nomor

Merchant mchId String(20) Ya

Nomor unik untuk merchant

yang diberikan oleh Payment

Gateway

Nomor Versi version String(4) Ya 2.1 (di-hardcode “2.1”)

Metode

Pembayaran channel String(10) Ya Jenis pembayaran

Nomor Transaksi

Merchant outTradeNo String(50) Ya

Nomor order yang dibuat oleh

merchant. Bersifat unik di

dalam sistem merchant.

Jumlah Transfer amount decimal(12,2) Ya

Nominal dalam satuan rupiah,

dengan dua angka belakang

koma, dan desimal

menggunakan tanda titik.

Khusus VA payment,

jumlahnya tidak boleh lebih

rendah dari channel fee

merchant (biaya dalam

kontrak). Nilai transaksi Wallet

harus lebih dari IDR 100.

Jenis Transaksi tradeType String(20) Ya Di-hardcode “pay.submit”

Nomor Telepon mobilePhone String(20) Ya Nomor telepon pelanggan

Email email String(45) Ya Email

URL Notifikasi

Pembayaran notifyUrl String(200) Tidak

Setelah pembayaran selesai

maka akan kirim notifikasi ke

URL tersebut;

URL Callback callbackUrl String(200) Tidak

Ketika transaksi berhasil atau

gagal, sistem akan redirect ke

URL ini. Paylabs akan

menyertakan nomor transaksi

6

3.1.2. Parameter Respon

dari merchant ke dalam URL

seperti

callBackUrl?OrderNo=123456,

sehingga Merchant bisa query

transaksi dari nomor yang

diberikan.

Nama Pembayar payer String(60) Ya Nama orang yang melakukan

transaksi

Nama Produk goodsinfo String(100) Tidak Informasi Produk, diisi saat

nomor versi adalah 2.1

Signature sign String(32) Ya Silahkan merujuk ke “1.3.3

Cara Enkripsi”


Kode

Respon returnCode String(1) Ya 0：Sukses、1： Gagal

Deskripsi

Respon returnMsg String(128) Tidak

Penjelasan kode respon.

Penjelasan termasuk dalam

bahasa Mandarin.

Berikut adalah parameter yang muncul apabila returnCode bernilai 0

Link

pembayaran

atau Kode

Pembayaran

payCode String(200) Tidak

Selain jenis Kode Pembayaran,

seluruh jenis pembayaran

lainnya ada respon; Berikut

aturannya:

01： URL Pembayaran；

04： Format JSON dari

Payment channel atau Payment

Code

Nomor

Transaksi

Merchant

outTradeNo String(50) Ya


merchant. Maksimal 50

karakter, bisa mengandung

alfabet dan harus bersifat unik

di dalam sistem merchant.

Nomor

Transaksi

Platform

outChannelNo String(32) Tidak Nomor transaksi di platform

7

3.1.3. Contoh

Contoh Format Request：

{

"amount": "10000.00",

"mchId": "0010001",

"mobilePhone": "16666666666",

"outTradeNo": "1578982657657",

"channel": "MaybankVA",

"sign": "B6338203092F1BD0A9DAB651758EEACE",

"notifyUrl": "http://192.168.0.165:8080/trans/notify",

Waktu

Transaksi transTime String(16) Ya yyyyMMddHHmmss

Batas Waktu expiredTime String(16) Ya

yyyyMMddHHmmss

( Dikarenakan proses

sinkronisasi waktu dan jeda

polling, bisa terjadi perbedaan

waktu kadaluarsa dibandingkan

dengan waktu sesungguhnya.)

Nominal

Transfer amount decimal(12,2) Ya

Nominal transaksi dalam

satuan Rupiah, dengan dua

angka belakang koma, dan

desimal menggunakan titik.

Kode Error errCode String(32) Tidak Silahkan merujuk ke

“Lampiran Daftar Error.”

Deskripsi

Kode Error errCodeDes String(128) Tidak Deskripsi terkait kode error

Nomor

Merchant mchId String(20) Tidak Nomor Merchant

Jenis

Pembayaran payCodeWay String(2) Tidak

01：URL Pembayaran；

04：Format JSON untuk

Payment channel atau Payment

Code

Nama

Pembayar payBackName String(100) Tidak

Field ini akan muncul jika

request-nya menggunakan versi

2.2 dan payment_type diisi

“convenient store”

Signature sign String(32) Ya Signature, untuk detailnya lihat

cara enkripsi.

8

"callbackUrl": "https://www.google.com",

"payer": "Jack",

"version": "2.1",

"tradeType": "pay.submit",

"email": "[email protected]"

}

Contoh format respon：

{

"returnCode": "0",

"sign": "608229914A59CF67FD95C814A22D5A37",

"outTradeNo": "1578982657657",

"outChannelNo": "2020011400000017935",

"payCodeWay": "04",

"payCode": "7879600114000004",

"amount": 10000.00,

"transTime": "20200114131850",

"expiredTime": "20200115131850"

}

3.2 Transaksi Alamat H5

Kelebihan dari Transaksi dengan Alamat H5 adalah tidak perlunya programming untuk

membuat halaman pembayaran lagi. Paylabs menyediakan halaman pembayaran untuk menuntun

pembeli untuk menyelesaikan proses pembayarannya. Terkait query detail order, notifikasi

transaksi berhasil (notifyUrl), Url callback (callbackUrl), semuanya menggunakan metode yang

sama persis. Sehingga programmer bisa memilih salah satu caranya.

3.2.1 Parameter Respon

Ketika merchant mengirim suatu transaksi, panjang nomor transaksi harus sesuai dengan

petunjuk dokumen dan tidak melebihi batas.


Nomor




Gateway

Jenis

Pembayaran channel String(10) Tidak

Jenis pembayaran. Silahkan lihat

“Jenis Pembayaran”;

Jika dikosongkan maka akan

muncul halaman H5 agar

pembeli yang memilih jenis

pembayaran.

9


Nomor

Transaksi

Merchant

orderNo String(50) Ya

Nomor transaksi yang ada di

dalam sistem merchant. Bersifat

unik di dalam sistem merchant.

Jumlah

Transaksi amount decimal(12,2) Ya

Nominal dalam satuan rupiah,

dengan dua angka belakang

koma, dan desimal

menggunakan tanda titik.

Khusus VA payment, jumlahnya

tidak boleh lebih rendah dari

channel fee merchant (biaya

dalam kontrak). Nilai transaksi

Wallet harus lebih dari IDR 100.

Nomor

Telepon mobilePhone String(20) Ya Nomor handphone customer.

Nama Produk goodsInfo String(100) Ya Nama barang yang dibeli oleh

pembeli.

Url target

notifikasi notifyUrl String(200) Tidak

Setelah pembayaran selesai,

sistem harus kirim notifikasi ke

URL mana. Parameter yang

dikirim dalam notifikasi terkait

detail inquiry.

Url target

callback callbackUrl String(200) Ya

Ketika transaksi berhasil maupun

gagal, sistem akan redirect ke

URL ini. Pada saat redirect

Paylabs akan menyertakan nomor

transaksi seperti

callBackUrl?OrderNo=123456,

sehingga merchant dapat mencari

transaksi berdasarkan nomor

tresebut.

Bahasa lang String(10) Tidak

Secara default menggunakan

bahasa Indonesia. Untuk

mengubah ke Inggris, isi “en”

Signature sign String(32) Ya Signature, Lihat 1.3 .3Cara

Mengenkripsi.


10

3.2.3 Contoh

Contoh format request:

Disumbit dengan POST, parameter pakai format json

{

"mchId":"0010001",

"mobilePhone":"16666666666",

"amount":"10000.00",

"callbackUrl":"https://www.google.com",

"goodsInfo":"wash machine",

"orderNo":"12345678925613",

"notifyUrl":"https://www.google.com"

}

Contoh format respon:

{

"returnCode":"0",

"url":"https://paylabs.co.id/payer/in-home-index.html?notifyUrl=https://www.google.com&amo

unt=10000.00&callbackUrl=https://www.google.com&goodsInfo=wash machine&mchId=001000

1&outTradeNo=12345678925613&sign=7ea39fee1f8554e9f39d16e1bc6e0924"

}

3.2.4 Follow-up

Setelah pembeli klik bayar, mereka akan masuk ke halaman pembayaran H5 Paylabs. Dari

situ akan dituntun untuk proses pembayaran. Jika pembayaran berhasil, maka merchant, menerima

notifikasi bahwa transaksi berhasil melalui notifyUrl, dan pembeli akan kembali ke

halaman/aplikasi merchant melalui callbackUrl.

Kode

kembalikan returnCode String(20) Ya 0：Sukses, 1:Gagal

Alamat H5

dikembalik

an

url String(10) Tidak

Jenis pembayaran. Jika jenis

pembayaran kosong, maka akan

terbuka halaman H5. Maka pembeli

bisa memilih sendiri jenis

pembayaran. Respon jika nilai kode

respon adalah 0..

Deskripsi

kesalahan errCodeDes String(100) Tidak

Ketika nilai returnCode adalah 1,

maka me-return deskripsi error.

11

3.3 Meng-inquiry Status Detail Order

3.3.1 Parameters Request



Jenis

Transaksi tradeType String(20) Ya Di-hardcode “trade.query”

Nomor Versi version String(4) Ya

Diisi 2.1 atau 2.2. versi 2.2 meliputi

semua fitur versi 2.1 dan bisa

me-return field payChannelType dan

memberitahukan merchant tipe

pembayaran

Nomor


Nomor unik untuk merchant yang

diberikan oleh Payment Gateway

Nomor

Transaksi

Merchant



merchant. Bersifat unik di dalam

sistem merchant.

Jenis Query queryType String(1) Ya 1: Transaksi

2: Refund

Signature sign String(32) Ya Silahkan merujuk ke “1.3.3 Cara

Enkripsi”


Kode Status

Respon returnCode String(1) Ya

0: Sukses, 1:Gagal (bukan

status transaksi）

Deskripsi Respon returnMsg String(128) Tidak


Penjelasan termasuk

dalam bahasa Mandarin.


Nomor Transaksi

Merchant outTradeNo String(50) Ya

Nomor order yang dibuat

oleh merchant. Maksimal

50 karakter, bisa

mengandung alfabet dan

harus bersifat unik di

12

dalam sistem merchant.

Nomor Transaksi

Platform outChannelNo String(32) Tidak

Nomor transaksi platform

Waktu Transaksi

Dibuat transTime String(16) Ya yyyyMMddHHmmss

Waktu

Pembayaran tradePayTime String(16) Tidak yyyyMMddHHmmss

Batas Waktu

Pembayaran expiredTime String(16) Ya yyyyMMddHHmmss

Link

Pembayaran

atau Kode

Pembayaran

payCode String(200) Ya

dana wallet, credit card,

ovo wallet, akulaku

wallet, doku wallet returns

url link, the rest return va

code

Nominal

Transaksi amount

decimal(12,

2) Ya

Nominal transaksi dalam

satuan Rupiah, dengan

dua angka di belakang

koma, dan desimal dengan

tanda titik.

Kode Error errCode String(32) Tidak Silahkan merujuk ke

lampiran “Daftar Error”

Deskripsi Error errCodeDes String(128) Tidak Deskripsi dari Error

ID Merchant mchId String(10) Ya ID Merchant

Status Transaksi status String(2) Tidak

Hanya ada respon jika

berupa jenis query adalah

“Transaksi”

01：Belum bayar

02：Sudah bayar

05：Refund transfer

09：Pembayaran gagal

Status Refund refundStatus String(2) Tidak

Hanya ada respon jika

berupa jenis query adalah

“Refund”

02: Refund berhasil

03: Proses Refund

05: Refund Gagal

Tipe Query queryType String(1) Ya 1. Pesan Pembayaran

2. Refund

13

3.3.3 Contoh


{

"tradeType":"trade.query",

"mchId":"0010001",

"version":"2.1",

"outTradeNo":"1562142875641",

"queryType":"1",

"sign": "660B6B5BF40D2EDC54661400ADDBB15F"

}


{

"returnCode":"0",

"sign":"35BA9679E9D67881271164EBB4ED85FE",

"outChannelNo":"201907030100000026",

"status":"02",

"mchId":"0010001",

"outTradeNo":"1562142875641",

"amount":100.00,

"payCode":"0703163536",

"tradePayTime":"20190703163536",

"expiredTime":"20190703173040",

"transTime":"20190703163036"

}

Tipe

Pembayaran payChannelType String(32) Tidak

Saat versi adalah 2.2 akan

me-return

Nama

Pembayaran payBackName String(100) Tidak

Saat versi adalah 2.2, jika

tipe pembayaran adalah

minimarket akan

me-return

Signature sign String(32) Ya Signature, silahkan cek

cara enkripsi.

14

4. Notifikasi Asynchronous Callback

Server akan mengirim request POST dalam format JSON.

Mohon untuk me-return “SUCCESS” tanpa tanda kutip setelah mendapat notifikasi dari

sistem kami. Sistem akan terus mengirim notifikasi beberapa kali selama tidak mendapat respon

(total sebanyak 8 kali).

Jarak waktu notifikasi adalah 1 detik, 5 detik, 10 detik, 30 detik, 60 detik, 300 detik, 900

detik dan 1800 detik.


Kode Status

Respon returnCode String(1) Ya

0：Sukses、1：Gagal( Bukan status

transaksi)

Deskripsi



Penjelasan termasuk dalam bahasa

Mandarin.

Waktu

Transaksi transTime String(16) Ya yyyyMMddHHmmss

Waktu

Selesai tradePayTime String(16) Ya yyyyMMddHHmmss

Nomor

Transaksi

Platform

outChannelNo String(30) Tidak 2019102202900005956

Nomor

Transaksi

Merchant

outTradeNo String(50) Ya Dibuat saat merchant melakukan

transaksi

Waktu

Kadaluarsa epiredTime String(16) Ya yyyyMMddHHmmss

Link

Pembayaran

atau Kode

Pembayaran

payCode String(200) Ya

Nominal


Kode Error errCode String(32) Tidak Silahkan merujuk ke lampiran

“Daftar Error”

Deskripsi

Error errCodeDes String(128) Tidak Deskripsi terhadap kode error

Signature sign String(32) Ya Silahkan merujuk ke 1.3.3 Cara

Mengenkripsi

15

Response example

{

"returnCode":"0",

"sign":"35BA9679E9D67881271164EBB4ED85FE",

"outChannelNo":"201907030100000026",

"status":"02",

"mchId":"0010001",

"outTradeNo":"1562142875641",

"amount":100.00,

"expiredTime":"20190704163538",

"payCode":"454564648",

"tradePayTime":"20190703163538",

"transTime":"20190703163536"

}

5. Refund

5.1.1. API Refund

Perhatian: Saat ini hanya Kartu Kredit, Dana Wallet yang mendukung refund..

5.1.2. Parameter Request

Status

Transaksi status String(2) Ya

01：Belum Bayar

02：Sudah Bayar

05：Refund Transfer

09：Pembayaran Gagal

Nomor

Merchant mchId String(20)


Nomor




Gateway

Jenis channel String(10) Ya Jenis pembayaran, silahkan

16

5.1.3. Parameter Respon

Pembayaran merujuk ke Jenis

Pembayaran.

Nomor

Transaksi

Merchant


Nomor order yang dibuat

oleh merchant. Bersifat unik

di dalam sistem merchant.

Nominal


Nominal dalam satuan

Rupiah dan dua angka di

belakang koma, desimal

ditandai dengan titik.

Jenis Transaksi tradeType String(20) Ya Di-hardcode “refund.apply”

Nomor

Transaksi

Refund

outRefundNo String(32) Ya Nomor transaksi yang ingin

di-refund merchant.

Alamat

pemberitahuan

asinkron

pengembalian

notifyUrl String(200) Tidak

URL yang menerima

notifikasi apabila proses

refund selesai.

Parameter merujuk pada quer

y terperinci transaksi .

Signature sign String(32) Ya Silahkan merujuk ke 1.3.3

Cara Enkripsi.


Kode Status

Respon returnCode String(1) Ya 0：Sukses、1：Gagal

Deskripsi



Penjelasan termasuk dalam

bahasa Mandarin.


Nomor

Transaksi

Merchant



merchant. Maksimal 50 karakter,

bisa mengandung alfabet dan

harus bersifat unik di dalam

sistem merchant.

Nomor

Order channelRefundNo String(32) Tidak Nomor order platform

17

5.1.4. Contoh


{

"amount":"100",

"mchId":"0010001",

"outRefundNo":"1562309398129",

"outTradeNo":"T1562309523590",


"sign":"714C3C55E40982622AB96771140851C7",


"tradeType":"refund.apply"

}


{

"returnCode":"0",

"sign":"3D6205701CE3F876FFB320DB8B234C68",

"outRefundNo":"1562309398129",

"outTradeNo":"T1562309523590",

"channelRefundNo":"201907050200000034",

"refundStatus":"02"

}

Platform

Nomor

Transaksi

Refund

outRefundNo String(32) Tidak Nomor transaksi yang ingin

di-refund oleh merchant.

Status

Refund refundStatus String(2) Tidak

02：Refund berhasil

03：Sedang proses refund

05：Refund gagal

Kode Error errCode String(32) Tidak Silahkan merujuk ke lampiran

“Daftar Error”

Deskripsi

Kode Error errCodeDes String(128) Ya Penjelasan dari kode error.

Signature sign String(32) Ya Signature, merujuk ke 1.3.3

algoritma enkripsi.

18

6. Error Code

Kode Error Deskripsi

noauth Merchant tidak belum membuka hak akses untuk API ini.

paramError Format parameter salah.

outTradeNoUsed Nomor order merchant ada yang duplikat

signError Kesalahan Signature

systemError Kesalahan sistem

mchInvalid Merchant tidak valid

postDataEmpty Nilai Post kosong

channelIsError Jenis Pembayaran tidak benar

amountSetERROR Jumlah Transaksi tidak benar

phoneNotNull Nomor telepon tidak boleh kosong.

payerNotNull Nama Pembayar tidak boleh kosong

merchantOrderNotNull Nomor transaksi merchant tidak boleh kosong.

merchantOrderNoLengthExceeds Panjang Nomor transaksi merchant tidak boleh lebih dari

50 karakter.

merchantFreezing Bekukan akun pedagang

dokumen api sistem pembayaran · 2020. 10. 15. · 1 catatan revisi versi dokumen tanggal perubahan...

Documents