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:

  1. Two-Way communication, every request will be replied with a response.
  2. Using HTTPS protocol.
  3. Client sends parameters in HTTP POST format.
  4. 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
signature AN 255 Yes Signature (view Signature Validation)
beneficiary_bank_code AN 5 Yes Destination bank code
beneficiary_account_number AN 32 Yes Destination account number

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

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
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 &signature= 58ee167fb041c237c9759398e4d7ca017f113c77c33c82396e895acb64d5901e &beneficiary_bank_code=014&beneficiary_account_number=2731726215

Inquiry Name
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" }

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