Top Up VA

Flow Chart

Cross Functional Flow Chart

Inquiry

Description

This functionality is to get customer/transaction details from merchant.

Direction

From E2Pay to Merchant (H2H).

M/O

Mandatory

Canonical Path

Define by Merchant. If using public internet please use HTTPS/TLS for secure communication protocol layer

Request Header

Key	Value
Content-Type	application/json

Request Body

Field	Type (Size)	Mandatory	Description
Request Type	String (7)	Yes	"inquiry".
PaymentId	Numeric	Yes	Refer to chapter 5.
MerchantCode	String (20)	Yes	Will be given by E2Pay.
RefId	String (30)	Yes	Unique E2Pay reference number.
BINCode	String (4)	Yes	BIN code from bank
VANumber	String (16)	Yes	Can be generated from customer’s Mobile Phone or Bill Number with the addition of BIN code as prefix. Please notice : If concatenation of BIN code and customer’s Mobile Phone or Bill Number has more than 16 digits in length, then the value of customer’s Mobile Phone or Bill Number should be adjusted or truncated. Taken only the last 10 or 12 digits ( depends on the length of BIN code ). Example : BIN Code 8452 Mobile Phone or Bill Number in merchant side is 08789959611889. Then Mobile Phone or Bill Number that should be used in VA number is 789959611889
Timestamp		Yes	Date and time
Signature		Yes	SHA256-HMAC hex encoded signature (refer to chapter 4)

Example Request: { "RequestType":"Inquiry", "PaymentId":22, "MerchantCode":"ID00001", "RefId":"A00000001", "BINCode":"8452", "VANumber":"8452789959611889", "Timestamp":"20200820230330", "Signature": "d9449b380eca56bd4d0e5241dc4613082b36b328b37bb2d9a28f91f58bc1b311" }

Response Body

Field	Data Type	Mandatory	Description
ResponseType	String (7)	Yes	"Inquiry"
PaymentId	Numeric	Yes	Echo from request
MerchantCode	String (20)	Yes	Echo from request
RefId	String (30)	Yes	Echo from request
UserName	String (100)	Yes	Customer name
UserContact	String (20)	Yes	Customer contact number
UserEmail	String (100)	Yes	Customer email for receiving receipt
Amount	Numeric	Yes	If open payment set to 0, if closed payment set amount here
RefNo	String (18)	Yes	Unique merchant transaction number / Order ID
Status	String (18)	Yes	00 if successful else error

Example response: { "ResponseType":"Inquiry", "PaymentId":22, "MerchantCode":"ID00001", "RefId":"A00000001", "UserName":"Cupcake and Dino", "UserContact":"0811500100", "UserEmail":"[e-mail]", "Amount":10000, "RefNo":"XY0000000001", "Status":"00", }

Top Up

Description

This functionality is to notify merchant for incoming money transfer.

Direction

From E2Pay to Merchant (H2H).

M/O

Mandatory

Canonical Path

Define by Merchant. If using public internet please use HTTPS/TLS for secure communication protocol layer.

Request Header

Key	Value
Content-Type	application/json

Request Body

Field	Type (Size)	Mandatory	Description
RequestType	String (7)	Yes	"Topup"
PaymentId	Integer	Yes	Refer to chapter 5
MerchantCode	String (20)	Yes	Will be given by E2Pay
RefId	String (30)	Yes	Unique E2Pay reference number for transaction chain. The same value, taken from Inquiry request will be sent.
RefNo	String (18)	Yes	Reference number from merchant. Value taken from field "RefNo" in Inquiry response
VANumber	String (16)	Yes	Customer assigned static VA number
Amount	Numeric	Yes	Transaction amount
UserName	String (100)	Yes	Customer name
BankRefNo	String (50)	C	Unique ID send from Bank
AdditionalData	String (100)	O	Reserved field. For later use
TimeStamp	String (14) yyyymmddhhmmss	Yes	Date and time
Signature	String (100)	Yes	SHA256-HMAC hex encoded signature (refer to chapter 4)

Example Request: { "RequestType":"Topup", "PaymentId":22, "MerchantCode":"ID00001", "RefId":"A00000001", "RefNo":"XY0000000001", "VANumber":"8452789959611889", "Amount":"10000", "UserName":"Cupcake and Dino", "BankRefNo":"A00000001", "AdditionalData":"", "Timestamp":"20200820230335", "Signature": "4bad9bfaa17214dcc48619058ff98eccefa51a20981ba7aed290ab6b6a4bdb77" }

Response Body

Field	Data Type	Mandatory	Description
ResponseType	String (7)	Yes	"Topup"
PaymentId	Numeric	Yes	Echo from request
MerchantCode	String (20)	Yes	Echo from request
RefId	String (30)	Yes	Echo from request
Amount	Numeric	Yes	Transaction amount
RefNo	String (18)	Yes	Echo from request
Status	String (8)	Yes	00 if successful else error

Example response:
{ "ResponseType":"Topup", "PaymentId":22, "MerchantCode":"ID00001", "RefId":"A00000001", "Amount":10000, "RefNo":"XY0000000001", "Status":"00", }

Create VA

Description

This functionality is to create VA number to show to merchant's customer

Direction

From Merchant to E2Pay (H2H)

M/O

Optional

Canonical Path

/e2pay-controller/va/service/create

Request Header

Key	Value
Content-Type	application/json

Request Body

Field	Type (Size)	Mandatory	Description
RequestType	Stirng (7)	Yes	"CreateVA"
PaymentId	Integer	Yes	Refer to chapter 5
MerchantCode	String (20)	Yes	Will be given by E2Pay
RefNo	String (18)	Yes	Unique merchant to number
CustomerKey	String (12)	Yes	Customer assigned ID. Should be unique per customer. Will be used as VA number element
UserName	String (100)	Yes	Customer name
UserContact	String (20)	Yes	Customer contact number
UserEmail	String (100)	Yes	Customer email for receiving receipt
TimeStamp	String (14) yyyymmddhhmmss	Yes	Date and time
Signature	String (100)	Yes	SHA256-HMAC hex encoded signature (refer to chapter 4)

Example request:
{ "RequestType":"CreateVA", "PaymentId":22, "MerchantCode":"ID00001", "RefNo":"XY0000000001", "CustomerKey":"15426598", "UserName":"Cupcake and Dino", "UserContact":"0811500100", "UserEmail":"[e-mail]", "Timestamp":"20200820230330", "Signature": "c946a7e3e09dfb97864e1a781ea73c6ba4817835fb254402f4f733bbf79ff1a1" }

Response Body

Field	Type (Size)	Mandatory	Description
ResponseType	String (7)	Yes	"CreateVA"
RefNo	String (18)	Yes	Echo from request
Status	String (8)	Yes	00 if successful else error
VirtualAccount	String (16)	Yes	VA Number that will be used for transaction. One of its component is taken from CustomerKey value combined with BIN code from Bank. Please notice : If concatenation of BIN code and CustomerKey has more than 16 digits in length, then the value of CustomerKey will be adjusted or truncated. Taken only the last 10 or 12 digits ( depends on the length of BIN code ).
			Example : BIN Code 8452 CustomerKey in merchant side is 08789959611889. Then CustomerKey that will be used in VA number is 789959611889

Example Response:
{ "ResponseType":"CreateVA", "RefNo":"A00000001", "Status":"00", "VirtualAccount":"8452000015426598" }

Signature

Digital signature ensures reliability and anti-repudiation of data transmitted. Signature is generated by the service requestor, and verified by the service recipient.

The signature data will be signed with SHA256-HMAC algorithm using client Secret and then encoded with Base64. The signature is formed as following :

1. Path -> eg: /e2pay-controller/va/service/create

2. Verb -> eg: POST

3. PaymentId -> eg: 28

4. MerchantCode -> eg: ID00001

5. RefId / RefNo -> eg: XY0000000001 (in "Create VA" please use RefNo)

6. Timestamp -> eg: 20231720 ( in format yyyymmddhhmmss )

The fields must set in the following order, (Path + Verb + PaymentId + MerchantCode + RefId / RefNo + Timestamp) signature example :

Plain text :

Path=/e2pay-controller/va/service/create+Verb=POST+PaymentId=28+MerchantCode=I D00001+RefNo=XY0000000001+Timestamp=20200820231720

Merchant key : appleKey

Hash value : Hex encode (SHA256-HMAC(plain_text, merchant_key))

Hash value : 8f2a6ac8222119e4cb8352541bc2c83d30e52229cdaf335d666c7cf0f9e

Example in Java

import javax.crypto.Mac; 
import javax.crypto.spec.SecretKeySpec; 
import org.apache.commons.codec.binary.Hex;

public static String hashSha2HMAC(String data, String key) throws Exception
{ 
    Mac sha256_HMAC = Mac.getInstance("HmacSHA256"); byte[]
    keyByteArr = key.getBytes();
    SecretKeySpec secret_key = new SecretKeySpec(keyByteArr,"HmacSHA256"); 
    sha256_HMAC.init(secret_key); 
    return Hex.encodeHexString(sha256_HMAC.doFinal(data.getBytes("UTF-8")));
}

Example in PHP

(PHP 5 >= 5.1.2, PHP 7, PECL hash >= 1.1) hash_hmac ( string $algo , string $data ,
string $key [, bool $raw_output = FALSE ] ) : string

<?php
echo hash_hmac(
    'sha256',
    'plain_text',
    'encryption_key'
); ?>

Payment ID

ID	Bank
22	Permata VA
24	Alfamart
37	CIMB VA
38	BCA VA
40	BRI VA
44	Mandiri VA

List Status Code

API Name	Code	Description
Inquiry	00 10 11 12 13 14 15 16 17	Transaction Success Invalid Request Provider Problem Timeout Connection Failure Bill not found Bill Already Paid Bill expired General Failure
Topup	00 18 19 20 21 22 23 24	Transaction Success Provider Problem Timeout Connection Failure Bill not found Bill Already Paid Bill expired General Failure
Create VA	00 pge1005 pge2009 pge2102 pge2202 pge2203	Transaction Success Error database General Error Unknown Payment ID Missing required parameter Invalid Signature

Additional Note for BRI Virtual Account

Minimum User Contact: 10 Character (Only Number)

Maximum User Contact: 14 Character (Only Number)