BCVN-EDC CONTROLLER

API Programming Guide

Version: 1.1.3 [EN]

TABLE OF CONTENTS

1 Document Management .................................................................................................................. 3

1.1 Document Overviews ........................................................................................................ 3
1.2 History .................................................................................................................................. 3
1.3 Standard Terminology / Common Terms / Abbreviations ......................... 3
2 Introduction................................................................................................................................... 4
3 Function Specification ........................................................................................................... 5
3.1 Overview ................................................................................................................................ 5
3.2 JSON KEY definition in transactions ............................................................... 7
3.3 JSON String (Send from EDCC, POST method) ................................................. 8
3.4 EDCC Service Information Checking .................................................................... 9
3.5 Third Party Key Checking........................................................................................ 10
3.6 SALE ....................................................................................................................................... 11
3.7 VOID ....................................................................................................................................... 14
3.8 SETTLEMENT ......................................................................................................................... 17
3.9 CHECK RESULT .................................................................................................................... 20
3.10 GET CONNECTION............................................................................................................ 22
3.11 HEALTH CHECK ................................................................................................................ 24
3.12 GET TRANSACTION ......................................................................................................... 25
3.13 QR Code ............................................................................................................................ 28
3.14 Print Receipt .............................................................................................................. 31
4 Encrypt/Decrypt Message ...................................................................................................... 34
4.1 Encrypt-Decrypt Message Code in Java ........................................................... 34
4.2 Encrypt-Decrypt Message Code in C# ................................................................ 35
5 Response Code Reference ...................................................................................................... 37
1 Document Management

1.1 Document Overviews

- Writer: Bao.Ho, Hai.Nguyen

- Dept: RD-CS
- Created day: Jun-2018
- Language: English

1.2 History

Versio Date Content Name

n
1.0.0 15-Aug-2017 EDCC APIs Bao.Ho,
Hai.Nguyen
1.0.1 08-Sep-2017 EDCC APIs Bao.Ho,
Hai.Nguyen
1.0.2 12-Sep-2017 Update VOID and GET TRANSACTION Khoa.Cao
1.0.3 15-Sep-2017 Update CHECK RESULT Khoa.Cao
1.0.4 28-Sep-2017 Update response message from EDCC Khoa.Cao
1.0.5 20-Jun-2018 Udpate QR Code message Khoa.Cao,
Hai.Nguyen
1.0.6 02-Sep-2018 Update the flow SALE/VOID/SETTLEMENT Nhi Tran,
Hai.Nguyen
1.0.7 22-Sep-2018 Translate from EDCC APIs Version 1.0.6 Sieu.Huynh
1.0.8 17-Jan-2019 Add print receipt Hai.Nguyen
1.0.9 18-Nov-2019 Add check EDC’s health Hai.Nguyen
1.1.0 16-Jan-2020 Adjust VOID transaction Hai.Nguyen
1.1.1 31-Jan-2020 Adjust SETTLEMENT transaction Hai.Nguyen
1.1.2 27-Aug-2021 Add description for Additional Data Hai.Nguyen
1.1.3 05-Jul-2023 Add description for Additional_Data/ Hai.Nguyen
Additional_print for QR Code

1.3 Standard Terminology / Common Terms / Abbreviations

Term Description
EDC Electronic Data Capture
EDCC EDC Controller
ECR Electronic Cash Register
REQMsg Request Message
 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

2 Introduction

EDC Controller (EDCC) is a utility system for specialized

applications on ECR (Electronic Cash Register) machines which communicate
with Electronic Data Capture (EDC) terminal automatically. The
information of a transaction is converted directly from ECR to EDC via
EDCC without the need to manually enter data to help reduce the human
error (cashier) and reduce the processing time. Figure 1 shows the
connection diagram of the EDCC system with payment devices and devices
running ECR applications.

Figure 1: EDCC – ECR diagram

EDCC is built on Microsoft's .NET 4.6 technology, which includes the

following main components:
• EDCC-Core: transaction processing, data storage, and message
forwarding between EDC and ECR.
• Web-APIs: provide interface to ECR to send request to system as Web
service.
• Web-APP: Provides a web interface for interacting with users.
• TCP-Endpoint: Provides means of connecting to EDC as a Windows
service.
The documentation only describes the Web-APIs component, which is
provided to ECR application developers who build modules integrated with
the EDCC system. In particular, the document describes in detail each
function used to connect, exchange data, as well as process and manage
transactions.

Version 1.1.3 [EN] Page 4 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

3 Function Specification

3.1 Overview

According to the connection model in Figure 1, the overall processing

flow of a transaction is as follows:

• A specific transaction (Ex: SALE, VOID, SETTLEMENT) generated by the

cashier on ECR applications from the Merchant Outlet and transferred
to the Merchant Application Server (Merchant Data Center).

• The Application Server packs transaction information into a Request

Message - REQMsg in the correct format and then encrypts it to EDCC
via Web-APIs using the POST method.

• EDCC decodes and validates data. If the data is valid, then EDCC
analyzes the REQMsg to extract the EDC information that the
transaction needs to send.

• REQMsg is changed to the appropriate format before sending to the

corresponding EDC to process the transaction and wait for the result
to return.

• EDC performs the transaction, receives the return from Bank

Acquiring and transfers the transaction result to the EDCC.

• EDCC records the transaction and forwards the result to the merchant
application server.

• The Application Server extracts transaction information, stores it

into the system and sends the results on the ECR application to
inform the cashier and customer.

In order to send a request message from the ECR to EDCC, the ECR (3rd
application) should be generated by EDCC and assigned a pair of
identifiers and a {3-Id, 3rd-Key} pair. In this, the 3rd-Id is used to
identify the ECR and 3rd-Key applications is used to encrypt and
decrypt data during the exchange with EDCC. The message exchanges
between the Application Server and EDCC before encoding is organized in
JSON format. The path for calling the EDCC service like this:

ROOT-URL/API-INDICATOR/REQUEST-MESSAGE

• ROOT-URL: [required], is the IP address or domain name of the server

used to implement the EDCC and service port.
For example, http://edcc.BCCard.com.vn or http://127.0.0.1:4946.

• API-INDICATOR: [required], specifies the APIs to link to the

service. With EDCC, the default value when installed is api/action.

Version 1.1.3 [EN] Page 5 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

• REQUEST-MESSAGE: [optional], contains the information to call the

service. In the case of calling the service using the POST method,
the value of this component is an empty string.

• Two 'Requirement Designator' values are used to define standard

transactions. These are detailed with their meanings below:
o M: Mandatory - This item must be present in all data
transactions -used for critical data which is not mandatory in
the standard, but in the opinion of the implementation guide
designers are essential for correct operation of the
transaction set.
o O: Optional - This item may or may not be present in a data
transaction·- used for data which may or may not be needed by
any given implementation of the transaction set.

Version 1.1.3 [EN] Page 6 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

3.2 JSON KEY definition in transactions

# Keyname Meaning Para Value

Type
1 APP Application Name Fix "PAYMENT_STD"
2 EVENT Transaction Type Change
3 CLIENT_ID Bank ID Fix
4 MERCHANT_ID Merchant ID Change
5 MERCHANT_OUTLET_ID Merchant Outlet Change
6 MERCHANT_CODE Merchant Code Change
7 SERIAL_NUMBER Serial EDC Change
8 ADD_DATA Additional Data Change
9 ADD_PRINT Additional Print Change
10 AMOUNT Amount Change
11 STAFF_ID Staff ID Change
12 TERMINAL_ID Terminal ID Change
13 CURRENCY_CODE Currency Code Change
14 ORDER_ID Order Id Change

Table 1: Keyword definition

Version 1.1.3 [EN] Page 7 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

3.3 JSON String (Send from EDCC, POST method)

For services that use the POST method to send a request to EDCC, the
send-message must be packaged in the following format:
• = {"KEY": "ThirdPartyID", "VALUE": "MessageContent"}
o KEY: is 3rd-Id
o VALUE: is the encrypted string of message content. This
message needs to be processed with 3rd-Key. Depending on the
type of transaction, the content of the message to be
processed will be different. This content is also formatted
using a JSON string with key-value pairs matching every
transaction.

The following is a detailed description of the functionality provided

to the ECR application developer when using the EDCC service. In the
example for each function, the EDCC service is installed on the server
whose IP address is 192.168.5.80, the Web-APIs port is 8095, and the
API-INDICATOR is /action/.

Version 1.1.3 [EN] Page 8 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

3.4 EDCC Service Information Checking

• Functionality: Check that the EDCC service is running normally

and what the EDCC version is running. This feature helps ECR
application developers make sure the EDCC service is fine
(working).
• URL: http://ROOT-URL/API-INDICATOR/
• Method: GET
• Request: NULL
• Response: Returns the version information of the EDDC service.
• Example:
o URL: http://192.168.5.80:8095/action/
o Request: NULL
o Response: "Copyright © 2017 BCCard (Vietnam) Co., Ltd. EDC
Controller Version: 2.0. Build Date: 2017/09/28."

Version 1.1.3 [EN] Page 9 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

3.5 Third Party Key Checking

• Functions: Check whether 3rd-Id and 3rd-Key are correct.

• URL: http://ROOT-URL/API-INDICATOR/checkkey
• Method: GET
• Request: /3rd-Id/Encrypted-Data. Where Encrypted-Data is the 3rd-
Key encoding value of the "EDCC" string.
• Response: Returns the check key.
o If true, the result will be: EDCC
o If wrong Key, will receive the message: THIRD PARTY KEY IS
INVALID
o If the wrong ID, will receive the message: THIRD PARTY ID IS
INVALID
• Example:
o URL: http://192.168.5.80:8095/action/checkkey
o Request: /95462196/5a707a5436634c41556d413d
o As described above, if "95462196" is a valid 3rd-id and is
encoded by the corresponding 3rd-Key, then the return value
is the string "EDCC".

Version 1.1.3 [EN] Page 10 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

3.6 SALE

• Function: Send request processing a SALE transaction from ECR

machine to EDC machine.
• URL: http://ROOT-URL/API-INDICATOR/
• Method: POST
• Transaction details: To send the transaction to EDCC from the ECR
must go through two steps and must use the following two events:
"EVENT": "SALE" and "EVENT": "CHECK_ RESULT"
o Step 1: ECR sends the "EVENT" request: "SALE" to EDCC and
receives the response containing the key
o Step 2: ECR sends "EVENT" request: "CHECK_ RESULT" to EDCC
with this key. (Repeat step 2 repeatedly for 1 to 5 seconds
apart until you receive the result.) See more details for
the CHECK RESULT transaction
• Request Step 1: Same as described in Section 3.3. Where the
content of the request message is a JSON string as follows:
{
"EVENT": "SALE",
"REF_ID": "",
"SERIAL_NUMBER": "",
"TERMINAL_ID": "",
"AMOUNT": "000015000000",
"CURRENCY_CODE": "704",
"STAFF_ID": "",
"ADD_PRINT": "",
"ADD_DATA": "",
"ORDER_ID": "",
"APP": "PAYMENT_STD",
"MERCHANT_OUTLET_ID":
"000000000000000071000",
"MERCHANT_ID": "000000000070000",
"CLIENT_ID": "1111"
}
Listing 1: SALE Request Message
The size and type of each field are shown in Table 2

Name Data Length Required Note

Type
APP String FIXED 12 M Hard Coding
EVENT String FIXED 4 M "PAYMENT_STD"
Hard Coding "SALE"
REF_ID String FIXED 8 M
TERMINAL_ID String FIXED 8 Terminal ID of Acquirer
SERIAL_NUMBER String 6-15 M
AMOUNT String FIX 12 O Amount must be greater
than one. Example:
125.000 VND --
>000012500000
$2.35 -->000000000235
CURRENCY_CODE String FIXED 3 M VND: 704, USD: 840
STAFF_ID String MAX 8 O
ADD_DATA String MAX 100 O Format: Tag-Length-Value
Ex: 01030030206876543
Param 01: 0103003
Param 02: 0206876543

Version 1.1.3 [EN] Page 11 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

ADD_PRINT String MAX 100 O

ORDER_ID String MAX 100
MERCHANT_OUTLET_ID String FIXED 21 M
MERCHANT_ID String FIXED 15 M
CLIENT_ID String FIXED 4 M

Table 2: SALE Request Message Data

• Response Step 1:
{
"RESULT": "Y",
"RESPONSE_CODE": "7000",
"DESCRIPTION": "Processing ... ",
"KEY": "0EF60A8890F44EBA8F68EB4BDC92F73B"
}
• Request Step 2: Continue sending a check result request with KEY
is the KEY that receive from the response in step 1. (See 3.9)
{
"EVENT": "CHECK_RESULT",
"KEY": "0EF60A8890F44EBA8F68EB4BDC92F73B"
}
• Response Step 2: Returns the result of the transaction SALE
associated with CHECK transaction, in the form of JSON encoded as
follows:
{
"APP": "PAYMENT_STD",
"RESULT": "Y",
"RESPONSE_CODE": "00",
"DESCRIPTION": "Transaction was processed
successfully.",
"MERCHANT_CODE": "312948798231748",
"TERMINAL_ID": "98719284",
"CURRENCY_CODE": "704",
"REF_ID": "77770001",
"SERIAL_NUMBER": "3J125611",
"AMOUNT": "000015000000",
"EVENT": "SALE",
"PAN": "483542******0348",
"NAME": "VISA CARDHOLDER",
"REF_NO": "834473175214",
"APPV_CODE": "320878",
"CARD_TYPE": "VISA",
"INVOICE": "000010",
"DATE": "0301",
"TIME": "145345",
"ADD_PRINT": "",
"ADD_DATA": "",
"ORDER_ID": "",
"STAFF_ID": ""
}
Listing 2: SALE Response Message

Version 1.1.3 [EN] Page 12 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

Name Data Type Length Note

APP String FIXED 12 Hard Coding "PAYMENT_STD"
EVENT String FIXED 4 Hard Coding "SALE"
RESULT String FIXED 1 Value: "Y" or "N"
RESPONSE_CODE String FIXED 4
DESCRIPTION String MAX 100
MERCHANT_CODE String FIXED 15
TERMINAL_ID String FIXED 8
CURRENCY_CODE String FIXED 3 VND: 704, USD: 840
REF_ID String FIXED 8
SERIAL_NUMBER String 6-15
AMOUNT String FIXED 12 VND: 000012500000 -> 125.000,00
USD: 000000000235 -> $2.35
PAN String FIXED 16
NAME String FIX 30
REF_NO String FIXED 12
APPV_CODE String FIXED 6
CARD_TYPE String MAX 10
INVOICE String FIXED 6
DATE String FIXED 4
TIME String FIXED 6
STAFF_ID String MAX 8
ADD_PRINT String MAX 100
ADD_DATA String MAX 100
ORDER_ID String MAX 100

Table 3: SALE Response Message Data

Version 1.1.3 [EN] Page 13 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

3.7 VOID

• Function: Send request to process a VOID transaction from ECR

machine to EDC machine.
• URL: http://ROOT-URL/API-INDICATOR/
• Method: POST
• Transaction Flow Details: To send a transaction to EDCC from the
ECR, you must go through two steps and use the following two
events: "EVENT": "VOID" and "EVENT": "CHECK_ RESULT"
o Step 1: ECR sends the "EVENT" request: "VOID" to EDCC and
receives the response containing the key
o Step 2: ECR sends "EVENT" request: "CHECK_ RESULT" to EDCC
with this key. (Repeat step 2 repeatedly for 1 to 5 seconds
apart until you receive the result.) See more details for
the CHECK RESULT transaction
• Request Step 1: Same as described in Section 3.3. Where the
content of the request message is a JSON string as follows:
{
"EVENT": "VOID",
"REF_ID": "",
"SERIAL_NUMBER": "",
"TERMINAL_ID": "",
"AMOUNT": "000015000000",
"CURRENCY_CODE": "704",
"INVOICE": "000001",
"AMOUNT_CONFIRM": "Y",
"STAFF_ID": "",
"ADD_PRINT": "",
"ADD_DATA": "",
"ORDER_ID": "",
"APP": "PAYMENT_STD",
"MERCHANT_OUTLET_ID": "000000000000000071000",
"MERCHANT_ID": "000000000070000",
"CLIENT_ID": "1111"
}
Listing 3: VOID Request Message

Name Data Type Length Required Note

APP String FIXED 12 M Hard Coding "PAYMENT_STD"
EVENT String FIXED 4 M Hard Coding "VOID"
REF_ID String FIXED 8 M
TERMINAL_ID String FIXED 8 Terminal ID of Acquirer
AMOUNT_CONFIRM String FIXED 1 O Value: "Y" or "N"
Default value: "Y"
"Y": cashier confirm on
terminal.
"N": without cashier
confirm on terminal.
SERIAL_NUMBER String 6-15 M
INVOICE String FIXED 6 M
AMOUNT String FIX 12 M Amount must be greater than
one. Example:
125.000 VND →000012500000
$2.35 →000000000235
CURRENCY_CODE String FIXED 3 M VND: 704, USD: 840
STAFF_ID String MAX 8 O

Version 1.1.3 [EN] Page 14 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

ADD_DATA String MAX 100 O Format: Tag-Length-Value

Ex: 01030030206876543
Param 01: 0103003
Param 02: 0206876543
ADD_PRINT String MAX 100 O
ORDER_ID String MAX 100 O
MERCHANT_OUTLET_ID String FIXED 21 M
MERCHANT_ID String FIXED 15 M
CLIENT_ID String FIXED 4 M
Table 4: VOID Request Message Data

• Response Step 1:
{
"RESULT": "Y",
"RESPONSE_CODE": "7000",
"DESCRIPTION": "Processing ... ",
"KEY": "0EF60A8890F44EBA8F68EB4BDC92F73B"
}
• Request Step 2: Continue sending a check result request with KEY
is the KEY that receive from the response in step 1. (See 3.9)
{
"EVENT": "CHECK_RESULT",
"KEY": "0EF60A8890F44EBA8F68EB4BDC92F73B"
}
• Response Step 2: Returns the VOID transaction result associated
with the CHECK RESULT transaction, in the form of an encrypted
JSON that has the following contents:
{
"APP": "PAYMENT_STD ",
"RESULT": "Y",
"RESPONSE_CODE": "00",
"DESCRIPTION": "Transaction was processed
successfully.",
"MERCHANT_CODE": "312948798231748 ",
"TERMINAL_ID": "98719284",
"CURRENCY_CODE": "704",
"REF_ID": "77770001",
"SERIAL_NUMBER": "3J125611",
"AMOUNT": "000015000000",
"EVENT": "VOID",
"PAN": "483542******0348",
"NAME": "VISA CARDHOLDER",
"REF_NO": "834473175214",
"APPV_CODE": "779848",
"CARD_TYPE": "VISA",
"INVOICE": "000010",
"DATE": "0301",
"TIME": "150932",
"ADD_PRINT": "",
"ADD_DATA": "",
"ORDER_ID": "",
"STAFF_ID": ""
}

Listing 4: VOID Response Message

Version 1.1.3 [EN] Page 15 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

Name Data Type Length Note

APP String FIXED 12 Hard Coding "PAYMENT_STD"
EVENT String FIXED 4 Hard Coding "VOID"
RESULT String FIXED 1 Value: "Y" or "N"
RESPONSE_CODE String FIXED 4
DESCRIPTION String MAX 100
MERCHANT_CODE String FIXEX 15
TERMINAL_ID String FIXED 8
CURRENCY_CODE String FIXED 3 VND: 704, USD: 840
REF_ID String FIXED 8
SERIAL_NUMBER String 6-15
AMOUNT String FIXED 12 VND: 000012500000 → 125.000,00
USD: 000000000235 → $2.35
PAN String FIXED 16 Card Number
NAME String FIX 30 Cardholder
REF_NO String FIXED 12
APPV_CODE String FIXED 6 Approval Code
CARD_TYPE String MAX 10
INVOICE String FIXED 6
DATE String FIXED 4 Transaction Date: MMDD
TIME String FIXED 6 Transaction Time: HHmmSS
STAFF_ID String MAX 8
ADD_PRINT String MAX 100
ADD_DATA String MAX 100
ORDER_ID String MAX 100

Table 5: VOID Response Message Data

Version 1.1.3 [EN] Page 16 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

3.8 SETTLEMENT

• Function: Send a request to process a SETTLEMENT transaction from

the ECR machine to the EDC machine.
• URL: http://ROOT-URL/API-INDICATOR/
• Method: POST
• Transaction Flow Details: To send EDCC transactions from ECR, you
must go through 2 steps and use the following two events:
"EVENT": "SETTLEMENT" and "EVENT": "CHECK_ RESULT"
o Step 1: ECR sends the "EVENT" request: "SETTLEMENT" to EDCC
and receives the response containing the key
o Step 2: ECR sends "EVENT" request: "CHECK_ RESULT" to EDCC
with this key. (Repeat step 2 repeatedly for 1 to 5 seconds
apart until you receive the result.) See more details for
the CHECK RESULT transaction
• Request Step 1: Same as described in Section 3.3. Where the
content of the request message is a JSON string as follows:
{
"EVENT": "SETTLE",
"REF_ID": "",
"SERIAL_NUMBER": "",
"AMOUNT_CONFIRM": "Y",
"STAFF_ID": "",
"ADD_PRINT": "None",
"ADD_DATA": "",
"ORDER_ID": "",
"APP": "PAYMENT_STD",
"MERCHANT_OUTLET_ID": "000000000000000071000",
"MERCHANT_ID": "000000000070000",
"CLIENT_ID": "1111"
}
Listing 5: SETTLEMENT Request Message

The size and type of each field are shown in Table 6

Name Data Length Required Note

Type
APP String FIXED 12 M Hard Coding:"PAYMENT_STD"
EVENT String FIXED 6 M Hard Coding: "SETTLE"
REF_ID String FIXED 8 M
SERIAL_NUMBER String 6-15 M
AMOUNT_CONFIRM String FIXED 1 O Value: "Y" or "N"
Default value: "Y"
"Y": cashier confirm on
terminal.
"N": without cashier
confirm on terminal.
STAFF_ID String MAX 8 O
ADD_DATA String MAX 100 O Format: Tag-Length-Value
Ex: 01030030206876543
Param 01: 0103003
Param 02: 0206876543
ADD_PRINT String MAX 100 O
ORDER_ID String MAX 100
MERCHANT_OUTLET_ID String FIXED 21 M
MERCHANT_ID String FIXED 15 M
String FIXED 4 M

Version 1.1.3 [EN] Page 17 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

CLIENT_ID

Table 6: SETTLEMENT Request Message Data

• Response Step 1:
{
"RESULT": "Y",
"RESPONSE_CODE": "7000",
"DESCRIPTION": "Processing ... ",
"KEY": "0EF60A8890F44EBA8F68EB4BDC92F73B"
}
• Request Step 2: Continue sending a check result request with KEY
is the KEY that receive from the response in step 1. (See 3.9)
{
"EVENT": "CHECK_RESULT",
"KEY": "0EF60A8890F44EBA8F68EB4BDC92F73B"
}
• Response Step 2: Returns the transaction result SETTLEMENT
associated with CHECK CHECK transaction, in the form of JSON
encoded as follows:
{
"APP": "PAYMENT_STD",
"RESULT": "Y",
"RESPONSE_CODE": "00",
"DESCRIPTION": "Transaction was processed successfully .",
"SETTLE_DATA":
"98719284#312948798231748#20170301151046#1#000015000000#0#00
0000000000#1#000015000000#0#000000000000",
"EVENT": "SETTLE",
"REF_ID": "77770001",
"SERIAL_NUMBER": "3J125611",
"ADD_PRINT": "",
"ADD_DATA": "",
"ORDER_ID": "",
"STAFF_ID": "",
"SETTLE_END": "1"
}
Listing 6: SETTLEMENT Response Message

Name Data Type Length Note

APP String FIXED 12 Hard Coding "PAYMENT_STD"
EVENT String FIXED 6 Hard Coding "SETTLE"
RESULT RESPONSE_CODE String FIXED 1 Value: "Y" or "N"
DESCRIPTION String FIXED 4
String MAX 100
SETTLE_DATA String MAX 1000
REF_ID String FIXED 8
SERIAL_NUMBER String 6-15
STAFF_ID String MAX 8
ADD_PRINT String MAX 100
ADD_DATA String MAX 100
ORDER_ID String MAX 100
SETTLE_END String FIXED 1 1: Settlement success
0: Settlement fail

Table 7: SETTLEMENT Response Message Data

Version 1.1.3 [EN] Page 18 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

Note: In case EDC has more than one Acquirer, EDC performs Settlement
for each Acquirer. Upon completion, the EDC prepares the results of the
entire Settlement transaction in the following format: Settlement
information of each Acquirer separated by "~" and content of each data
field separated by " # ". As follows:

• SETTLE_DATA Format:
TerminalID-1#MerchantID-1#DateTime-1#SaleTransNo-1#SaleAmt-
1#RefundTransNo-1 #RefundAmt-1#VoidSaleTransNo-1#VoidSaleTransAmt-
1#VoidRefundTransNo-1 #VoidRefundTransAmt-1~TerminalID-2#MerchantID-
2#DateTime-2
#SaleTransNo-2#SaleAmt-2#RefundTransNo-2#RefundAmt-2 #VoidSaleTransNo-
2#VoidSaleTransAmt-2#VoidRefundTransNo-2 #VoidRefundTransAmt-2~...

• Example:
99999999#999999999999999#20170822122153#6#000000120000
#0#000000000000#0#000000000000#0#000000000000~
00000000#123456789012345#20170822122153#1#000000000100#0#000000000000#0
#000000000000#0#000000000000

Version 1.1.3 [EN] Page 19 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

3.9 CHECK RESULT

• Function: When ECR sends a valid transaction to EDCC, EDCC

returns the ECR a 32-byte token sent as KEY. While the timeout
has not expired, the ECR schedules the request to EDCC with the
token received to know the transaction status being processed at
the EDC to prevent the ECR being blocked while processing the
transaction.
• By default, EDCC saves the last 05 Token values per EDC, saving
memory for EDCC.
• URL: http://ROOT-URL/API-INDICATOR/
• Method: POST
• Request: Same as described in Section 3.3. Where the content of
the request message is a JSON string as follows
{
"EVENT": "CHECK_ RESULT",
"KEY ": "0EF60A8890F44EBA8F68EB4BDC92F73B"
}

Listing 7: CHECK RESULT Request Message

The size and type of each field are shown in Table 8

Name Data Length Required Note

Type
EVENT String FIXED 12 M Hard Coding "CHECK_RESULT"
KEY String FIXED 32 M

Table 8: CHECK RESULT Request Message Data

Response: The result returned will depend on the previous transaction

to send to the API or depending on the processing status of the
transaction.

• If RESPONSE_CODE = 7000 means the transaction is being processed

under EDC, ECR should continue to wait.

• If the transaction has been completed, the result is the response

message of transaction SALE, VOID or SETTLEMENT.

• In the event, the result of the transaction returns ECR and EDCC
continue to receive the CHECK_RESULT request with the old key, EDCC
will return the error code RESPONSE_CODE = 9995. Thus, the KEY is
valid only when the transaction is in the state of affairs.
Management and transaction results are only returned once for ECR.

• JSON string example for case code 7000

{
"RESULT": "Y",
"RESPONSE_CODE": "7000",
"DESCRIPTION": "Processing ... ",
"KEY": "0EF60A8890F44EBA8F68EB4BDC92F73B"
}
Version 1.1.3 [EN] Page 20 of 38
 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

Listing 8: CHECK RESULT Response Message

• Json series results for SALE, VOID, SETTLEMENT: refer to the

sections outlined above

Name Data Type Length Note

RESULT String FIXED 1 Value: "Y" or "N"
RESPONSE_CODE String FIXED 4
DESCRIPTION String MAX 100
KEY String FIXED 32

Table 9: CHECK RESULT Response Message Data

Version 1.1.3 [EN] Page 21 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

3.10 GET CONNECTION

• Function: Used to lay out the EDCs that are calling to EDCC
corresponding to MERCHANT_ID and MERCHANT_OUTLET_ID.
• http://ROOT-URL/API-INDICATOR/
• Method: POST
• Request: Same as described in section 3.3. Where the content of the
request message is a JSON string as follows:
{
"EVENT": "CONN",
"MERCHANT_OUTLET_ID": "000000000000000071000",
"MERCHANT_ID": "000000000070000",
"CLIENT_ID": "1111"
}

Listing 9: GET CONNECTION Request Message

Name Data Type Length Required Note

EVENT String FIXED 4 M Hard Coding "CONN"
MERCHANT_OUTLET_ID String FIXED 21 M
MERCHANT_ID String FIXED 15 M
CLIENT_ID String FIXED 4 M

Response: Returns the EDC that is connecting to the EDCC corresponding

to MERCHANT_ID and MERCHANT_OUTLET_ID.
{
"RESULT": "Y",
"TOTAL ": 2,
"CONN ": [
{
"SERIAL": "29835228",
"APP": "PAYMENT_STD",
"MERCHANT_ID": "123456789123456",
"MERCHANT_OUTLET_ID": "123456789123456789123",
"TERMINAL_ID": "10000029",
"HOST": "192.168.5.80",
"HOST_NAME": "192.168.5.80",
"PORT": 8097
},
{
"SERIAL": "29835228",
"APP": "PAYMENT_STD",
"MERCHANT_ID ": "123456789123456",
"MERCHANT_OUTLET_ID": "123456789123456789123",
"TERMINAL_ID": "10000015",
"HOST": "192.168.5.80",
"HOST_NAME ": "192.168.5.80",
"PORT": 8097
}
]
}

Listing 10: GET CONNECTION Response Message

Version 1.1.3 [EN] Page 22 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

Name Data Type Length Note

RESULT String FIXED 1 Value: "Y" or "N"
TOTAL Number EDC Total is online
CONN Json String EDC List
APP String FIXED 12 Hard Coding "PAYMENT_STD"
REF_ID String FIXED 8
SERIAL String 6 - 15
MERCHANT_ID String FIXED 15
MERCHANT_OUTLET_ID String FIXED 21
HOST String
HOST_NAME String
PORT Number

Table 11: GET CONNECTION Response Message Data

Version 1.1.3 [EN] Page 23 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

3.11 HEALTH CHECK

• Function: Used to check the EDC is available to send the payment

request.
• http://ROOT-URL/API-INDICATOR/
• Method: POST
• Request: Same as described in section 3.3. Where the content of the
request message is a JSON string as follows:
{
"EVENT": "HEALTH_CHECK",
"REF_ID": "00000002",
"SERIAL_NUMBER": "29835228",
"MERCHANT_OUTLET_ID": "000000000000000071000",
"MERCHANT_ID": "000000000070000",
"CLIENT_ID": "1111"
}
Listing 10: Check EDC’s Health Request Message

Name Data Type Length Required Note

EVENT String FIXED 4 M Hard Coding
"HEALTH_CHECK"
REF_ID String FIXED 8 M
SERIAL_NUMBER String 6-15 M
MERCHANT_OUTLET_ID String FIXED 21 M
MERCHANT_ID String FIXED 15 M
CLIENT_ID String FIXED 4 M

Response: Returns the EDC that is connecting to the EDCC corresponding

to MERCHANT_ID and MERCHANT_OUTLET_ID.
{
"RESULT": "Y",
"REF_ID": "00000002",
"SERIAL": "29835228",
"LAST_UPDATE": "2019-11-18 13:53:24"
}

Listing 11: Check EDC’s Health Response Message

Name Data Type Length Note

RESULT String FIXED 1 Value: "Y" or "N"
REF_ID String FIXED 8
SERIAL_NUMBER String 6 - 15
LAST_UPDATE String FIXED 19 Format: yyyy-mm-dd HH:mm:ss
Last time EDC reach to the EDCC

Table 12: Check EDC’s Health Response Message Data

Version 1.1.3 [EN] Page 24 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

3.12 GET TRANSACTION

• Functions: Search for information of one or more transactions

from day to day. This function provides an interface for ECR to
query transaction information that has occurred at the counter.
• URL: http://ROOT-URL/API-INDICATOR/
• Method: POST
• Request: Same as described in Section 3.3. Where the content of
the request message is a JSON string as follows:
{
"EVENT": "GET_TRANX",
"FROM_DATETIME": "09/09/2017 09:06:50",
"TO_DATETIME": "12/09/2017 09:06:50",
"PAGE_INDEX": "1",
"INVOICE": "",
"REF_ID": "",
"TERMINAL_ID": "",
"MERCHANT_OUTLET_ID": "346346536365363456365",
"MERCHANT_ID": "637453356435634",
"CLIENT_ID": "1111"
}

Listing 13: GET TRANSACTION Request Message

Name Data Length Required Note

Type
EVENT String FIXED 9 M Hard Coding GET_TRANX
FROM_DATETIME String FIXED 19 M From: dd/MM/yyyy HH:mm:ss
TO_DATETIME String FIXED 19 M To: dd/MM/yyyy HH:mm:ss
PAGE_INDEX String The feedback data from the
system will be split. Every
page has 30 transactions.
INVOICE String FIXED 6 Find with InvoiceID
Table 14: GET TRANSACTION Request Message Data

Response: Returns the total number of transactions that meet the search
criteria.

{
"RESULT": "Y",
"RESPONSE_CODE": "00",
"DESCRIPTION": "Transaction was processed successfully .",
"TOTAL_PAGE": 1,
"PAGE_INDEX": 1,
"TOTAL_ROW": 3,
"TRANX":[
{
"RESPONSE_CODE": "00",
"CARD_TYPE": "VISA",
"TIME": "155951",
"INVOICE": "000007",
"CURRENCY_CODE": "704",
"NAME": "VISA CARDHOLDER",
"TRANX_TYPE": "SALE",
Version 1.1.3 [EN] Page 25 of 38
 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

"DATE":"0301",
"AMOUNT": "000015000000",
"REF_NO": "997826890668",
"APPV_CODE": "153714",
"MERCHANT_OUTLET_ID": "432134143141243143124",
"MERCHANT_ID": "313131313133143",
"CLIENT_ID": "1111",
"TERMINAL_ID": "98719284",
"MERCHANT_CODE": "312948798231748",
"REF_ID": "77770001",
"ADD_PRINT": "MSSV_NGUYEN VAN A",
"ADD_DATA": "",
"ORDER_ID": "",
"STAFF_ID": ""
},
{
"RESPONSE_CODE": "00",
"CARD_TYPE": "VISA",
"TIME": "155922",
"INVOICE": "000006",
"CURRENCY_CODE": "704",
"NAME": "VISA CARDHOLDER",
"TRANX_TYPE": "SALE",
"DATE": "0301",
"AMOUNT": "000015000000",
"REF_NO": "665537444609",
"APPV_CODE": "478239",
"MERCHANT_OUTLET_ID": "432134143141243143124",
"MERCHANT_ID": "313131313133143",
"CLIENT_ID": "1111",
"TERMINAL_ID": "98719284",
"MERCHANT_CODE": "312948798231748",
"REF_ID": "77770001",
"ADD_PRINT": "",
"ADD_DATA": "",
"ORDER_ID": "",
"STAFF_ID": ""
},
{
"RESPONSE_CODE": "00",
"CARD_TYPE": "DEBIT",
"TIME": "152241",
"INVOICE": "000004",
"CURRENCY_CODE": "704",
"NAME": "TEST CARD",
"TRANX_TYPE": "VOID",
"DATE": "0301",
"AMOUNT": "000015000000",
"REF_NO": "148577140922",
"APPV_CODE": "996979",
"MERCHANT_OUTLET_ID ": "432134143141243143124",
"MERCHANT_ID": "313131313133143",
"CLIENT_ID": "1111",
"TERMINAL_ID": "92184124",
"MERCHANT_CODE": "432524525425432",
Version 1.1.3 [EN] Page 26 of 38
 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

"REF_ID": "77770001",
"ADD_PRINT": "",
"ADD_DATA": "",
"ORDER_ID": "",
"STAFF_ID": ""
}
]
}

Listing 15: GET TRANSACTION Response Message

Name Data Type Length Note

RESULT String FIXED 1 Value: "Y" or "N"
RESPONSE_CODE String
DESCRIPTION String
TOTAL_PAGE Number Total Page
PAGE_INDEX Number Current Page
TOTAL_ROW Number Transaction Total
TRANX Json String Transaction List

Table 16: GET TRANSACTION Response Message Data

Version 1.1.3 [EN] Page 27 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

3.13 QR Code

• Function: Use to display or print QR Codes on EDC devices via

EDCC.
• URL: http://ROOT-URL/API-INDICATOR/
• Method: POST
• Request: The message sending structure is the same as described
in Section 3.3. Where the content of the request message is a
JSON string as follows:
{
"EVENT : "QRCODE ",
"PRIORITY": "BankPlus",
"VERSION": "1.0",
"TYPE": "PAY_ORDER",
"BILLCODE": "TH3232323",
"MERCHANT_CODE ": "BCCARD_VCB",
"REF_ID": "10000001",
"SERIAL_NUMBER": "29835228",
"TERMINAL_ID": "98719284",
"AMOUNT": "000015000000",
"CURRENCY_CODE": "704",
"STAFF_ID": "",
"ADD_PRINT": "",
"ADD_DATA": "",
"ORDER_ID": "",
"APP": "PAYMENT_STD",
"MERCHANT_OUTLET_ID ": "123456789123456789123",
"MERCHANT_ID": "123456789123456",
"CLIENT_ID": "1234"
}
Listing 17: QR Code Request Message

Version 1.1.3 [EN] Page 28 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

The size and type of each QR Code transaction field are shown in Table
14

Name Data Type Length Required Note

APP String FIXED 12 M Hard Coding "PAYMENT_STD"
EVENT String FIXED 6 M Hard Coding "QRCODE"
REF_ID String FIXED 8 M
TERMINAL_ID String FIXED 8 Terminal ID of Acquirer
SERIAL_NUMBER String 6-15 M
AMOUNT String FIX 12 M The amount must be greater
than one. Example:
125.000 VND →000012500000

$2.35 → 000000000235
CURRENCY_CODE String FIXED 3 M VND: 704, USD: 840
STAFF_ID String MAX 8 O
ADD_PRINT String MAX 100 O Destination account, using
to print account number
below the QR Code.
ADD_DATA String MAX 100 O Content tranfer
ORDER_ID String MAX 100 O
MERCHANT_OUTLET_ID String FIXED 21 M
MERCHANT_ID String FIXED 15 M
CLIENT_ID String FIXED 4 M
PRIORITY String FIXED 8 M Hard Coding "BankPlus"
VERSION String FIXED 3 M Hard Coding "1.0"
TYPE String FIXED 9 M Hard Coding "PAY_ORDER"
BILLCODE String MAX 50 M
MERCHANT_CODE String FIXED 12 M Hard Coding "BCCARD_VCB"

Table 18: QR Code Request Message Data

Response: The result of a QR Code encoded in JSON encoded is as

follows:
{
"APP": "PAYMENT_STD",
"RESULT": "Y",
"RESPONSE_CODE": "00",
"DESCRIPTION": "Transaction was processed successfully .",
"MERCHANT_CODE": "BCCARD_VCB",
"TERMINAL_ID": "98719284",
"CURRENCY_CODE": "704",
"REF_ID": "10000001",
"SERIAL_NUMBER": "29835228",
"AMOUNT": "000015000000",
"EVENT": "QRCODE",
"PRIORITY": "BankPlus",

Version 1.1.3 [EN] Page 29 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

"VERSION": "1.0",
"TYPE": "PAY_ORDER",
"BILLCODE": "TH3232323",
"ADD_PRINT": "",
"ADD_DATA": "",
"ORDER_ID": "",
"STAFF_ID": ""
}
Listing 19: QR Code Response Message

Name Data Type Length Note

APP String FIXED 12 Hard Coding "PAYMENT_STD"
EVENT String FIXED 6 Hard Coding "QRCODE"
RESULT String FIXED 1 Value: "Y" or "N"
RESPONSE_CODE String FIXED 4
DESCRIPTION String MAX 100
MERCHANT_CODE String FIXED 12 Hard Coding "BCCARD_VCB"
TERMINAL_ID String FIXED 8
CURRENCY_CODE String FIXED 3 VND: 704, USD: 840
REF_ID String FIXED 8
SERIAL_NUMBER String 6-15
AMOUNT String FIXED 12 VND: 000012500000 → 125.000,00
USD: 000000000235 → $2.35
STAFF_ID String MAX 8
ADD_PRINT String MAX 100 Destination account, using to print
account number the below QR Code.
ADD_DATA String MAX 100 Content tranfer
ADD_PRINT String MAX 100
PRIORITY String FIXED 8 Hard Coding "BankPlus"
VERSION String FIXED 3 Hard Coding "1.0"
TYPE String FIXED 9 Hard Coding "PAY_ORDER"
BILLCODE String MAX 50

Table 20: QR Code Response Message Data

Version 1.1.3 [EN] Page 30 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

3.14 Print Receipt

• Function: Use to print a receipt on EDC devices via EDCC.

• URL: http://ROOT-URL/API-INDICATOR/
• Method: POST
• Request: The message sending structure is the same as described
in Section 3.3. Where the content of the request message is a
JSON string as follows:
{
"EVENT”:"PRINT_RECEIPT",
"APP”:"PAYMENT_STD",
"REF_ID": "10000001",
"SERIAL_NUMBER": "29835228",
"TERMINAL_ID": "98719284",
"AMOUNT": "000015000000",
"CURRENCY_CODE": "704",
"ADD_PRINT": "",
"ORDER_ID": "",
"MERCHANT_OUTLET_ID ": "123456789123456789123",
"MERCHANT_ID": "123456789123456",
"CLIENT_ID": "1234"
"NAME": "Nguyen Van A",
"PAN": "123****325",
"DATE": "2409",
"TIME": "1525",
"INVOICE": "0000005",
"CARD_TYPE": "VISA",
"REF_NO": "",
"APPV_CODE": "00",
"MERCHANT_NAME": "",
"MERCHANT_ADD": ""
}
Listing 21: Print Receipt Request Message

Version 1.1.3 [EN] Page 31 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

The size and type of each field are shown in Table 16

Name Data Type Length Required Note

APP String FIXED 12 M Hard Coding "PAYMENT_STD"
EVENT String FIXED 4 M Hard Coding "PRINT_RECEIPT"
MERCHANT_NAME String MAX 50 O
MERCHANT_ADD String MAX 50 O
TERMINAL_ID String MAX 8 O
CURRENCY_CODE String FIXED 3 M VND: 704, USD: 840
REF_ID String FIXED 8 M
SERIAL_NUMBER String 6-15 M
AMOUNT String FIXED 12 M VND: 000012500000 ->
125.000,00
USD: 000000000235 -> $2.35
PAN String MAX 16 M
NAME String MAX 30 M
REF_NO String FIXED 12 M
APPV_CODE String 2-6 M
CARD_TYPE String MAX 10 M
INVOICE String FIXED 6 M
DATE String FIXED 4 M
TIME String FIXED 4 M
MERCHANT_OUTLET_ID String FIXED 21 M
MERCHANT_ID FIXED 15 M
CLIENT_ID FIXED 4 M
ADD_PRINT String MAX 100 O
ORDER_ID String MAX 100 O

Table 22: Print Receipt Request Message Data

Response: The result of a Print Receipt encoded in JSON encoded is as

follows:
{
"EVENT”:"PRINT_RECEIPT",
"APP”:"PAYMENT_STD",
"RESULT”:"Y",
"RESPONSE_CODE": "00",
"DESCRIPTION": "",
"TERMINAL_ID": "98719284",
"CURRENCY_CODE": "704",
"REF_ID": "10000001",
"SERIAL_NUMBER": "29835228",
"AMOUNT": "000015000000",
"NAME": "Nguyen Van A",
"PAN": "123****325",
"REF_NO": "",
Version 1.1.3 [EN] Page 32 of 38
 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

"APPV_CODE": "00",
"CARD_TYPE": "VISA",
"INVOICE": "0000005",
"DATE": "2409",
"TIME": "1525",
"ADD_PRINT": "",
"ORDER_ID": "",
"MERCHANT_NAME": "",
"MERCHANT_ADD": ""
}
Listing 23: Print Receipt Response Message

Name Data Type Length Note

APP String FIXED 12 Hard Coding "PAYMENT_STD"
EVENT String FIXED 6 Hard Coding "PRINT_RECEIPT"
RESULT String FIXED 1 Value: "Y" or "N"
RESPONSE_CODE String FIXED 4
DESCRIPTION String MAX 100
TERMINAL_ID String FIXED 8
CURRENCY_CODE String FIXED 3 VND: 704, USD: 840
REF_ID String FIXED 8
SERIAL_NUMBER String 6-15
MERCHANT_NAME String MAX 50
MERCHANT_ADD String MAX 50
AMOUNT String FIXED 12 VND: 000012500000 → 125.000,00
USD: 000000000235 → $2.35
PAN String MAX 16
NAME String MAX 30
REF_NO String FIXED 12
APPV_CODE String 2-6
CARD_TYPE String MAX 10
INVOICE String FIXED 6
DATE String FIXED 4
TIME String FIXED 4
ADD_PRINT String MAX 100
ORDER_ID String MAX 100

Table 24: Print Receipt Response Message Data

Version 1.1.3 [EN] Page 33 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

4 Encrypt/Decrypt Message

4.1 Encrypt-Decrypt Message Code in Java

import org.jpos.iso.ISOUtil;
import javax.crypto.Cipher;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;

public class AESEncryption {

private static final String ALGORITHM = "AES";
private static final String TRANSFORMATION = "AES/CBC/NoPadding";
private static final byte[] IV = new byte[16]; // Initialization
Vector

public static String encrypt(String plaintext, String key) throws

Exception {
SecretKeySpec secretKey = new
SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), ALGORITHM);
Cipher cipher = Cipher.getInstance(TRANSFORMATION);
IvParameterSpec ivParameterSpec = new IvParameterSpec(IV);
cipher.init(Cipher.ENCRYPT_MODE, secretKey, ivParameterSpec);
byte[] plaintextBytes =
plaintext.getBytes(StandardCharsets.UTF_8);
int blockSize = cipher.getBlockSize();
int plaintextLength = plaintextBytes.length;
int paddedLength = (plaintextLength / blockSize + 1) * blockSize;
byte[] paddedBytes = new byte[paddedLength];
System.arraycopy(plaintextBytes, 0, paddedBytes, 0,
plaintextLength);
byte[] encryptedBytes = cipher.doFinal(paddedBytes);
return ISOUtil.hexString(encryptedBytes);
}

public static String decrypt(String plaintext, String key) throws

Exception {
SecretKeySpec secretKey = new
SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), ALGORITHM);
Cipher cipher = Cipher.getInstance(TRANSFORMATION);
IvParameterSpec ivParameterSpec = new IvParameterSpec(IV);
cipher.init(Cipher.DECRYPT_MODE, secretKey, ivParameterSpec);
byte[] encryptedBytes =
cipher.doFinal(ISOUtil.hex2byte(plaintext));
return new String(encryptedBytes);
}

public static void main(String[] args) throws Exception {

String plaintext = "111111";
Version 1.1.3 [EN] Page 34 of 38
 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

String key = "3CC1570585494D69AD43FCBEC40F8D90";

String encryptedText = encrypt(plaintext, key);

String decryptedText = decrypt(encryptedText, key);
System.out.println("Encrypted Text: " + encryptedText);
System.out.println("Decrypted Text: " + decryptedText);
}
}

4.2 Encrypt-Decrypt Message Code in C#

public static byte[] StringToByteArray(string hex)

{
return Enumerable.Range(0, hex.Length)
.Where(x => x % 2 == 0)
.Select(x => Convert.ToByte(hex.Substring(x, 2),
16))
.ToArray();
}

public static string EncryptString(string key, string plainText)

{
byte[] iv = new byte[16];
byte[] array;

using (Aes aes = Aes.Create())

{
aes.Key = Encoding.UTF8.GetBytes(key);
aes.IV = iv;
aes.Mode = CipherMode.CBC;
aes.Padding = PaddingMode.Zeros;

ICryptoTransform encryptor = aes.CreateEncryptor(aes.Key, aes.IV);

using (MemoryStream memoryStream = new MemoryStream())

{
using (CryptoStream cryptoStream = new
CryptoStream((Stream)memoryStream, encryptor, CryptoStreamMode.Write))
{
using (StreamWriter streamWriter = new
StreamWriter((Stream)cryptoStream))
{
streamWriter.Write(plainText);
}

array = memoryStream.ToArray();
}
}

Version 1.1.3 [EN] Page 35 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

}
return BitConverter.ToString(array).Replace("-", "").ToLower();
}

public static string DecryptString(string key, string cipherText)

{
byte[] iv = new byte[16];
byte[] buffer = StringToByteArray(cipherText);

using (Aes aes = Aes.Create())

{
aes.Key = Encoding.UTF8.GetBytes(key);
aes.IV = iv;
aes.Mode = CipherMode.CBC;
aes.Padding = PaddingMode.Zeros;

ICryptoTransform decryptor = aes.CreateDecryptor(aes.Key, aes.IV);

using (MemoryStream memoryStream = new MemoryStream(buffer))

{
using (CryptoStream cryptoStream = new
CryptoStream((Stream)memoryStream, decryptor, CryptoStreamMode.Read))
{
using (StreamReader streamReader = new
StreamReader((Stream)cryptoStream))
{
return streamReader.ReadToEnd();
}
}
}
}
}

Version 1.1.3 [EN] Page 36 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

5 Response Code Reference

Error Code Description

00 Transaction was processed successfully.
01 PLS CALL BANK
02 REFERRAL
03 INVALID MERCHANT
04 PICKUP CARD
05 DO NOT HONOUR
08 APPROVED WITH ID
09 ACEPTED nnnnnn
12 INVALID PROCESSING CODE
13 INVALID AMOUNT
14 INVALID ACCOUNT
19 RE-ENTER Transaction
25 INVALID TERMINAL
30 FORMAT ERROR
41 LOST CALL LC
43 STOLEN CARD
51 INSUFFICIENT FUND
52 NO CURRENT ACCT
53 NO SAVING ACCT
54 EXPIRED CARD
55 INCORRECT PIN
58 INVALID PROCESSING CODE
60 CALL ACQUIRER
61 EXCDS WITHDRAW
75 PIN TRIED EXCEEDED
76 BAD PRODUCT CODE
77 RECONCILE ERROR
78 TRACE NOT FOUND
79 DECLINE
80 BAD BATCH NUMBER
81 WRONG FORMAT FOR PAYMENT
82 BAD PREPAID CODE
83 NO SUSP. SOC SLOTS
85 BATCH NOT FOUND
88 APPRV, CALL AMEX
89 BAD TERMINAL ID
91 SYSTEM NOT AVAIL
94 DUPLICATE TRACE
95 BATCH TRANSFER
96 INVALID MESSAGE
Q1 CARD AUTH FAIL
Y1 OFFLINE APPROVAL
Y2 APPROVED
Y3 GO ONLINE FAIL
Z1 OFFLINE DECLINE
Z2 INSUFFICIENT FUND
Z3 GO ONLINE FAIL
0100 User intentionally cancel the transaction.
0101 Transaction timeout from EDC.
0200 Unable to process transaction
0300 No response from authorization system (Host)
0400 The input parameters are not correct
0500 The operation was processed, not allow process twice
0600 Transaction adjusted

Version 1.1.3 [EN] Page 37 of 38

 BCCard Vietnam-EDC CONTROLLER – API Programming Guide

0800 The acquirer is invalid

0905 Message Error
0906 EDC-POS is busy
0907 EDC-POS was not existed
0908 Transaction Error
0909 Transaction Time-out
0911 Another Error
0912 Duplicate Transaction
0913 Missing Parameters
0914 Not Connect to EDC
0919 Checksum is failed
1301 The trace No. is invalid
1302 The amount is invalid
1303 Invalid currency code.
1304 The terminal id is invalid
1305 Terminal id is duplicate on EDC
7000 Processing...
9000 Unknown error
9800 Must settle batch first
9801 Out of paper
9900 Expired card
9901 Invalid PAN
9902 Read card error
9903 Unsupported card.
9904 Empty batch.
9905 Can’t display QR Code
9980 Client Id is invalid.
9981 Merchant Id is invalid.
9982 Merchant outlet Id is invalid.
9983 Ref Id is invalid.
9984 Serial number is invalid.
9985 Third party is invalid.
9990 Error connect between EDC and EDC-Controller.
9994 The transaction was not supported or not allowed.
9995 Invalid input parameter(s).
9996 Missing parameter(s).
9997 Cannot connect to EDC.
9998 Cannot connect to Service.
9999 EDC doesn’t send the transaction result to EDC-Controller
after WaitTimeout period.

Version 1.1.3 [EN] Page 38 of 38