espay logo

Payment Instruction



Introduction

Dokumen ini dibuat untuk standar komunikasi antara aplikasi mitra ESPay dengan system ESPay. File ini menjelaskan webservice, data flow, dan field-field untuk penggunaan webservice B2B Online Banking

Seluruh service Payment Instruction dilakukan dengan ketentuan sebagai berikut :

  1. Two-Way communication, setiap request akan dibalas dengan response.
  2. Menggunakan protokol HTTPS.
  3. Client mengirimkan parameter dalam format HTTP POST.
  4. Server akan membalas dengan response format JSON.

Authentication

Setiap request yang masuk ke sistem ESPay akan selalu diverifikasi dengan metode basic auth. Client akan diberikan username dan password di media terpisah dan harus dijaga kerahasiannya. 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 encoding base64.

Contoh

Username: Romeo
Password: Juliet

Format sebelum di encode : Romeo:Juliet

Hasil Base64 encoding: Um9tZW86SnVsaWV0

Header yang dikirim :

Authorization : Basic Um9tZW86SnVsaWV0

Signature Validation

Setiap request service harus dilengkapi parameter signature untuk divalidasi. Client akan diberikan Secret Key di dokumen atau media terpisah dan diharuskan menjaga kerahasian Secret Key agar tidak disalahgunakan oleh pihak yang tidak berkepentingan. Secret Key yang dimiliki Client akan diolah untuk menjadi signature dari kombinasi parameter di setiap webservice.

Parameter yang digunakan (berdasarkan webservice) :

Inquiry Name

  • rq_uuid
  • rq_datetime
  • sender_id
  • beneficiary_bank_code
  • beneficiary_account_number
  • Secret Key

Inquiry Balance

  • rq_uuid
  • rq_datetime
  • sender_id
  • bank_code
  • Secret Key

Inquiry Status Transfer / Transaksi

  • rq_uuid
  • rq_datetime
  • sender_id
  • transaction_id
  • Secret Key

Fund Transfer (Inhouse / Interbank)

  • rq_uuid
  • rq_datetime
  • sender_id
  • beneficiary_bank_code
  • beneficiary_account_number
  • amount
  • Secret Key

Berikut contoh langkah-langkah pembuatan signature untuk webservice Inquiry Name :

Step 1:
Gabungkan parameter-parameter yang digunakan dengan urutan sebagai berikut :

rq_uuid + rq_datetime + sender_id + beneficiary_bank_code + beneficiary_account_number + Secret Key

Contoh:

Request UUID : CLIENTID123abc-def456
Request Datetime : 2017-12-13 09:17:45
Sender ID : CLIENTID
Beneficiary Bank Code : 014
Beneficiary Account Number : 2731726215
Secret Key : b2bS3cr317kEY

Sehingga akan menjadi rangkaian string sebagai berikut :

Result = CLIENTID123abc-def4562017-12-13 09:17:45CLIENTID014

Step 2:
Uppercase kombinasi parameter pada Step 1 lalu ditambahkan Secret Key pada di akhir :

$tmpSignature = CLIENTID123ABC-DEF4562017-12-13 09:17:45CLIENTID0142731726215
$plainSignature = CLIENTID123ABC-DEF4562017-12-13
09:17:45CLIENTID0142731726215b2bS3cr317kEY

Step 3:
Hash hasil dari Step 2 dengan menggunakan hashing sha256 :

$hash = hash(sha256, CLIENTID123ABC-DEF4562017-12-13
09:17:45CLIENTID0142731726215b2bS3cr317kEY)
Result = 1fa3db27eb462827cad9f77862180f44238615291799a8af9c2e9ddf52d3b412

Hasil dari Step 3 inilah yang akan digunakan sebagai value dari parameter signature.

Inquiry Name

Digunakan untuk mendapatkan informasi atau nama dari pemilik rekening tujuan

API URL

Development : https://sandbox-api.espay.id/b2b/inquiry/name
Production : https://api.espay.id/b2b/inquiry/name

Format message yang dikirimkan harus dalam bentuk URL encoded. Keterangan untuk setiap field dalam HTTP POST message tersebut:

Inquiry Name Request Data :

Nama Field Attribute Mandatory Keterangan
rq_uuid ANS 255 Ya Request Identifier. ID unik untuk mengidentifikasi request message tersebut dengan message lainnya.
Format : Client ID + Unique ID
Ex : CLIENTID123abc-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
Ex : 2014-12-17 12:30:45
sender_id AN 32 Ya Identitas unik aplikasi Client yang terdaftar di sistem ESPay
beneficiary_bank_code AN 5 Ya Kode bank tujuan
beneficiary_account_number AN 32 Ya Nomor rekening tujuan
signature AN 255 Ya Signature (lihat Signature Validation)
source_bank_code N 3 Opsional Kode Bank Sumber.
Direct : Menggunakan kode bank yang terdaftar di Espay.
Deposit : DIberikan dari Espay.
transfer_type N 1 Opsional Deposit : Mandatory
Menggunakan fix value 5.
amount N 15,2 Opsional Deposit : Mandatory Jumlah transaksi
Format: 1000000.00
category_purpose N 1 Opsional Deposit : Mandatory
category_purpose : 0=Investment, 1=Transfer of Wealth, 2=Purchase, 3=Others (for various purposes)
swift_code N 3 Opsional Deposit : Mandatory
Kode bank yang tedaftar di BI sepasang dengan bankcode.
Menggunakan kode yang terdaftar di Espay.

Setelah melakukan request dengan contoh diatas, client akan mendapatkan response. Dengan rincian dan contoh sebagai berikut :

Inquiry Name Response Data :

Nama Field Attribute Mandatory Keterangan
rq_uuid ANS 255 Ya Request Identifier. ID unik untuk mengidentifikasi request message tersebut dengan message lainnya (echoed from request).
Format : Client ID + Unique ID
Ex : CLIENTID123abc-def456
rs_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 error
error_message ANS 255 Ya Deskripsi error
beneficiary_account_number AN 32 Ya Nomor rekening tujuan
beneficiary_account_name AN 32 Ya Nama pemilik rekening tujuan
beneficiary_account_currency AN 3 Tidak Kode mata uang
beneficiary_account_status AN 5 Tidak Status rekening
beneficiary_account_type AN 32 Tidak Tipe rekening
beneficiary_bank_name AN 32 Ya Nama bank tujuan
transfer_reff AN 32 Tidak Nomor referensi untuk Fund Transfer
swift_code AN 3 Tidak Deposit : Mandatory Kode bank yang tedaftar di BI
sepasang dengan bankcode.
Menggunakan kode yang terdaftar di Espay.

Inquiry Status Transfer / Transaksi

Digunakan untuk mendapatkan status terakhir dari transaksi sebelumnya

API URL

Development : https://sandbox-api.espay.id/b2b/inquiry/status
Production : https://api.espay.id/b2b/inquiry/status

Format message yang dikirimkan harus dalam bentuk URL encoded. Keterangan untuk setiap field dalam HTTP POST message tersebut:

Inquiry Status Transfer / Transaksi Request Data :

Nama Field Attribute Mandatory Keterangan
rq_uuid ANS 255 Ya Request Identifier. ID unik untuk mengidentifikasi request message tersebut dengan message lainnya.
Format : Client ID + Unique ID
Ex : CLIENTID123abc-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
Ex : 2014-12-17 12:30:45
sender_id AN 32 Ya Identitas unik aplikasi Client yang terdaftar di sistem ESPay
signature AN 255 Ya Signature (lihat Signature Validation)
transaction_id AN 32 Ya Nomor transaksi yang digunakan pada service Fund Transfer

Setelah melakukan request dengan contoh diatas, client akan mendapatkan response. Dengan rincian dan contoh sebagai berikut :

Inquiry Status Transfer / Transaksi Response Data :

Nama Field Attribute Mandatory Keterangan
rq_uuid ANS 255 Ya Request Identifier. ID unik untuk mengidentifikasi request message tersebut dengan message lainnya (echoed from request).
Format : Client ID + Unique ID
Ex : CLIENTID123abc-def456
rs_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 error
error_message ANS 255 Ya Deskripsi error
source_bank_code AN 32 Tidak Kode bank pengirim
source_account_number AN 32 Tidak Nomor rekening pengirim
beneficiary_bank_code AN 3 Ya Kode bank penerima
beneficiary_account_number AN 5 Ya Nomor rekening penerima
amount NUM 15,2 Ya Jumlah transaksi
Format: 1000000.00
transaction_datetime Datetime Ya Waktu transaksi
transaction_datetime Datetime Ya Waktu transaksi
status_code ANS 5 Ya Kode status transaksi
status_description ANS 255 Ya Keterangan status transaksi

Table of Bank Code

Bank Code Bank Name
002 Bank BRI
008 Bank Mandiri
009 Bank BNI
009 Bank BNI Syariah
011 Bank Danamon
014 Bank BCA
013 Bank Permata
016 Bank Maybank
022 Bank CIMB Niaga
022 Bank CIMB Niaga Syariah
026 Bank Lippo
028 Bank OCBC NISP
031 CITIBANK
147 Bank Muamalat
153 Bank Sinarmas
157 Bank Maspion
200 Bank Tabungan Negara (BTN)
422 Bank BRI Syariah
426 Bank MEGA
441 Bank BUKOPIN
451 Bank Syariah Mandiri
536 Bank BCA Syariah

Table Error Payment Instruction

Response Code Description
0000 Success
0011 Invalid Signature
0032 Error while execution
0033 Internal error
0037 Service maintenance
0050 Incomplete field / mandatory field empty or not set
0051 Zero amount
0052 Invalid account or currency
0060 Transaction rejected
0061 Timeout from core banking
0062 Request not set to core banking, please retry
9999 Suspect / timeout 
Contoh Request:

       
        Contoh Request:
        POST /rest/digitalpay/void 
        HTTP/1.1
        Content-Length: 282
        Content-Type: application/x-www-form-urlencoded
        Accept: */*Host: sandbox-api.espay.id
        Authorization: Basic U0dXUEFJREJBUTAyOkhOUlFLSENI

        rq_uuid=88996d80-e466-48f8-8b4b-be2334e0f0dc
        &comm_code=SGWYESSISHOP
        &product_code=OVO
        &order_id=SGWYESSIOVO000040
        &trx_id=ESP1566967156ALDY
        &amount=10000
        &signature=e3aa2465caa0b6300fca424aa5309a817697b7b5a3c3b76b4fbef1fc3c061b8f

    
Contoh Response:

        
        {
            "rq_uuid": "88996d80-e466-48f8-8b4b-be2334e0f0dc",
            "rs_datetime": "2019-08-28 11:44:58",
            "error_code": "0000",
            "error_message": "",
            "order_id": "SGWYESSIOVO000040",
            "trx_id": "ESP1566967156ALDY",
            "trx_status": "V"
        }
    
Inquiry Name (Direct)
Contoh Request:

       
            POST /b2b/inquiry/account HTTP/1.1
            Host: sandbox-api.espay.id
            Connection: keep-alive
            Content-Length: 196
            Authorization: Basic Um9tZW86SnVsaWV0
            Content-Type: application/x-www-form-urlencoded
            Accept: */*
            rq_uuid=CLIENTIDUUID171214001
            &rq_datetime=2017-12-14 15:30:00
            &sender_id=CLIENTID
            &beneficiary_bank_code=014
            &beneficiary_account_number=2731726215
            &signature=58ee167fb041c237c9759398e4d7ca017f113c77c33c82396e895acb64d5901e

    
Inquiry Name (Direct)
Contoh Respone:

    
            {
              "rq_uuid":"CLIENTIDUUID171214001",
              "rs_datetime":"2017-12-14 15:30:02",
              "error_code":"0000",
              "error_message":"Success",
              "beneficiary_account_number":"2731726215",
              "beneficiary_account_name":"PT. Pembayaran Lintas Usaha Sukses",
              "beneficiary_account_currency":"N/A",
              "beneficiary_account_status":"N/A",
              "beneficiary_account_type":"N/A",
              "beneficiary_bank_name":"Bank Central Asia",
              "transfer_reff":"N/A"
            }
    
Inquiry Name (Deposit)
Contoh Request:

       
            POST /b2b/inquiry/account HTTP/1.1
            Host: sandbox-api.espay.id
            Connection: keep-alive
            Content-Length: 196
            Authorization: Basic Um9tZW86SnVsaWV0
            Content-Type: application/x-www-form-urlencoded
            Accept: */*
            rq_uuid=testinqname002
            &rq_datetime=2023-10-17 11:50:32
            &sender_id=VAPESTOREID
            &beneficiary_bank_code=046
            &beneficiary_account_number=3320126060
            &signature=123356658a597023cc68957b90a8e2262808040f505cb1a051fd9b8641abd486
            &source_bank_code=013
            &transfer_type=5
            &amount=50000.00
            &category_purpose=0
            &swift_code=DBSBIDJA

    
Inquiry Name (Deposit)
Contoh Respone:

    
            {
              "rq_uuid":"testinqname001",
              "rs_datetime":"2023-10-20 15:23:25",
              "error_code":"0000",
              "error_message":"Success",
              "beneficiary_account_name":"ACCOUNT DUMMY 3320126060",
              "beneficiary_account_number":"3320126060",
              "beneficiary_account_currency":"IDR",
              "beneficiary_account_status":"N/A",
              "beneficiary_account_type":"SVGS",
              "beneficiary_bank_name":"Bank DBS",
              "swift_code": "DBSBIDJA",
              "transfer_reff":"N/A"
            }
    
Inquiry Status Transfer / Transaksi
Contoh Request:

            
            POST /b2b/inquiry/status HTTP/1.1
            Host: sandbox-api.espay.id
            Connection: keep-alive
            Content-Length: 184
            Authorization: Basic Um9tZW86SnVsaWV0
            Content-Type: application/x-www-form-urlencoded
            Accept: */*
            rq_uuid=CLIENTIDUUID171214004
            &rq_datetime=2017-12-14 15:35:00
            &signature=3fda772700296c7179b985b37c6112affedeba0b79482bb53f2ab8ffd8b3ae79
            &sender_id=CLIENTID
            &transaction_id=TRX171214001

    
Inquiry Status Transfer / Transaksi
Contoh Respone:

     
            {
              "rq_uuid":"CLIENTIDUUID171214002",
              "rs_datetime":"2017-12-14 15:30:02",
              "error_code":"0000",
              "error_message":"Success",
              "source_bank_code":"N/A",
              "source_account_number":"N/A",
              "beneficiary_bank_code":"002",
              "beneficiary_account_number":"720801001600505",
              "amount":"1000000.00",
              "transaction_datetime":"2017-12-14 15:33:02",
              "status_code":"0000",
              "status_descriptioin":"Success"
            }