Top Up VA

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:

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:

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)

Unique ID send from Bank

AdditionalData

String (100)

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:

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:

3c60f285e16f47919e9748f76425351c-ab2554ba2a6e4eb68dde13b15f03f25b

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:

1a47c5c2c1f04537bada8db37a55d6b5-e38c19d07d854594878d42fcad90fdf9

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 :

Path -> eg: /e2pay-controller/va/service/create
Verb -> eg: POST
PaymentId -> eg: 28
MerchantCode -> eg: ID00001
RefId / RefNo -> eg: XY0000000001 (in "Create VA" please use RefNo)
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

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

(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

Bank

Permata VA

Alfamart

CIMB VA

BCA VA

BRI VA

Mandiri VA

List Status Code

API Name

Code

Description

Inquiry

Transaction Success

Invalid Request

Provider Problem

Timeout

Connection Failure

Bill not found

Bill Already Paid

Bill expired

General Failure

Topup

Transaction Success

Provider Problem

Timeout

Connection Failure

Bill not found

Bill Already Paid

Bill expired

General Failure

Create VA

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)

Last updated 1 year ago

hashtagFlow Chart

hashtagInquiry

hashtagDescription

hashtagDirection

hashtagM/O

hashtagCanonical Path

hashtagRequest Header

hashtagRequest Body

hashtagResponse Body

hashtagTop Up

hashtagDescription

hashtagDirection

hashtagM/O

hashtagCanonical Path

hashtagRequest Header

hashtagRequest Body

hashtagResponse Body

hashtagCreate VA

hashtagDescription

hashtagDirection

hashtagM/O

hashtagCanonical Path

hashtagRequest Header

hashtagRequest Body

hashtagResponse Body

hashtagSignature

hashtagPayment ID

hashtagList Status Code

hashtagAdditional Note for BRI Virtual Account

Flow Chart

Inquiry

Description

Direction

M/O

Canonical Path

Request Header

Request Body

Response Body

Top Up

Description

Direction

M/O

Canonical Path

Request Header

Request Body

Response Body

Create VA

Description

Direction

M/O

Canonical Path

Request Header

Request Body

Response Body

Signature

Payment ID

List Status Code

Additional Note for BRI Virtual Account