espay logo

Bill Payment

Introduction



Download Image

This feature enables you to perform purchasing / invoice payment activities such as cell phone credit, PLN (electricity), PDAM (clean water), BPJS (national health insurance), etc. In the process, ESPAY serves as the third party which mediates between the user (Merchant) and Provider.


Authentication

Each request will be verified by basic authentication, so every request sent must include the authorization Header, with the basic value followed by username and password, with username:password format that has been encoded with Base64 encoding.

Example :

Username: Aladdin

Password: Smelana

Format before being encoded : Aladdin:Smelana

Base64 encoding result : 

 QWxhZGRpbjpTbWVsYW5h

Header sent :

Authorization : Basic 

QWxhZGRpbjpTbWVsYW5h

Failed authentication will receive http 401 header

Signature Validation

All requests that enter ESPAY system will be signature validated. Signature sent on each request must follow the signature parameters. Each signature will be hashed using sha256 algorithm. The signature will be generated by multiplying some values from the previous value parameter and with a key provided by ESPAY. Signature formats differ for each service. Each parameter will start with, be separated by, and end with ##. All values will be changed to uppercase. The signature sequence is as follows:

  • Service Bill Inquiry
    • Sender id
    • Order id
    • Product code
    • Rq uuid
    • Key

(Bill Inquiry : ##sender_id##order_id##product_code##rq_uuid##key##)

  • Service Bill Payment
    • Sender id
    • Order id
    • Product code
    • Amount
    • Rq uuid
    • Key

(Bill payment : ##sender_id##order_id##product_code##amount##rq_uuid##key##)

  • Service Inquiry Bill Payment Status
    • Sender id
    • Referensi ID
    • Rq uuid
    • Key
  • Service Get Balance
    • Sender ID
    • Rq uuid
    • Key

Generated signature example

First format

##SGOPLUS##142921023##STCKAI##sgoplus201711aa##keyforsignature##

Change to uppercase

##SGOPLUS##142921023##STCKAI##SGOPLUS201711AA##KEYFORSIGNATURE##

Hash with sha256 algorithm

6767aa419fe1fbf8f8896c7a0857b5cea41a7e4f407262f0fc82a914137a9401

IP Whitelist Registration

ESPAY server also filters the IP address which accesses the ESPAY server. So please contact ESPAY team to register your IP.

Bill Inquiry & Bill Payment

  • Bill Inquiry

    • Performed through web-service using REST protocol. Clients send a number of values / parameters in HTTP POST to the biller, to perform transaction inquiry or obtain data from transaction, such as amounts to be paid or other transaction details.

    API URL
    Development : https://sandbox-api.espay.id/rest/biller/inquirytransaction
    Production: https://api.espay.id/rest/biller/inquirytransaction

    Format of the transmitted message must be Encoded URL.

    Description for each field in the HTTP POST message:

    BILL INQUIRY REQUEST DATA
    Name Field Attribute Mandatory Description
    rq_uuid ANS 255 Yes Request Identifier. Unique ID to identify the request message with other messages.
    Formula : sender_id + unique ID
    Ex : SENDERID123ABC-DEF456
    rq_datetime ANS 19 Yes 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
    sender_id ANS 50 Yes Client’s unique identity registered in ESPAY (Will be assigned to each client).
    password ANS 32 Yes Client’s access password registered in ESPAY. (Will be determined according to the agreement).
    order_id ANS 64 Yes Transaction ID. Can be a mobile phone number, credit card number, customer id, etc.
    product_code ANS 16 Yes Supported product code. View the Product List table.
    additional_data ANS 999 No Supported data required for certain products in JSON format. Details can be found on Bill Inquiry page and Bill Payment additional data
    signature ANS 999 Yes Signature
    After requesting, client will get JSON response from biller. Example as follows :

    - BILL INQUIRY RESPONSE DATA

    Name Field Attribute Mandatory Description
    rq_uuid ANS 255 Yes Request Identifier. Unique ID to identify the request message with other messages.
    Formula : sender_id + unique ID
    Ex : SENDERID123ABC-DEF456
    rs_datetime ANS 19 Yes 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. 0000 = Success, other than that failed.
    error_desc ANS 128 Yes Error description if any.
    order_id ANS 64 Yes Transaction ID. Can be a mobile phone number, credit card number, customer id, etc.
    amount NUM 17 Yes Amount to be paid. Default is 2 decimal digit.
    Ex : 10000000 = 100.000,00
    bill_amount NUM 17 No Amount to be paid before adding admin_fee. Default is 2 decimal digit.
    Ex : 10000000 = 100.000,00
    admin_fee NUM 17 No Admin fee if any. Default is 2 decimal digit.
    Ex : 10000000 = 100.000,00
    description ANS 128 No Transaction description
    data ANS 999 Yes Transaction data detail from biller in JSON format. This data is dynamic based on the inquiry product.
    Details can be found on Bill Inquiry page and Bill Payment data
  • Bill Payment

    • Performed through web-service using REST protocol. Client sends a number of values / parameters in HTTP POST form to the biller, to notify biller that there has been a transfer made to the biller’s account as form of payment / purchase / transaction by client.

    API URL
    Development : https://sandbox-api.espay.id/rest/biller/paymentreport
    Production: https://api.espay.id/rest/biller/paymentreport

    Format of the transmitted message must be Encoded URL.

    Description for each field in the HTTP POST message:

    BILL PAYMENT REQUEST DATA
    Name Field Attribute Mandatory Description
    rq_uuid ANS 255 Yes Request Identifier. Unique ID to identify the request message with other messages.
    Formula : sender_id + unique ID
    Ex : SENDERID123ABC-DEF456
    rq_datetime ANS 19 Yes 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
    sender_id ANS 50 Yes Client’s unique identity registered in ESPAY (Will be assigned to each client).
    channel_code ANS 32 No The channel code used by the client as a differentiator in client applications
    password ANS 32 Yes Client’s access password registered in ESPAY. (Will be determined according to the agreement).
    order_id ANS 64 Yes Transaction ID. Can be a mobile phone number, credit card number, customer id, etc.
    product_code ANS 16 Yes Supported product code. View the Product List table.
    amount NUM 17 Yes Amount to be paid. Default is 2 decimal digit
    Ex : 35000000 = 350.000,00
    data ANS 999 Yes Transaction data detail from biller in JSON format. In accordance with the result of inquiry (if any).
    Details can be found on Bill Inquiry page and Bill Payment data
    additional_data ANS 999 No Supported data required for certain products in JSON format. Details can be found on Bill Inquiry page and Bill Payment additional data
    signature ANS 999 Yes Signature

    Upon request, clients will get JSON response from biller. Example as follows:

    BILL PAYMENT RESPONSE DATA
    Name Field Attribute Mandatory Description
    rq_uuid ANS 255 Yes Request Identifier. Unique ID to identify the request message with other messages.
    Formula : sender_id + unique ID
    Ex : SENDERID123ABC-DEF456
    rs_datetime ANS 19 Yes 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. 0000 = Success, other than that failed.
    error_desc ANS 128 No Error description if any
    order_id ANS 64 Yes Transaction ID. Can be a mobile phone number, credit card number, customer id, etc.
    description ANS 128 No Transaction description
    data ANS 999 Yes Transaction data detail from biller in JSON format.
    Details can be found on Bill Inquiry page and Bill Payment data

Inqury Bill Payment Status

Performed through web-service with REST method. The client sends a number of values/parameters in the form of HTTP POST to the ESPAY system to get the transaction that have been completed.

API URL

Development : https://sandbox-api.espay.id/rest/billertools/gettransactioninfo
Production: https://api.espay.id/rest/billertools/gettransactioninfo

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

Get Payment Status Request Data:
Name Field Attribute Mandatory Description
rq_uuid ANS 255 Yes Request Identifier. Unique ID to identify the request message with other messages.
Formula : sender_id+ Unique ID
Example: ESPAY123ABC-456DEF
rq_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
Example: 2017-12-17 12:22:32
sender_id AN...32 Yes Unique client identities listed in the ESPAY system (Will be provided for each client).
password AN...32 Yes The client’s access password that is registered with ESPAY. (Will be determined according to agreement)
signature ANs...128 Yes Signature
ref_id AN...32 Yes Reference ID obtained on Bill Payment API

Upon request, client will get JSON response. Example as follows:

Get Payment Status Response Data:
Name Field Attribute Mandatory Description
rq_uuid ANS 255 Yes Request Identifier. Unique ID to identify the request message with other messages.
Formula : sender_id+ Unique ID
Example: ESPAY123ABC-456DEF
rq_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
Example: 2017-12-17 12:22:32
error_code ANS...4 Yes Error Code(see Table Error)
error_desc AN...32 Yes Error Description
product_code ANs...16 No Product code
order_id AN...64 No Order ID / Payment ID

Get Biller Products

Performed through web-service with REST protocol. The client sends a number of values / parameters in the form of HTTP POST to get a list of supported products.

API URL
Development : https://sandbox-api.espay.id/rest/billertools/getregisteredproducts
Production : https://api.espay.id/rest/billertools/getregisteredproducts

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

Get Biller Product Request Data:
Name Field Attribute Mandatory Description
rq_uuid ANS 255 Yes Request identifier. Unique ID to identify these messages with other messages
rq_datetime ANS 19 Yes Date and time in ESPAY application server when messages sent
sender_id AN 32 Yes Client’s unique ID which is registered in ESPAY. (Will be provided for each client)
password AN 32 Yes The client’s access password that is registered with ESPAY. (Will be determined according to agreement)

Upon request, client will get JSON response from biller. Example as follows:

Get Biller Product Response Data:
Name Field Attribute Mandatory Description
rq_uuid ANS 255 Yes Request ID. Unique ID for identifying the request message with another message.
Formula : sender_id+ Unique ID
Example: ESPAY123ABC-456DEF
rq_datetime ANS 19 Yes Date and time on the client application server where 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. 0000 = Success, otherwise it will fail.
error_desc ANS 128 No Error description if present
product ANs 16 No The desired product that supported. Look the product

Get Balance

Performed through web-service with REST protocol. The client sends a number of values / parameters in the form of HTTP POST to obtain balance information

API URL
Development : https://sandbox-api.espay.id/rest/billertools/getbalance
Production : https://api.espay.id/rest/billertools/getbalance

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

Get Balance Request Data:
Name Field Attribute Mandatory Description
rq_uuid ANS 255 Yes Request Identifier. Unique ID to identify the request message with other messages.
rq_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
sender_id AN 32 Yes Given by ESPay, this is used to identify the sender of each request
password AN 32 Yes Password is used for identification and validation mechanism by merchant to identify requests completely derived from the ESPAY application
signature AN 32 Yes Signature required for validation by merchant

Upon request, client will get JSON response. Example as follows:

Get Balance Response Data:
Name Field Attribute Mandatory Description
rq_uuid ANS 255 Yes Request ID. Unique ID for identifying the message with other messages.
Formula : sender_id + unique ID
Example : SENDERID123ABC-DEF456
rs_datetime ANS 19 Yes Date and time of the server application server where the response message is sent
Format : YYYY-MM-DD HH:MM:SS
Example : 2014-12-17 12:30:45
error_code ANS 4 Yes Error code. 0000 = Success, otherwise it will fail.
error_desc ANS 128 No Error description
balance Total balance in the account

Get Provider Phone Number

Performed through web-service with REST protocol. The client sends a number of values / parameters in the form of HTTP POST to obtain provider information

API URL
Development : https://sandbox-api.espay.id/rest/billertools/getmno
Production : https://api.espay.id/rest/billertools/getmno

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

Get Provider Phone Number Request Data:
Name Field Attribute Mandatory Description
rq_uuid ANS 255 Yes Request Identifier. Unique ID to identify the request message with other message.
rq_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
sender_id AN 32 Yes Provided by ESPay, this is used to identify the sender of each request
password AN 32 Yes Password is used for identification and validation mechanism by merchant to identify requests completely derived from the Espay application
phone_num AN 15 Yes Cell phone Number
Ex: +6281284620888 / 6281284620888 / 081284620888

Upon request, clients will get JSON response. Example as follows:

Get Provider Phone Number Response Data:
Name Field Attribute Mandatory Description
rq_uuid ANS 255 Yes Request ID. Unique ID for identifying the message with other messages.
rs_datetime ANS 19 Yes Date and time on the server application server when the response message is sent
Format : YYYY-MM-DD HH:MM:SS
Example : 2014-12-17 12:30:45
error_code ANS 4 Yes error message. 0000 = Success, otherwise it fails
error_desc ANS 128 No Error description if present
operator Details of the intended operator

Table Error

Response Code Description
0000 COMPLETED SUCCESFULLY
9999 SUSPECT / TIMEOUT
802 MAX/MIN PAYMENT AMOUNT EXCEEDED
801 TRANSACTION ERROR, INQUIRY DATA NOT FOUND
800 INSUFFICIENT FUNDS
614 UNABLE TO PROCESS TRANSACTION AT CERTAIN HOURS
612 UNABLE TO PROCESS TRANSACTION, PLEASE TRY AGAIN LATER
611 TRANSACTION DECLINE, PLEASE CONTACT YOUR ADMINISTRATOR
610 YOU CAN PERFORM THE SAME TRANSACTION IN 5 MINUTES
601 IP ADDRESS REJECTED / UNREGISTERED
406 INQUIRY DATA IS INVALID
405 PRODUCT DENIED
404 PRODUCT NOT AVAILABLE
403 AMOUNT IS NOT SET
300 INQUIRY NOT AVAILABLE
210 DUPLICATE UUID
205 INVALID REQUEST
040 BILLER SYSTEM MALFUNCTION
09 REQUEST IN PROGRESS
13 TXN AMT IS DIFFER WITH TOTAL BILL AMT
14 PAYMENT NBR NOT FOUND
15 NO SUCH ISSUER
17 SERVICE UNAVAILABLE (MAINTENANCE)
18 DISPUTE
22 SUSPECTED MALFUNCTION
34 SUSPECTED FRAUD
36 RESTRICTED
60 CARD ACCEPTOR CONTACT ACQUIRER
61 TRANSACTION EXCEEDS APPROVAL AMOUNT LIMIT
64 ORIGINAL AMOUNT INCORRECT
65 EXCEED FREQUENCY LIMIT
66 CARD ACCEPTOR, CALL ACQUIRER SECURITY
67 HOT CARD RETAIN CARD
68 LATE RESPONSE FROM BILLER
72 VOUCHER / DENOM NOT AVAILABLE 
Sample Request: Bill Inquiry

		POST /rest/biller/inquirytransaction HTTP/1.0
		Host: 116.90.162.170:10809
		Content-Length: 108
		Authorization: Basic QWxhZGRpbjpTbWVsYW5h
		Content-type: application/x-www-form-urlencoded

		rq_uuid=5441217&rq_datetime=2014-12-09 17:53:20&sender_id=SENDERID&order_id=9900990099&product_code=STCKAI

    

Sample Response: Bill Inquiry

		{
		    "rq_uuid":"5441217",
		    "rs_datetime":"2014-12-09 17:53:24",
		    "error_code":"0000",
		    "error_desc":"COMPLETED SUCCESFULLY",
		    "order_id":"9900990099",
		    "amount":"35300000",
		    "bill_amount":"35000000",
		    "admin_fee":"300000",
		    "description":"Biaya admin fee Rp 3.000",
		    "data":{
		        "ticket_no":"9900990099",
		        "reserved1":"",
		        "reserved2":"",
		        "bill_total":"1",
		        "passenger_name":"Andreanus Hendy",
		        "train_number":"KA 16",
		        "train_name":"ARGO GEDE",
		        "train_seat":"39A",
		        "info":[
		            {
		                "trip_info":"JKTSBY0000",
		                "trip_info_extended":"23072340"
		            }
		        ]
		    }
		}

Sample Request: Bill Payment:


		POST /rest/biller/paymentreport HTTP/1.0
		Host: 116.90.162.170:10809
		Authorization: Basic QWxhZGRpbjpTbWVsYW5h
		Content-Length: 124
		Content-type: application/x-www-form-urlencoded

		rq_uuid=4328662&rq_datetime=2014-12-11 15:21:15&sender_id=SENDERID&order_id=9900990099&product_code=STCKAI&amount=35000000&data={"ticket_no":"9900990099","reserved1":"","reserved2":"","bill_total":"1","passenger_name":"Andreanus Hendy","train_number":"KA 16","train_name":"ARGO GEDE","train_seat":"39A","info":[{"trip_info":"JKTSBY0000","trip_info_extended":"23072340"}]}


	    
	
Sample Response: Bill Payment:

		{
		    "rq_uuid":"4328662",
		    "rs_datetime":"2014-12-09 15:21:15",
		    "error_code":"0000",
		    "error_desc":"COMPLETED SUCCESFULLY",
		    "order_id":"9900990099",
		    "description":"Pembayaran tiket KAI",
		    "data":{
		        "ticket_no":"9900990099",
		        "reserved1":"",
		        "reserved2":"",
		        "bill_total":"1",
		        "passenger_name":"Andreanus Hendy",
		        "train_number":"KA 16",
		        "train_name":"ARGO GEDE",
		        "train_seat":"39A",
		        "info":[
		            {
		                "trip_info":"JKTSBY0000",
		                "trip_info_extended":"23072340"
		            }
		        ]
		    }
		}

	
Raw Request Example: Inqury Bill Payment Status:


		POST /rest/billertools/gettransactioninfo HTTP/1.0
		Host: api.espay.idContent-Length: 197
		Authorization: Basic QWxhZGRpbjpTbWVsYW5h
		Content-type: application/x-www-form-urlencoded
		rq_uuid=ESPAY123ABC-456DEF&rq_datetime=2017-12-17
		12:22:32&sender_id=ESPAY&password=espaypass&signature=c26a2a9901941a2eefd
		9c529c38822fabbd470c2693d40465616fa3fd58a0b26&ref_id=TX1712171209991FA


	    
	
Raw Response Example: Inqury Bill Payment Status:

		{
		  "rq_uuid":"ESPAY123ABC-456DEF,
		  "rq_datetime":"2017-12-17 12:22:32",
		  "error_code":"0000",
		  "error_desc":"COMPLETED SUCCESFULLY",
		  "product_code":"SVHTS50",
		  "order_id":"081218816222",
		  "status_code":"00",
		  "status_desc":"SUCCESS",
		  "serial_number":"41001621787608"

		}
	
Sample Request: Get Biller Products:

		POST /rest/billertools/getregisteredproducts HTTP/1.0
		Host: https://sandbox-api.espay.id
		Content-Length: 108
		Content-type: application/x-www-form-urlencoded

		rq_uuid=5441217&rq_datetime=2014-12-09
		17:53:20&sender_id=SENDERID&password=590biller
	    
	
Sample Response: Get Biller Products:

	{
	    "rq_uuid":"5441217",
	    "rs_datetime":"2014-12-09 17:53:24",
	    "error_code":"0000",
	    "error_desc":"COMPLETED SUCCESFULLY",
	    "products":[
	      {
	        "product_code":"SINCBN",
	        "product_name":"CBN"
	      }
	      {
	        "product_code":"SCCCTB",
	        "product_name":"CITIBANK CREDIT CARD"
	      }
	      {
	        "product_code":"STBFRM",
	        "product_name":"FIRST MEDIA (d/h KABELVISION)"
	      }
	      {
	        "product_code":"STCGRI",
	        "product_name":"GARUDA INDONESIA"
	      }
	      {
	        "product_code":"SVHTS50",
	        "product_name":"TELKOMSEL 50000""
	      }
	      {
	        "product_code":"STBTOP",
	        "product_name":"TOP TV"
	      }
	      {
	        "product_code":"SLYYTV",
	        "product_name":"YES TV"
	      }
	        ]
	}
	
Sample Request: Get Balance:


		POST /rest/billertools/getbalance HTTP/1.1
		Host: sandbox-api.espay.id
		Content-Length: 176
		Authorization: Basic RU5TRVZBTDprVXVYUjVNUkRtcHZrY1lk
		Content-Type: application/x-www-form-urlencoded

		rq_uuid=getbalance018&rq_datetime=2018-01-15 10:33:43&sender_id=SENDERID&password=p45w0rd&
		signature=db420be770fef07ebdc23378456a1c6b7c6b3cd9aadef39cb2784f0bb48bf869


	    
	
Sample Response: Get Balance:

		{
		  "rq_uuid":"getbalance09",
		  "rq_datetime":"2018-01-15 10:45:50",
		  "error_code":"getbalance09",
		  "error_desc":"2018-01-15 10:45:50",
		  "balance":"16127451.00"
		}

	
Sample Request: Get Provider Phone Number:


		POST /rest/billertools/getmno HTTP/1.1
		Host: sandbox-api.espay.id
		Content-Length: 176
		Authorization: Basic RU5TRVZBTDprVXVYUjVNUkRtcHZrY1lk
		Content-Type: application/x-www-form-urlencoded

		rq_uuid=5326eaca-f715-f39f-36e1-432b1253cf49&rq_datetime=2018-01-16 15:07:20&sender_id=SENDERID&password=p45w0rd&phone_num=+6281284620888


	    
	
Example Response Get Provider Phone Number:

		
		{
		  "rq_uuid":"5326eaca-f715-f39f-36e1-432b1253cf49",
		  "rs_datetime":"2018-01-16 15:07:20",
		  "error_code":"0000",
		  "error_desc":"COMPLETED SUCCESFULLY",
		  "operator":{
		    "group_code":"GSVHTS",
		    "provider_name":"TELKOMSEL"
		  }
		}