NAVNavbar
Shell/Json

Introduction

Welcome! Baokim’s mission is to deliver automated payment infrastructure solutions for your business. We help with both money in (collection payments) and money out (disbursement payments). Our users range from platforms businesses, fintech, e-Commerce, and everything else in between.

We have language bindings in Shell, Json! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Benefits of Baokim

Regulations and requirements

To authorize, use this shell code:

curl --request GET \
  --url https://replacedomain/Sandbox \
  --header 'Authorization: Basic YmFva2ltOmJrQDEyMzQ1Ng==' \
}
                

- API that Baokim deployed, will be built on the Restful architecture, data transmission between the two sides will be Json.

- Baokim will restrict access to the API by one or more IPs based on each Partner. So before joining , Partner will send the IP list to Baokim to open the access.

- Baokim uses Basic Authentication to allow access to the API. Account information will be provided by Bao Kim at the start of the integration.

Authorization: Basic YmFva2ltOmJrQDEyMzQ1Ng==

Restful and Digital Signature

Restfull Web Service

REST (Representational State Transfer) has been widely adopted instead of Web services based on SOAP and WSDL. REST defines architectural rules for designing Web services that focus on system resources, including how resource states are formatted and transported via HTTP through a large number of users and are written by different languages.

In order to be able to connect REST with the tool and test with BAOKIM, the PARTNER can load and use one of the following two universal tools:

- Postman: https://www.getpostman.com

- Soap UI: https://www.soapui.org

Digital signature

Model Sign

Private key and public key

Baokim is currently using digital signature by RSA-SHA1

There are several ways to generate RSA key pairs.

Way 1:

Generate your RSA key pairs online: Generate now

Way 2:

Using OpenSSL software for Windows:

Step 1: Download the software at:

http://slproweb.com/products/Win32OpenSSL.html. Partner should download the installer "OpenSSL_Light-1_0_2k". Then install in any directory, for example "C:\OpenSSLWin64"

Step 2: Access "C:\OpenSSLWin64\bin" then open the command prompt. Type the command to declare the environment config.

set OPENSSL_CONF=C:\OpenSSL-Win64\bin\openssl.cfg

Step 3: Generate private key and public key

openssl genrsa -aes256 -out c:\opensslkeys\partner\partner_privatekey.pem 2048

openssl rsa –in c:\opensslkeys\partner\partner_privatekey.pem -pubout >c:\opensslkeys\partner\partner_publickey.pem

After successful pairing, Partner will send back to Baokim the public key to authenticate the signature that the Partner sends via the API

Disbursement payments

* Introduction documents and business processes on services: Download

Model Sign

Definition API

Environment Method Url
Test POST https://devtest.baokim.vn/Sandbox/FirmBanking
Production POST Provided when the contract is completed

Now we will see the details of each function

Verify customer information

Process:

1. Partner will call the customer authentication function, Baokim will check the data format and signature authentication..

2. Baokim continues to check customer information and corresponding bank

3. If the information is correct, Baokim will return successful information and corresponding customer name.

Body request samples:

                    {
                        RequestId: "PARTNERBK2018033000001",
                        RequestTime: "2018-03-30 11:20:32",
                        PartnerCode: "PARTNER",
                        Operation: 9001,
                        BankNo: "970436",
                        AccNo: "0021000382448",
                        AccType: 0,
                        Signature: "hBMeZuDNPDD1TE9q3ojo+SSwA/FehW3H77y+3JkNHrdpRentPD 1TE9q3ojo FehW3H77y+3JkNHrdpRentPD =",
                    }
                

Request pamram

# Parameters Datatypes Condition Description
1 RequestId String (50) Required The only code that corresponds to an upload request. Proposed format is as follows: PartnerCode + BK + YYYYMMDD + UniqueId
2 RequestTime String (19) Required It is time to send request from Partner, format: YYYY-MM-DD HH:MM:SS
3 PartnerCode String (20) Required The partner code is defined in the Baokim system. This code will send to the partner when the integration begins.
4 Operation Int (4) Required This parameter will determine which function that partner is calling. For customer authentication functions, the fix is “9001”
5 BankNo String (20) Required Bank code in accordance with Baokim is defined in the section 8. List of remittance banks
6 AccNo String (22) Required Account number or bank card number of the customer.
7 AccType Int (1) Required AccNo classification 0: Bank account number 1: Bank card number
8 Signature String (500) Required The partner will sign with digital signature of data transmitted using the algorithm RSACryptoServiceProvider. Before sending ,data will be base64 encoding. Data follow this structure: RequestId|RequestTime| PartnerCode|Operation|BankNo| AccNo|AccType

Body response success samples:

{
    ResponseCode: 200,
    ResponseMessage: "Successful",
    RequestId: "PARTNERBK2018033000001",
    BankNo: "970436",
    AccNo: "0021000382448",
    AccType: 0,
    AccName: "TRUONG DUC THUAN",
    Signature: "zoUhBMeZuDNPDD1TE9q3ojo+SSwA/FehW3H77y+3JkNHrdpRentPD 1TE9q3ojo FehW3H77y+3JkNHrdpRentPDmwk =",
}
                

Body response Account no/Card no. does not exist samples:

{
    ResponseCode: 119,
    ResponseMessage: "Account no./Card no. does not exist",
    RequestId: "PARTNERBK2018033000001",
    BankNo: "970436",
    AccNo: "0021000382448",
    AccType: 0,
    AccName: "",
    Signature: "qwhBMeZuDNPDD1TE9q3ojo+SSwA/FehW3H77y+3JkNHrdpRentPD 1TE9q3ojo FehW3H77y+3JkNHrdpRentPDPxe =",
}
                

Response pamram

# Parameters Datatypes Description
1 ResponseCode Int (4) The response status, is defined in Response Code
2 ResponseMessage String (200) Description for return status, defined in Response Code
3 RequestId String (50) Partner information posted
4 BankNo String (20) Partner information posted
5 AccNo String (22) Partner information posted
6 AccType Int (1) Partner information posted
7 AccName String (50) Baokim Customer's name response if customer information is submitted correctly
8 Signature String (200) Baokim will sign with digital signature of data returned using RSACryptoServiceProvider. Returns the base64 encoding. Data is structured: ResponseCode|ResponseMessage|RequestId| BankNo|AccNo|AccType|AccName

Transfer money

Process:

1. Partner will call the money transfer function, Baokim will check the data format and signature authentication, then will check the customer information, the amount to transfer.

2. If the correct information will return successful transfer.

Body request samples:

{
    RequestId: "PARTNERBK2018033000002",
    RequestTime: "2018-03-30 11:20:32",
    PartnerCode: "PARTNER",
    Operation: 9002,
    ReferenceId: "5CBCAB920C63CED5E0540010E099E090",
    BankNo: "970436",
    AccNo: "0021000382448",
    AccType: 0,
    RequestAmount: 1000000,
    Memo: "transfer money to customers",
    Signature: "zzhBMeZuDNPDD1TE9q3ojo+SSwA/FehW3H77y+3JkNHrdpRentPD 1TE9q3ojo FehW3H77y+3JkNHrdpRentPDbb =",
}
                

Request pamram

# Parameters Datatypes Condition Description
1 RequestId String (50) Required The only code that corresponds to an upload request. Proposed format is as follows: PartnerCode + BK + YYYYMMDD + UniqueId
2 RequestTime String (19) Required It is time to send request from Partner, format: YYYY-MM-DD HH:MM:SS
3 PartnerCode String (20) Required The partner code is defined in the Baokim system. This code will send to the partner when the integration begins.
4 Operation Int (4) Required This parameter will determine which function partner is calling. For the transfer function, the fix is “9002”
5 ReferenceId String (50) Required Transaction code sent by the partner
6 BankNo String (20) Required Bank code in accordance with Baokim is defined in the section 8. List of remittance banks
7 AccNo String (22) Required Account number or bank card number of the customer.
8 AccType Int (1) Required AccNo classification 0: Bank account number 1: Bank card number
9 RequestAmount Int (9) Required The amount requested by the partner to transfer to the recipient.
10 Memo String (100) Optional Money transfer contents
11 Signature String (500) Required The partner will sign with digital signature of data transmitted using the algorithm RSACryptoServiceProvider. Before sending ,data will be base64 encoding. Data follow this structure: RequestId|RequestTime|PartnerCode| Operation|ReferenceId|BankNo|AccNo| AccType|RequestAmount|Memo

Body response success samples:

{
    ResponseCode: 200,
    ResponseMessage: "Successful",
    ReferenceId: "5CBCAB920C63CED5E0540010E099E090",
    TransactionId: "BK5CF8D68AE3CF8JY",
    TransactionTime: "2019-06-06",
    BankNo: "970436",
    AccNo: "0021000382448",
    AccName: "TRUONG DUC THUAN"
    AccType: 0,
    RequestAmount: 1000000,
    TransferAmount: 1000000,
    AffterBalance : 100000000,
    AfterDisbursementDay : 100000000,
    Signature: "zzhBMeZuDNPDD1TE9q3ojo+SSwA/FehW3H77y+3JkNHrdpRentPD 1TE9q3ojo FehW3H77y+3JkNHrdpRentPDbb =",
}
                

Body response fail samples:

{
    ResponseCode: 11,
    ResponseMessage: "Failed",
    ReferenceId: "5CBCAB920C63CED5E0540010E099E090",
    TransactionId: "BK5CF8D68AE3CF8JY",
    TransactionTime: "2019-06-06",
    BankNo: "970436",
    AccNo: "0021000382448",
    AccName: "TRUONG DUC THUAN"
    AccType: 0,
    RequestAmount: 1000000,
    TransferAmount: null,
    AffterBalance : null,
    AfterDisbursementDay : null,
    Signature: "zzhBMeZuDNPDD1TE9q3ojo+SSwA/FehW3H77y+3JkNHrdpRentPD 1TE9q3ojo FehW3H77y+3JkNHrdpRentPDbb =",
}
                

Response pamram

# Parameters Datatypes Description
1 ResponseCode Int (4) The response status, is defined in Response Code
2 ResponseMessage String (200) Description for return status, defined in Response Code
3 ReferenceId String (50) Partner information posted
4 TransactionId String (50) Transaction code recorded side Baokim
5 TransactionTime String (50) Finishing time side Baokim. Format YYYY-MM-DD
6 BankNo String (20) Partner information posted
7 AccNo String (22) Partner information posted
8 AccName String (50) Full name of the recipient, may or may not, depending on the time
9 AccType Int (1) Partner information posted
10 RequestAmount Int (9) Partner information posted
11 TransferAmount Int (9) The actual amount transferred to the recipient. Will be less if the remittance
12 AffterBalance Int (9) Current balance of investors
13 AfterDisbursementDay Int (9) Continue disbursement amount (in limit)
14 Signature String (500) BAOKIM will sign by digital signature of response data. Data is structured: ResponseCode| ResponseMessage| ReferenceId|TransactionId| TransactionTime|BankNo|AccNo|AccName|AccType| RequestAmount|TransferAmount

Look up for transfer info

Process:

1. PARTNER will call the transaction information search function, BAOKIM will check the data format and signature authentication, then will check the transaction code..

2. If the information is correct, return the transaction information..

Body request samples:

{
    RequestId: "PARTNERBK2018033000002",
    RequestTime: "2018-03-30 11:20:32",
    PartnerCode: "PARTNER",
    Operation: 9003,
    ReferenceId: "5CBCAB920C63CED5E0540010E099E090",
    Signature: "zzhBMeZuDNPDD1TE9q3ojo+SSwA/FehW3H77y+3JkNHrdpRentPD 1TE9q3ojo FehW3H77y+3JkNHrdpRentPDbb =",
}
                

Request pamram

# Parameters Datatypes Condition Description
1 RequestId String (50) Required The only code that corresponds to an upload request. Proposed format is as follows: PartnerCode + BK + YYYYMMDD + UniqueId
2 RequestTime String (19) Required It is time to send request from Partner, format: YYYY-MM-DD HH:MM:SS
3 PartnerCode String (20) Required The partner code is defined in the Baokim system. This code will send to the partner when the integration begins.
4 Operation Int (4) Required This parameter will determine which function partner is calling. For transactional lookup information, the fix is "9003"
5 ReferenceId String (50) Required Transaction code from PARTNER submitted
6 Signature String (500) Required The partner will digitally sign up data using the RSACryptoServiceProvider algorithm. Before sending to will base64 encoding. Data is structured: RequestId|RequestTime|PartnerCode| Operation|ReferenceId

Body response success samples:

{
    ResponseCode: 200,
    ResponseMessage: "Successful",
    ReferenceId: "5CBCAB920C63CED5E0540010E099E090",
    TransactionId: "BK5CF8D68AE3CF8JY",
    TransactionTime: "2019-06-06",
    BankNo: "970436",
    AccNo: "0021000382448",
    AccName: "TRUONG DUC THUAN"
    AccType: 0,
    RequestAmount: 1000000,
    TransferAmount: 1000000,
    Signature: "zzhBMeZuDNPDD1TE9q3ojo+SSwA/FehW3H77y+3JkNHrdpRentPD 1TE9q3ojo FehW3H77y+3JkNHrdpRentPDbb =",
}
                

Response pamram

# Parameters Datatypes Description
1 ResponseCode Int (4) The response status, is defined in Response Code
2 ResponseMessage String (200) Description for return status, defined in Response Code
3 ReferenceId String (50) This is the ReferenceID of the input parameter
4 TransactionId String (50) Transaction code recorded side Baokim
5 TransactionTime String (50) Finishing time side Baokim. Format YYYY-MM-DD
6 BankNo String (20) Partner information posted
7 AccNo String (22) Partner information posted
8 AccName String (50) Full name of the recipient, may or may not, depending on the time
9 AccType Int (1) Partner information posted
10 RequestAmount Int (9) Partner information posted
11 TransferAmount Int (9) The actual amount transferred to the recipient. Will be less if the remittance
12 Signature String (500) BAOKIM will sign by digital signature of response data. Data is structured: ResponseCode| ResponseMessage| ReferenceId|TransactionId| TransactionTime|BankNo|AccNo|AccName|AccType| RequestAmount|TransferAmount

Look up for Partner balance

Process:

1. Partner will call the partner balance searching function, Baokim will check the data format and signature authentication

2. If the information is correct, return the availale balance

Body request samples:

{
    RequestId: "PARTNERBK2018033000002",
    RequestTime: "2018-03-30 11:20:32",
    PartnerCode: "PARTNER",
    Operation: 9004,
    Signature: "xzzhBMeZuDNPDD1TE9q3ojo+SSwA/FehW3H77y+3JkNHrdpRentPD 1TE9q3ojo FehW3H77y+3JkNHrdpRentPDbbqw =",
}
                

Request param

# Parameters Datatypes Condition Description
1 RequestId String (50) Required The only code that corresponds to an upload request. Proposed format is as follows: PartnerCode + BK + YYYYMMDD + UniqueId
2 RequestTime String (19) Required It is time to send request from Partner, format: YYYY-MM-DD HH:MM:SS
3 PartnerCode String (20) Required The partner code is defined in the Baokim system. This code will send to the partner when the integration begins.
4 Operation Int (4) Required This parameter will determine which function partner is calling. For lookup balance information, the fix is "9004"
5 Signature String (500) Required The partner will digitally sign up data using the RSACryptoServiceProvider algorithm. Before sending to will base64 encoding. Data is structured: RequestId|RequestTime| PartnerCode|Operation

Body response samples:

{
    ResponseCode: 200,
    ResponseMessage: "Successful",
    RequestId: "PARTNERBK20190606001",
    PartnerCode: "PARTNER"
    Available: 150000000,
    Holding: 2500000,
    Signature: "xzzhBMeZuDNPDD1TE9q3ojo+SSwA/FehW3H77y+3JkNHrdpRentPD 1TE9q3ojo FehW3H77y+3JkNHrdpRentPDbbqw =",
}
                

Response param

# Parameters Datatypes Description
1 ResponseCode Int (4) The response status, defined in Response Code
2 ResponseMessage String (200) Description for response status, defined in Response Code
3 RequestId String (50) Request id that partner sent
4 PartnerCode String (20) The code of partner
5 Available BigInt (30) Total partner’s available balance
6 Holding BigInt (30) Total money is pending
7 Signature String (500) BAOKIM will sign by digital signature of response data. Structured data: ResponseCode|ResponseMessage| RequestId | PartnerCode | Available | Holding

Describe the mechanism handling the transaction timeout

Due to traffic problems or during request processing at Baokim, transaction timeout may be generated. Baokim will describe the processing mechanism consists of two cases as follows:

Case 1: Baokim proactively returns error code timeout, error code 99

- This case occurs when the two parties set the maximum time to return the results for a transaction but for some reason the Baokim or Bank has not finished processing should be proactive return error code timeout

- The way to deal with this situation: Partner when receiving the timeout error code will call the check transaction status. In this function Baokim will return the transaction status for Partner.

Case 2: Timeout due to transmission line failure, does not get the result returned

In this case it is possible to timeout from Partner-> Baokim or Baokim-> Partner. So can not determine whether the transaction Baokim reception or not.

- The way to deal with this situation:

1. The Partner will call Check Transaction Status to look up transaction status. If the result is received then the Partner will update the partner status. If timeout is still the case then move on to step 2.

2. In cases where transmission lines meet with long incidents, Baokim and Partner will coordinate with human handling to certification. Partner will email to Baokim to request sending status for a transaction, the Baokim's technique will confirm the status and return to Partner

Response Code

ResponseCode ResponseMessage
200 Successful
99 Transaction timeout
11 Failed
101 Error processing from Baokim
102 Duplicated RequestId
103 Incorrect signature
110 Incorrect PartnerCode
111 PartnerCode deleted from the system
112 PartnerCode not yet activated
113 Operation code is required
114 Incorrect Operation code
115 BankID is required
116 BankID not supported
117 Account no. /Card no. should be from 6-22 characters in length
118 Invalid account no./Card no.
119 Account no./Card no. does not exist
120 Incorrect account type
121 Transaction ID sent from Partner is required
122 Transaction ID sent by Partner is existing
123 Transaction unfound
124 Transfer amount required
125 Invalid transfer amount
126 Error processing between Baokim and bank
127 Error connecting to bank
128 Error processing from bank
129 Insufficient disbursement limit or expired guarantee period
130 Exceeded transfer limit on day

List of bank transfer assistance

# BankNo BankName Account Card
1 970423 TIEN PHONG COMMERCIAL JOINT STOCK BANK
2 970437 Ho Chi Minh City Development Joint Stock Commercial Bank
3 970408 Global Petro Sole Member LimitedCommercial Bank
4 970407 Vietnam Technological and Commercial Joint Stock Bank
5 970442 Hong Leong Commercial Joint Stock Bank
6 970414 Ocean Commercial Joint - Stock Bank
7 970438 Bao Viet Joint Stock Commercial Bank
8 970422 Military Commercial Joint Stock Bank
9 970432 Vietnam Prosperity Joint-Stock Commercial Bank
10 970439 Public Bank Vietnam Limited (PBVN)
11 970415 VIETNAM JOINT STOCK COMMERCIAL BANK FOR INDUSTRY AND TRADE (Viettinbank)
12 970431 VIETNAM EXPORT IMPORT COMMERCIAL JOINT STOCK BANK (Eximbank)
13 970440 Southeast Asia Commercial Joint Stock Bank (SeABank)
14 970429 Sai Gon Joint StockCommercial Bank
15 970448 Orient Commercial Joint StockBank (OCB)
16 970425 An BinhCommercial Joint Stock Bank
17 970426 Vietnam Maritime Commercial Stock Bank (MSB)
18 970427 Vietnam Asia Commercial Joint Stock Bank (VietA)
19 970419 National Citizen Commercial Joint Stock Bank (NCB)
20 970418 Joint Stock Commercial Bank for Investment and Development of Vietnam (BIDV)
21 970443 Sai Gon- Ha Noi Commercial Joint Stock Bank
22 970406 DongA Joint Stock Commercial Bank
23 970441 Vietnam International Commercial Joint Stock Bank (VIB)
24 970424 Shinhan Bank Vietnam Limited
25 970433 Vietnam Thuong Tin Commercial Joint Stock Bank (Vietbank)
26 970454 VIET CAPITAL COMMERCIAL JOINT STOCK BANK (Ban Viet)
27 970452 Kien Long Commercial Joint -Stock Bank
28 970430 PETROLIMEX GROUPCOMMERCIAL JOINT STOCK BANK
29 970400 Sai Gon Joint Stock Commercial Bank (Saigon Bank)
30 970405 Vietnam Bank for Agriculture and Rural Development or Agribank (Agribank)
31 970403 Sacombank
32 970412 Vietnam Public Joint Stock Commercial Bank (Vietnam dai chung)
33 970421 Vietnam-Russia Joint Venture Bank - VRB
34 970428 Nam A Commercial Joint Stock Bank (Nam A Bank)
35 970434 Indovina Bank Ltd
36 970449 LienViet Post Joint Stock Commercial Bank (LienViet Post bank)
37 970457 Woori Bank Vietnam Limited
38 970436 Joint Stock Commercial Bank for Foreign Trade of Vietnam (Vietcombank)
39 970416 Asia Commercial Joint Stock Bank
40 970458 UNITED OVERSEAS BANK (VIETNAM) LIMITED
41 970446 Co-operative bank of VietNam
42 970455 Industrial Bank of Korea - Ha Noi Branch
43 970409 North Asia Commercial Joint Stock Bank
44 422589 CIMB Bank (Vietnam) Limited
45 796500 Ngân hàng DBS - Chi nhánh Hồ Chí Minh(DBS)
46 458761 TNHH MTV HSBC Việt Nam(HSBC)
47 970410 TNHH MTV Standard Chartered Việt Nam(SCVN)
48 801011 Nonghuyp - Chi nhánh Hà Nội(NHB)
49 970444 TM TNHH MTV Xây Dựng Việt Nam
50 970456 IBK - chi nhánh HCM
51 970462 Kookmin - Chi nhánh Hà Nội
52 970463 Kookmin - Chi nhánh Thành phố Hồ Chí Minh
53 546034 Ngân hàng số CAKE by VPBank
54 546035 Ngân hàng số Ubank by VPBank
55 970457 TNHH MTV Woori Việt Nam
56 999888 Chính sách Xã hội
57 970467 NGÂN HÀNG KEB HANA - CHI NHÁNH HÀ NỘI
58 971011 Trung tâm dịch vụ tài chính số VNPT – Chi nhánh Tổng công ty truyền thông
59 971005 Tổng Công ty Dịch vụ Số Viettel – Chi nhánh Tập đoàn Công nghiệp Viễn thông Quân đội
60 970466 NGÂN HÀNG KEB HANA - CHI NHÁNH THÀNH PHỐ HỒ CHÍ MINH
61 970468 Công ty Tài chính TNHH MTV Mirae Asset (Việt Nam)
62 533948 Citibank, N.A, - Chi nhánh Hà Nội
63 963668 BNP Paribas - Chi nhánh Hà Nội
64 963666 BNP Paribas - Chi nhánh TP. Hồ Chí Minh
65 168999 Cathay United Bank – Chi nhánh Hồ Chí Minh
66 971032 Trung tâm Dịch vụ số Mobifone – Chi nhánh Tổng Công ty viễn thông Mobifone
67 555666 Đầu tư và Phát triển Campuchia – Chi nhánh Hà Nội
68 963368 Công ty Tài chính TNHH MTV Shinhan Việt Nam
69 963688 Ngân hàng Bank of China (Hongkong) Limited – Chi nhánh Hồ Chí Minh

Collection payments version 2

Change log:

Version Updated at Updated by Updated Content
2.2 2020-09-20 Nguyen Nhu Tuan Anh Add: Notice of account bank switching (PARTNER Provide)
Update 9001 - Register VA
Response:
Update: AccountInfo: Change key from WOORIBANK to BANK
Update 9002 - Update VA Information
Response:
Update: AccountInfo: Change key from WOORIBANK to BANK
2.3 2021-08-09 Nguyen Thanh Dat Add QrCode into AccountInfo when create (9001) or update (9002) VA

* Introduction documents and business processes on services: Download

Model Sign

Note:

+ In case PARTNER want to use collect via Virtual Account, PARTNER will need to buid:

- Register virtual account
- Update virtual account informations
- Virtual account information searching
- Collection transaction status searching
- Notice of collection transaction
- Notice of account bank switching

+ In case PARTNER want to use collect at point, PARTNER will need to buid:

- Register virtual account
- Update virtual account informations
- Virtual account information searching
- Collection transaction status searching
- Collect at point
- Notice of collection transaction
- Notice of account bank switching

Definition API

Environment Method Url
Test POST https://devtest.baokim.vn/Sandbox/Collection/V2
Production POST Provided when the contract is completed

Request information to BAOKIM

Ingredient Parameters Describe
Header Content-Type application/json
Signature PARTNER will sign the Data with sha1WithRSA algorithm and use base64 encryption
Body Data Information (See details in section Details of functions)

Response from BAOKIM to PARTNER

Ingredient Parameters Describe
Header Content-Type application/json
Signature BAOKIM will sign the Data with sha1WithRSA algorithm and use base64 encryption
Body Data Information (See details in section Details of functions)

Sections Request information to BAOKIM and Response from BAOKIM to PARTNER describe the information transmitted and received during PARTNER's request to BAOKIM, corresponding to the functions Register virtual account, Update virtual account informations , Virtual account information searching and Collection transaction status searching.

Now we will see the details of each function

Register virtual account

Process:

1. PARTNER will call transaction by identification status checking, , BAOKIM will check the data format and signature authentication

2. If the information is correct, BAOKIM will cancel pending cash transfer transaction and return response to PARTNER.

Header request samples:

{
   Content-Type: "application/json",
   Signature:"hBMeZuDNPDD1TE9q3ojo+SSwA/FehW3H77y+3JkNHrdpRent ="
}
                

Body request samples:

{
    RequestId : "BK201907260657365",
    RequestTime : "2019-07-26 13:58:06",
    PartnerCode : "NTDAT",
    Operation : "9001",
    CreateType : 2,
    AccName         : "Nguyen Van A",
    CollectAmountMin : 50000,
    CollectAmountMax : 50000000,
    ExpireDate : "2025-05-09 12:00:00",
    OrderId : "de83d309aad465b59cadb223f",
    AccNo : NULL,
    SubMerchant : NULL,
    StoreCode : NULL
}
                

Request pamram

# Parameters Datatypes Condition Description
1 RequestId String (50) Required Unique code , recomment format: PartnerCode + BK + YYYYMMDD + UniqueId.
2 RequestTime String (19) Required Time send the request from PARTNER , format: YYYY-MM-DD HH:MM:SS.
3 PartnerCode String (20) Required Unique code BAOKIM provide
4 Operation Int (4) Required Fix: 9001
5 CreateType Int (4) Required Note: BK won't check this field, can send 2
6 AccName String (50) Required The name of Account holder (name of USER)
7 CollectAmountMin Int (11) Require Min collect amount (Min 50.000 vnd)
8 CollectAmountMax Int (11) Require Max collect amount (Max 50.000.000vnd)
9 AccNo String(17) Optional VA number (Max 17 characters).Note: BK won't check this field, can send NULL
10 OrderId String (25) Require Unique id for each VA
11 ExpireDate String (10) Optional Expire date. Format: YYYYMM-DD HH:II:SS
12 SubMerchant String (50) Optional Sub merchant
13 StoreCode String (20) Optional Store code

Body response success samples:

{
    ResponseCode:200,
    ResponseMessage:"Success",
    PartnerCode:"BK201907260657365",
    OrderId:"ORDER202002030001",
    CollectAmountMin:"50000",
    CollectAmountMax:"50000000",
    ExpireDate:"2025-05-09 12:00:00",
    AccountInfo: {
       "BANK":{
          "BankName":"Ngân hàng TNHH MTV Woori Việt Nam",
          "BankShortName":"WOORIBANK",
          "BankBranch":"Hà Nội",
          "AccNo":"902003000001",
          "AccName":"NGUYEN VAN AN",
          "Qr" : "base64 image return here",
          "QrPath" : "link qr image here",
       }
    }
}
                

Response pamram

# Parameters Datatypes Description
1 ResponseCode Int (4) The response status, is defined in Response Code.
2 ResponseMessage String (200) Description for return status, defined in Response Code
3 PartnerCode String(6) Account number code has been successfully created
4 OrderId String (50) Unique id for each VA (partner sent)
5 CollectAmountMin Int(11) Collect amount min
6 CollectAmountMax Int(11) ICollect amount max
7 ExpireDate String(10) Exprie date
8 AccountInfo JSON Account list

Update virtual account informations

Process:

1. PARTNER wanto change and save the USER changed informations , will call to “Virtual account information update”.

2. BAOKIM will check about datatype and the signature accuracy .

3. If every submitted datas are correct, BAOKIM will update the virtual account by the provided datas, At the same time BAOKIM will response to PARTNER.

Header request samples:

{
   Content-Type: "application/json",
   Signature:"hBMeZuDNPDD1TE9q3ojo+SSwA/FehW3H77y+3JkNHrdpRent ="
}
                

Body request samples:

{
    RequestId : "BK201907261428559",
    RequestTime : "2019-07-26 14:28:55",
    PartnerCode : "NTDAT",
    Operation : "9002",
    AccNo : "900300002294",
    AccName : "Nguyen Van B",
    CollectAmountMin : "50000",
    CollectAmountMax : "50000000",
    OrderId : "ORDER202002030001",
    ExpireDate : "2025-05-09 12:00:00",
}
                

Request pamram

# Parameters Datatypes Condition Description
1 RequestId String (50) Required The unique id for each Request from PARNTER to BAOKIM. Format: PARTNERCODE+YYYYMMD DHHIISS+UniqueId
2 RequestTime String (19) Required Time send the request from PARTNER , format: YYYY-MM-DD HH:MM:SS.
3 PartnerCode String (20) Required Unique code BAOKIM provide
4 Operation String (4) Required Fixed: 9002
5 AccNo String (20) Required VA number need to update information
6 AccName String(50) AccName The name of Account holder (name of USER)
7 CollectAmountMin Int (11) Optional Min collect amount (Min 50.000 vnd)
8 CollectAmountMax Int (11) Optional Min collect amount (Min 50.000.000 vnd)
9 OrderId String (25) Required Unique id for each VA
10 ExpireDate String (10) Optional Expire date. Format: YYYYMM-DD HH:II:SS

Body response success samples:

{
    ResponseCode : 200,
    ResponseMessage : "Success",
    PartnerCode : "BAOKIM",
    OrderId : "ORDER202002030001",
    CollectAmountMin : "50000",
    CollectAmountMax : "50000000",
    ExpireDate : "2020-05-09 12:00:00",
    AccountInfo : {
        "BANK": {
            "BankName":"Ngân hàng TNHH MTV Woori Việt Nam",
            "BankShortName":"WOORIBANK",
            "BankBranch":"Hà Nội",
            "AccNo":"900300002294",
            "AccName":"NGUYEN VAN B",
            "Qr" : "base64 image return here",
            "QrPath" : "link qr image here"
        }
    }
}
                

Response pamram

# Parameters Datatypes Description
1 ResponseCode Int (4) The response status, is defined in Response Code.
2 ResponseMessage String (200) Description for return status, defined in Response Code
3 PartnerCode String(6) Fix: BAOKIM
4 OrderId String (50) Unique id for each VA (partner sent)
5 CollectAmountMin Int(11) Collect amount min
6 CollectAmountMax Int(11) Collect amount max
7 ExpireDate String(10) Exprie date
8 AccountInfo JSON Account list

Virtual account information searching

Process:

1. When PARTNER want to get detail information of a virtual account, PARTNER will call to “Virtual account information searching”

2. BAOKIM will check the data type and the signature accuracy, if every submitted data is correct, BAOKIM will get and return all detail infomations of this virtual account , else return error.

Header request samples:

{
   Content-Type: "application/json",
   Signature:"hBMeZuDNPDD1TE9q3ojo+SSwA/FehW3H77y+3JkNHrdpRent ="
}
                

Body request samples:

{
    RequestId : "BK201907261509591",
    RequestTime : "2019-07-26 15:09:59",
    PartnerCode : "NTDAT",
    Operation : "9003",
    AccNo : "900300002294",
}
                

Request pamram

# Parameters Datatypes Condition Description
1 RequestId String (50) Required The unique id for each Request from PARNTER to BAOKIM. Format: PARTNERCODE+YYYYMMD DHHIISS+UniqueId
2 RequestTime String (19) Required Time send the request from PARTNER , format: YYYY-MM-DD HH:MM:SS.
3 PartnerCode String (20) Required Unique code BAOKIM provide
4 Operation Int (4) Required Fix: 9003.
5 AccNo String (20) Require VA number need to check information

Body response success samples:

{
    ResponseCode : 200,
    ResponseMessage : "Success",
    PartnerCode : "NTDAT",
    AccName : "NTDAT NGUYEN VAN B",
    AccNo : "900300002294",
    OrderId : "de83d309aad465b59cadb223f",
    CollectAmountMin : "50000",
    CollectAmountMax : "50000000",
    ExpireDate : "2020-07-28 00:00:00",
    TransactionList : null,
}
                

Response pamram

# Parameters Datatypes Description
1 ResponseCode Int (4) The response status, is defined in Response Code.
2 ResponseMessage String (200) Description for return status, defined in Response Code
3 PartnerCode String (20) Fix: BAOKIM
4 AccName String (20) VA owner name (unmarked, capitalized)
5 AccNo String (20) VA number PARTNER want to check
6 OrderId String (25) Unique id for each VA
7 CollectAmountMin Int (11) Collect amount min
8 CollectAmountMax Int (11) Collect amount max
9 ExpireDate String (10) Expire date partner sent
10 TransactionList String Transaction list

Collection transaction status searching

Process:

1. When PARTNER want to get all Collection transaction detail information, PARTNER will call to “Collection transaction detail information searching”.

2. BAOKIM will check about datatype and the signature accuracy, If every submitted datas are correct, BAOKIM will reponse exactly detail informations of this collection transaction.

Header request samples:

{
   Content-Type: "application/json",
   Signature:"hBMeZuDNPDD1TE9q3ojo+SSwA/FehW3H77y+3JkNHrdpRent ="
}
                

Body request samples:

{
    RequestId : "BK201907261549323",
    RequestTime : "2019-07-26 15:49:32",
    PartnerCode : "NTDAT",
    Operation : "9004",
    ReferenceId : "PARTNERCODE4b9e1152bf98d2e82935",
}
                

Request pamram

# Parameters Datatypes Condition Description
1 RequestId String (50) Required The unique id for each Request from PARNTER to BAOKIM. Format: PARTNERCODE+YYYYMMDDHHIIS S+UniqueId
2 RequestTime String (19) Required Time to send Request. Format: YYYY-MM-DD HH:II:SS
3 PartnerCode String (20) Required Unique code BAOKIM provide
4 Operation Int (4) Required Fixed: 9004
5 ReferenceId String (50) Required Transaction code (Generate when BAOKIM noti collection transaction to PARTNER via API)

Body response success samples:

{
    ResponseCode : 200,
    ResponseMessage : "Success",
    PartnerCode : "BAOKIM",
    AccNo : "900300000122",
    AccName : "BK NTDAT NGUYEN VAN B",
    PayerName : "Nguyen Van A",
    TransTimeBk : "2020-02-03 20:00:00",
    TransTimePartner : "2020-02-03 20:00:30",
    TransIdBk : "BK0000000001",
    TransIdPartner : "REFID0000000001",
    TransAmount : 500000,
    Memo : "Test giao dich",
}
                

Response pamram

# Parameters Datatypes Description
1 ResponseCode Int (4) The response status, is defined in Response Code.
2 ResponseMessage String (200) Description for return status, defined in Response Code
3 PartnerCode String (20) Fixed: BAOKIM
4 AccNo String (20) VA numbers
5 AccName String (50) VA owner name (unmarked, capitalized)
6 PayerName String (50) Payer name
7 TransTimeBk String (19) Trans time at BAOKIM system
8 TransTimePartner String (19) Trans time at PARTNER system
9 TransIdBk String(50) Transaction id in BAOKIM system
10 TransIdPartner String(50) Transaction id in PARTNER system
11 TransAmount int (11) Collect amount
12 Memo String (200) Content of money transfer

Collection at point

Process:

1. USER move to collection point then provide VA number (receive from Register virtual account).

2. Collection point send VA numbers to BAOKIM

3. BAOKIM will check then send information to PARTNER

4. PARTNER search information then response to BAOKIM, BAOKIM will response to collection point

Header request samples:

{
   Content-Type: "application/json",
}
                

Body request samples:

{
    RequestId:"PARTNERBK201909031120320001",
    RequestTime:"2019-09-03 11:20:32",
    PartnerCode:"BAOKIM",
    AccNo:"ACC00198374",
    Signature : "FYQ071FtJpPctvrvWScLwmG4Yiefl+48Ila8Og27+2JaGw0FEANa3hcL2Km4PRafzNPpgVRSAXRgfP7mqpfLUWmnLdWV9WRX6DI+ES\/xows+XQRM6M3zhEPV3YfnuEn8Yf\/Pp4r+jpSkScdruprXSmon79WxoL3TJzxZNFYR3YI="
}
                

Request pamram from BAOKIM

# Parameters Datatypes Condition Description
1 RequestId String (50) Required The unique id for each Request from PARNTER to BAOKIM. Format: PARTNERCODE+YYYYMMDDHHIIS S+UniqueId
2 RequestTime String (19) Required Time send the request from PARTNER , format: YYYY-MM-DD HH:MM:SS.
3 PartnerCode String (20) Required Partner code is defined in BAOKIM system, this code will be sent when partner start intergrating with BAOKIM
4 AccNo String (50) Required VA numbers
5 Signature String (500) Require The partner will digitally sign data transmitted by RSA and hash SHA1. Before sending to will base64 encoding. Format: RequestId|RequestTime|PartnerCode|AccNo

Body response success samples:

{
    ResponseCode:"200",
    ResponseMessage:"Success",
    AccNo:"900300000122",
    AccName:"NGUYEN VAN A",
    ClientIdNo:"123456789",
    OrderId:"OD2019090300001",
    ExpireDate:"2019-09-20",
    CollectAmount:"500000",
    CollectAmountMin:"50000",
    CollectAmountMax:"50000000",
    Info:{
        "Phone":"09123456789",
        "Address":"Số 102 Thái Thịnh, Đống Đa, Hà Nội",
        "ClientIdIssuedPlace":"Công an thành phố Hà Nội",
        "ClientIdIssuedDate":"12-10-2015"
    },
    Signature:"hBMeZuDNPDD1TE9q3ojo+SSwA/FehW3H77y+3JkNHrdpRent =",
}
                

Partner response pamram to BaoKim

# Parameters Datatypes Description
1 ResponseCode Int (4) The response status, is defined in Response Code.
2 ResponseMessage String (200) Description for return status, defined in Response Code
3 AccNo String (50) VA number BAOKIM send
4 AccName String (50) VA owner name
5 ClientIdNo String(12) Client id no
6 OrderId String (50) Unique id for each VA
7 ExpireDate String (10) Expire date
8 CollectAmount Int (11) Collect amount
9 CollectAmountMin Int (11) Collect amount min
10 CollectAmountMax Int (11) Collect amount max
11 Info JSON User information
12 Signature String (200) Baokim will sign with digital signature of data returned using RSACryptoServiceProvider. Returns the base64 encoding. Data is structured: ResponseCode|ResponseMessage|AccNo| AccName|ClientIdNo|OrderId|ExpireDate| CollectAmount|CollectAmountMin| CollectAmountMax

Notice of collection transaction (PARTNER Provide)

Process:

1. PARTNER build the system, to receive data notice the collection transaction.

2. When receive a new collection transaction, BAOKIM will call to “collection transaction notification” that provided by PARTNER to notice PARTNER need to update data.

Header request samples:

{
   Content-Type: "application/json",
}
                

Body request samples:

{
    RequestId : "BK72f3af40ef29600",
    RequestTime : "2019-07-26 16:33:12",
    PartnerCode : "NTDAT",
    AccNo : "900300001223",
    ClientIdNo : "909140379139",
    TransId : "5d3ac8a5a1a6b",
    TransAmount : 500000,
    TransTime : "2019-07-26 16:33:02",
    BefTransDebt : 9500000,
    AffTransDebt : 10000000,
    AccountType : 2,
    OrderId : "66c1ef5ed93eea2189fb8566e",
    Memo : "Transaction memo",
    Signature : "FYQ071FtJpPctvrvWScLwmG4Yiefl+48Ila8Og27+2JaGw0FEANa3hcL2Km4PRafzNPpgVRSAXRgfP7mqpfLUWmnLdWV9WRX6DI+ES\/xows+XQRM6M3zhEPV3YfnuEn8Yf\/Pp4r+jpSkScdruprXSmon79WxoL3TJzxZNFYR3YI="
}
                

Request pamram

# Parameters Datatypes Condition Description
1 RequestId String (50) Required Unique id for each request BAOKIM send to PARTNER.
2 RequestTime String (19) Required Time to send partner. Format: YYYY-MM-DD HH:II:SS
3 PartnerCode String (20) Required Fix: BAOKIM
4 AccNo String (50) Required VA number
5 ClientIdNo String (20) Require Client id no
6 TransId String (20) Require Unique transaction id in BAOKIM system
7 TransAmount Int (11) Require Collect amount
8 TransTime String (19) Require Transaction time at BAOKIM system
9 BefTransDebt Int (11) Require Amount before transaction
10 AffTransDebt Int (11) Require Amount after transaction
11 AccountType Int (1) Require Account with indentifier or without indentifier.
1: Account with identifier.
2: Account without identifier.
12 OrderId String (25) Require Unique id for each VA
13 Memo String (255) Optional Transaction memo
14 Signature String (500) Require BAOKIM will sign the data on the following structure sha1withRSA: RequestId|RequestTime|PartnerCode| AccNo|ClientIdNo|TransId|TransAmount| TransTime|BefTransDebt|AffTransDebt| AccountType|OrderId Then will use base64 encoding

Body response success samples:

{
    ResponseCode : 200,
    ResponseMessage : "Success",
    ReferenceId : "PARTNERCODE58b480bcb05126f7f789",
    AccNo : "900300001223",
    AffTransDebt : 9500000,
    Signature : "HqsE04yJKM\/82YWPDXN9KBCGbwA5T\/MhgQHmo4fkzbG9LGxPBdX+8vLDlR6EzO9HnMM5FNIQ8AjfReD+d13ksIwImzocr80S13gnPfYiCL611hfpQFZDz3KsXnYIXrm9TcIhwnuRnFibQ9GoBHCqGjiV9I5SPIoykzFiiyzdtKI="
}
                

Partner response pamram to BaoKim

# Parameters Datatypes Description
1 ResponseCode Int (4) The response status, is defined in Response Code.
2 ResponseMessage String (200) Description for return status, defined in Response Code
3 ReferenceId String (50) Unique transaction id in PARTNER system
4 AccNo String (20) VA number has transaction
5 AffTransDebt Int (11) Remain amount of VA
6 Signature String (200) Baokim will sign with digital signature of data returned using RSACryptoServiceProvider. Returns the base64 encoding. Data is structured: ResponseCode|ResponseMessage|ReferenceId| AccNo|AffTransDebt

Notice of account bank switching (PARTNER Provide)

Process:

1. When Bank A fails to use the support service, BAOKIM will update all VA accounts from other bank B as desired by the partner.

2. Successful update of BAOKIM will send information about this transaction via API to PARTNER.

3. PARTNER will check the information and return the results to BAOKIM

Header request samples:

{
   Content-Type: "application/json",
   Signature:"hBMeZuDNPDD1TE9q3ojo+SSwA/FehW3H77y+3JkNHrdpRent ="
}
                

Request Header

# Parameters Datatypes Description
1 Content-Type application/json
2 Signature String(50) BAOKIM will sign the Data with sha1WithRSA algorithm and use base64 encryption

Body request samples:

{
    RequestId : "BK72f3af40ef29600",
    RequestTime : "2020-02-03 16:19:11",
    PartnerCode : "BAOKIM",
    AccName : "BK Nhu Anh",
    AccNo : "909140379139",
    ExpirDate : "2020-09-21 16:20:01",
    OrderId : 500000,
    BankShortName : "VPBANK",
}
                

Request pamram

# Parameters Datatypes Condition Description
1 RequestId String (50) Required Unique id for each request BAOKIM send to PARTNER.
2 RequestTime String (19) Required Time to send partner. Format: YYYY-MM-DD HH:II:SS
3 PartnerCode String (20) Required Fix: BAOKIM
4 AccNo String (50) Required VA number
5 AccName String (50) Required VA owner name
6 ExpireDate Int (11) Require Expire date. Format: YYYYMM-DD HH:II:SS
7 OrderId String(25) Require Corresponding order code of USER
8 BankShortName String(20) Require Short name of the bank

Body response success samples:

{
    ResponseCode : 200,
    ResponseMessage : "Success",
    AccNo : "909140379139",
    Signature : "HqsE04yJKM\/82YWPDXN9KBCGbwA5T\/MhgQHmo4fkzbG9LGxPBdX+"
}
                

Partner response pamram to BaoKim

# Parameters Datatypes Description
1 ResponseCode Int (4) The response status, is defined in Response Code.
2 ResponseMessage String (200) Description for return status, defined in Response Code
3 AccNo String (20) VA number has transaction
4 Signature String (200) PARTNER will sign the Data with sha1WithRSA algorithm and use base64 encryption

Collection response code

ResponseCode ResponseMessage
200 Successful
99 Transaction timeout
11 Failed
101 Error processing from Baokim
102 Error from Bank
103 Operation is incorrect
104 RequestId or request is incorrect
105 PartnerCode is incorrect
106 AccName is incorrect
107 ClientIdNo is incorrect
108 IssuedDate hoặc IssuedPlace is incorrect
109 CollectAmount is incorrect
110 ExpireDate is incorrect
111 AccNo is incorrect
112 AccNo is not exist
113 RefferenceId is incorrect
114 RefferenceId isn’t exists
115 TransAmount is incorrect
116 TransTime is incorrect
117 BefTransDebt is incorrect
118 TransId is incorrect
119 AffTransDebt is incorrect
120 Signature is incorrect
121 AccountType is incorrect
122 OrderId is incorrect

* Red codes represent errors that will arpear when developing the function: "Notice of collection transaction"