espay logo

Binding, Balance, Payment with Linkage Account



Channel before binding
Input phone number
Term & Condition Iframe
OTP Iframe
Binding Success
Channel after binding
Payment
Payment pin challenge
Payment Success
Payment insufficient fund
Top Up Instruction
Failed
Failed
Failed
Failed
Failed
Failed
Failed




Authentication

Setiap request harus akan diverifikasi 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: Jasmine

Format sebelum di encode : 

Aladdin:Jasmine

Hasil Base64 encoding : 

QWxhZGRpbjpKYXNtaW5l

Header yang dikirim :

Authorization : Basic 

QWxhZGRpbjpKYXNtaW5l

Setiap Authentication yang gagal akan menerima header http 401

Binding

Web Service untuk melakukan Binding/Linkage ke Aplikasi Pembayaran

Alur Pesan

Merchant → Espay

Metode

HTTP Post

API URL

Endpoint Development: https://sandbox-api.espay.id/rest/digitalpay/binding
Endpoint Production: https://api.espay.id/rest/digitalpay/binding


Parameter Request:
Nama Field Attribute Mandatory Keterangan
rq_uuid 64 Ya Pengidentifikasi request. ID unik untuk mengidentifikasi pesan-pesan tersebut dengan pesan yang lain
rq_datetime 19 Ya Tanggal dan waktu di server aplikasi Espay ketika pesan dikirim
comm_code 32 Ya Kode penjual yang terdaftar di aplikasi Espay
product_code 10 Ya Kode Produk yang diinginkan.
  1. OVOLINK
user_id 50 Ya User ID/Unik ID untuk identitas setiap customer dalam sistem Espay, dibuat oleh Merchant
customer_id 20 Ya Data customer
  1. OVOLINK = Nomor Handphone
customer_name 64 Ya Data customer
device_id 200 Ya Device ID/Imei
device_os 200 Ya Device OS
Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_1 like Mac OS X) AppleWebKit/603.1.30 (KHTML, like Gecko) Version/10.0 Mobile/14E304 Safari/602.1
signature 64 Ya Signature diperlukan untuk validasi oleh penjual

Parameter Response:
Nama Field Attribute Mandatory Keterangan
rq_uuid 64 Ya Pengidentifikasi request. ID unik untuk mengidentifikasi pesan-pesan tersebut dengan pesan yang lain
rs_datetime 19 Ya Tanggal dan waktu di server aplikasi Espay
error_code 4 Ya Jika error_code sama dengan 0000 = Sukses
Jika error_code tidak sama dengan 0000 = Gagal call request ke Aplikasi Pembayaran
error_message 32 Ya Jika error_code sama dengan 0000 = Sukses
Jika error_code tidak sama dengan 0000 = Gagal call request ke Aplikasi Pembayaran
webview_url ... Ya URL untuk melakukan binding
https://webview.byte-stack.net/cellblockui/partner/activation?action=otpLinkage&authType=2FA&client-id=oamerchantad&phoneNumber=08961690****&refId=1f1a851f-1b2b-4c18-b5d5-bc1640b48684&submissionType=redirect&destination=https://sandbox-api.espay.id/rest/digitalnotify/ovopin&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb2RlaGFzaCI6IlpHTTNabVprTnpsa09UZ3lOR014TkRreE9EVmpZV1JrWlRVellUUTVZbU0iLCJyYW5kb20iOiJOalF3TkRFeE1BIiwidmVyc2lvbiI6MX0.T3b9Oy5zwmCi3FG8vJB-JrQfjg_RlslriBvVdMcltwg&state={"customerKey ":"2111251028392480"}
webview_otp ... Tidak Token one time untuk binding (sudah tercantum di webview_url)
customer_key 16 Ya Unik customer key yang dibuat oleh Espay sebagai key untuk mengakses service Balance, Payment, Unbinding

Balance

Web Service untuk melakukan cek saldo ke Aplikasi Pembayaran

Alur Pesan

Merchant → Espay

Metode

HTTP Post

API URL

Endpoint Development: https://sandbox-api.espay.id/rest/digitalpay/balance
Endpoint Production: https://api.espay.id/rest/digitalpay/balance


Parameter Request:
Nama Field Attribute Mandatory Keterangan
rq_uuid 64 Ya Pengidentifikasi request. ID unik untuk mengidentifikasi pesan-pesan tersebut dengan pesan yang lain
rq_datetime 19 Ya Tanggal dan waktu di server aplikasi Espay ketika pesan dikirim
comm_code 32 Ya Kode penjual yang terdaftar di aplikasi Espay
product_code 10 Ya Kode Produk yang diinginkan.
  1. OVOLINK
customer_key 16 Ya Unik customer key yang dibuat oleh Espay sebagai key untuk mengakses service Balance, Payment, Unbinding
signature 64 Ya Signature diperlukan untuk validasi oleh penjual

Parameter Response:
Nama Field Attribute Mandatory Keterangan
rq_uuid 64 Ya Pengidentifikasi request. ID unik untuk mengidentifikasi pesan-pesan tersebut dengan pesan yang lain
rs_datetime 19 Ya Tanggal dan waktu di server aplikasi Espay
error_code 4 Ya Jika error_code sama dengan 0000 = Sukses
Jika error_code tidak sama dengan 0000 = Gagal call request ke Aplikasi Pembayaran
error_message 32 Ya Jika error_code sama dengan 0000 = Sukses
Jika error_code tidak sama dengan 0000 = Gagal call request ke Aplikasi Pembayaran
balance JSON Ya { "cash": "IDR 475238", "points": "IDR 4814960" }

Payment

Web Service untuk melakukan Payment ke Aplikasi Pembayaran

Alur Pesan

Merchant → Espay

Metode

HTTP Post

API URL

Endpoint Development: https://sandbox-api.espay.id/rest/digitalpay/pushtopay
Endpoint Production: https://api.espay.id/rest/digitalpay/pushtopay


Parameter Request:
Nama Field Attribute Mandatory Keterangan
rq_uuid 64 Ya Pengidentifikasi request. ID unik untuk mengidentifikasi pesan-pesan tersebut dengan pesan yang lain
rq_datetime 19 Ya Tanggal dan waktu di server aplikasi Espay ketika pesan dikirim
comm_code 32 Ya Kode penjual yang terdaftar di aplikasi Espay
product_code 10 Ya Kode Produk yang diinginkan.
  1. OVOLINK
user_id 50 Ya User ID/Unik ID untuk identitas setiap customer dalam sistem Espay, dibuat oleh Merchant
customer_key 16 Ya Customer Key dari Binding
customer_id 20 Ya Data customer
  1. OVOLINK = Nomor Handphone
order_id 20 Ya Nomor transaksi / ID faktur / ID unik yang mengidentifikasi pesanan / tagihan / faktur
amount 13 Ya Jumlah tagihan yang harus dibayarkan
description 200 Ya Order deskripsi
payment_method 200 Ya {"cash":"1000"}
is_confirmation 1 Tidak Diisi Y jika service konfirmasi push to pay
signature 64 Ya Signature diperlukan untuk validasi oleh penjual

Parameter Response:
Nama Field Attribute Mandatory Keterangan
rq_uuid 64 Ya Pengidentifikasi request. ID unik untuk mengidentifikasi pesan-pesan tersebut dengan pesan yang lain
rs_datetime 19 Ya Tanggal dan waktu di server aplikasi Espay
error_code 4 Ya Jika error_code sama dengan 0000 = Sukses
Jika error_code tidak sama dengan 0000 = Gagal call request ke Aplikasi Pembayaran
error_message 32 Ya Jika error_code sama dengan 0000 = Sukses
Jika error_code tidak sama dengan 0000 = Gagal call request ke Aplikasi Pembayaran
customer_id 20 Ya Data customer
  1. OVOLINK = Nomor Handphone
order_id 20 Ya Nomor transaksi / ID faktur / ID unik yang mengidentifikasikan pesanan / tagihan / faktur
trx_status 2 Optional Status transaksi, tetap mengacu pada Payment Notification service
amount 20 Ya Jumlah tagihan
webview_url ... Ya URL untuk melakukan payment challenge dari E-Money nya
https://webview.byte-stack.net/cellblockui/partner/activation?action=otpLinkage&authType=2FA&client-id=oamerchantad&phoneNumber=08961690****&refId=1f1a851f-1b2b-4c18-b5d5-bc1640b48684&submissionType=redirect&destination=https://sandbox-api.espay.id/rest/digitalnotify/ovopin&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb2RlaGFzaCI6IlpHTTNabVprTnpsa09UZ3lOR014TkRreE9EVmpZV1JrWlRVellUUTVZbU0iLCJyYW5kb20iOiJOalF3TkRFeE1BIiwidmVyc2lvbiI6MX0.T3b9Oy5zwmCi3FG8vJB-JrQfjg_RlslriBvVdMcltwg&state={"customerKey ":"2111251028392480"}

Signature

Setiap request harus dilengkapi signature untuk divalidasi. Client akan diberikan Secret Key di dokumentasi terpisah dari document ini. Key tersebut akan diolah untuk menjadi signature dengan langkah-langkah sebagai berikut :

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

##rq_uuid##comm_code##product_code##order_id##amount##mode##key##

Contoh :

rq_uuid : 123ABC-DEF456
comm_code : MYCOMMCODE
product_code : OVO
order_id : ORDER001
amount : 10000
key : S3cr317kEY
mode : PUSHTOPAY

Sehingga akan menjadi rangkaian string sebagai berikut :

Result = ##123ABC-DEF456##MYCOMMCODE##OVO##ORDER001##10000##PUSHTOPAY##S3cr317kEY##

Step 2 :
Hasil dari Step 1 di uppercase menjadi seperti ini:

##123ABC-DEF456##MYCOMMCODE##OVO##ORDER001##10000##PUSHTOPAY##S3CR317KEY##

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

$sha256 = hash(sha256, '##123ABC-DEF456##MYCOMMCODE##OVO##ORDER001##10000##PUSHTOPAY##S3CR317KEY##')

Result = aa19e37e1bf6d5cfb23d59988d397f9ba6e79cf6853606e45a6809e0ca9a7b5d

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

IP Whitelist Registration

ESPAY server juga akan memfilter alamat IP yang akan mengakses server ESPAY. Untuk itu silahkan kontak Tim ESPAY untuk mendaftarkan IP anda.

Contoh Request

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

rq_uuid=PAIDBAQ721659
&rq_datetime=2019-11-02 01:29:10
&comm_code=SGWPAIDBAQ02
&product_code=OVO
&order_id=ESP.0043330
&amount=105000
&key=27hsdfv6ukmepgrv
&description=Customer PaidbaQ
&customer_id=081223213625
&signature=89c1ac1cdbb30185bcab457f209ba90ef43486216823abfe7ed013b24ee49733
        
    
Contoh Response

        
    {
        "rq_uuid": "E253B30C410911EB86A634BE08A20EFB",
        "rs_datetime": "2020-12-18 15:22:48",
        "error_code": "0000",
        "error_message": "Success",
        "trx_id": "ESP1608279768GQUZ",
        "QRLink": "https://sandbox-api.espay.id/rest/digitalnotify/qr/?trx_id=ESP1608279768GQUZ",
        "QRCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAJMAAACTAQMAAACwK7lWAAAABlBMVEX///8AAABVwtN+AAAACXBIWXMAAA7EAAAOxAGVKw4bAAAB+0lEQVRIieWWsa30IBCE1yIgww0g0QYZLdkNcHYDdktktGGJBuzMAfL+w/NJ7w/Z+CF0uvtOstjZ2cFEf22NzFvglSlqhy+PhBlSe+L15o3U4vFTwkLZtLpS24/HP1JGkWz0NMnZynXk2k4hZaQ2cqd3V6r0W1sXa/r58t3/adrDsIbs1uROXc7f1nWxMfHi7efmi92m3SNhAx9zVlto+s25iBg0uzIvZMmrHa6RsTqn+kmKs+NEk4SN7fh2vI/hdsCnhA23Nb4s4RhZMb8972XGu0WXKzUB1vuto5vpGuHTYCftlvD2rZdBthXHCage8h8iNqTaqk/V6MP4GkXshkNphtcCPK4eCTMeHwWRsGnI956lm2mHIFk8r1mh50bCSKN09Lys6YgBppOwgPjBY9ye7OSPKGGQLVIz2kZ1ZhmDfmdAzzFefNK3b50MvQK+Ms2MIFGLiIWykIN+m3c72yhhQ7KwjKG2YyARw2Dt8ClVCgdy9BSxgDzAPYMTlTWXRcIouEfzdaNvdUhv/nUz5FC2GM3PXT9sjYSNCTEAk7rmU+ZTwugbJ7AMxJMx3DMIsE9CQRV5YCSs3W9N/jbTkd6rppuFNtA/2dn2JGQtwzR8Wh5fScjg061djBaX1SNi7f3lGHKdMJ3fvvUy6Ldnd6Hh7fXnPUsv+1vrH6ThjE2DVkpUAAAAAElFTkSuQmCC"
    }