Payment Instruction

Introduction

This document is created for communication standards between ESPay partner applications and ESPay systems. This file describes the webservice, data flow, and fields for the use of the B2B Online Banking webservice

All services are Payment Instruction done under the following conditions:

Two-Way communication, every request will be replied with a response.
Using HTTPS protocol.
Client sends parameters in HTTP POST format.
Server will reply in JSON format.

Authentication

Any request that goes into ESPay system will always be verified with basic authentication method. Client will be given a username and password in a separate media and must be kept confidential. Every request sent must be accompanied by the Authorization header with the Basic value followed by username and password with username format: encoded password with base64 encoding.

Example

Username: Romeo
Password: Juliet

Format before encoding : Romeo:Juliet

Base64 encoding result: Um9tZW86SnVsaWV0

Headers sent:

Authorization: Basic Um9tZW86SnVsaWV0

Signature Validation

Each service request must be equipped with signature parameters to be validated. The Client will be assigned a Secret Key in a separate document or media and is required to keep Secret Key confidential in order not to be misused by unauthorized parties. Client's Secret Key will be processed to be the signature of a combination of parameters in each webservice.

Parameters used (based on 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 / Transaction

rq_uuid
rq_datetime
sender_id
transaction_id
Secret Key

Funds Transfer (Inhouse / Interbank)

rq_uuid
rq_datetime
sender_id
beneficiary_bank_code
beneficiary_account_number
amount
Secret Key

Here is an example of signature creation steps for the Inquiry Name webservice :

Step 1:
Combine the parameters used in the following order :

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

Example:

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

So it will be strings as follows :

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

Step 2:
Uppercase parameter combination in Step 1 and then add Secret Key at the end :

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

Step 3:
Hash the result of Step 2 by using hashing sha256 :

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

The result of this step 3 will be used as the value of the signature parameter.

Inquiry Name

Used to obtain information or the name of the destination account holder

API URL

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

The format of the submitted message must be in the form of an encoded URL. Description for each field in the HTTP POST message:

Inquiry Name Request Data :

Name Field	Attribute	Mandatory	Description
rq_uuid	ANS 255	Yes	Request Identifier. Unique ID to identify the request message with other message. Format : Client ID + Unique ID Ex : CLIENTID123abc-def456
rq_datetime	ANS 19	Yes	The date and time in the client application server when the massage is sent. Format : YYYY-MM-DD HH:MM:SS Ex : 2014-12-17 12:30:45
sender_id	AN 32	Yes	The unique identity of Client applications listed on the ESPay system
beneficiary_bank_code	AN 5	Yes	Destination bank code
beneficiary_account_number	AN 32	Yes	Destination account number
signature	AN 255	Yes	Signature (view Signature Validation)
source_bank_code	N 3	Optional	Source Bank Code. Direct : Use bank code registered in Espay. Deposit : Given from Espay.
transfer_type	N 1	Optional	Deposit : Mandatory Use fix value 5.
amount	N 15,2	Optional	Deposit : Mandatory Transaction amount Format: 1000000.00
category_purpose	N 1	Optional	Deposit : Mandatory category_purpose : 0=Investment, 1=Transfer of Wealth, 2=Purchase, 3=Others (for various purposes)
swift_code	N 3	Optional	Deposit : Mandatory The bank code registered with BI is paired with the bank code. Given from Espay.

After making a request with the example above, the client will get a response with details and examples as follows :

Inquiry Name Response Data :

Name Field	Attribute	Mandatory	Description
rq_uuid	ANS 255	Yes	Request Identifier. Unique ID to identify the request message with other messages (obtained from request). Format : Client ID + Unique ID Ex : CLIENTID123abc-def456
rs_datetime	ANS 19	Yes	The date and time in the client application server when the message is sent. Format : YYYY-MM-DD HH:MM:SS Ex : 2014-12-17 12:30:45
error_code	ANS 4	Yes	Error code
error_message	ANS 255	Yes	Error description
beneficiary_account_number	AN 32	Yes	Destination account number
beneficiary_account_name	AN 32	Yes	Destination account name
beneficiary_account_currency	AN 3	No	Account currency
beneficiary_account_status	AN 5	No	Account Status
beneficiary_account_type	AN 32	No	Account type
beneficiary_bank_name	AN 32	Yes	Destination bank name
transfer_reff	AN 32	No	Fund Transfer number reference
swift_code	AN 3	No	Deposit : Mandatory The bank code registered with BI is paired with the bank code. Given from Espay.

Transfer / Transaction Status Inquiry

Used to get the last status of the previous transaction

API URL

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

The format of the submitted message must be in the form of an encoded URL. Description for each field in the HTTP POST message:

Inquiry Status Transfer / Transaction Request Data:

Name Field	Attribute	Mandatory	Description
rq_uuid	ANS 255	Yes	Request Identifier. Unique ID to identify the request message with other messages. Format : Client ID + Unique ID Ex : CLIENTID123abc-def456
rq_datetime	ANS 19	Yes	The date and time in the client application server when the massage is sent. Format : YYYY-MM-DD HH:MM:SS Ex : 2014-12-17 12:30:45
sender_id	AN 32	Yes	The unique identity of Client applications listed on the ESPay system
signature	AN 255	Yes	Signature (view Signature Validation)
transaction_id	AN 32	Yes	The transaction number used in the service Fund Transfer

After making a request with the example above, the client will get a response. With details and examples as follows :

Inquiry Data Transfer / Transaction Response Inquiry:

Name Field	Attribute	Mandatory	Description
rq_uuid	ANS 255	Yes	Request Identifier. Unique ID to identify the request message with other message (obtained from request). Format : Client ID + Unique ID Ex : CLIENTID123abc-def456
rs_datetime	ANS 19	Yes	The date and time in the client application server when the message is sent. Format : YYYY-MM-DD HH:MM:SS Ex : 2014-12-17 12:30:45
error_code	ANS 4	Yes	Error code
error_message	ANS 255	Yes	Error description
source_bank_code	AN 32	No	Source Bank Code
source_account_number	AN 32	No	Source Account Number
beneficiary_bank_code	AN 3	Yes	Destination Bank Code
beneficiary_account_number	AN 5	Yes	Destination account number
amount	NUM 15,2	Yes	Transaction amount Format: 1000000.00
transaction_datetime	Datetime	Yes	Transaction Date/time
status_code	ANS 5	Yes	Transaction status code
status_description	ANS 255	Yes	Transaction status description

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

Example 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

Example 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)
Example 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)
Example 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)
Example 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)
Example 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" }

Transfer / Transaction Status Inquiry
Example 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 Transfer / Transaction Status
Respone Example:

{ "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" }