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

Note: The handling procedure described in Case 2 also applies when the Partner receives a Timeout error, HTTP 502 (Bad Gateway), or HTTP 503 (Service Unavailable). In such cases, the Partner should not assume the transaction has failed and must first call the Check Transaction Status API to determine the final transaction status before performing any subsequent processing.

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 971025 NGÂN HÀNG MOMO - VÍ MOMO
62 668888 Đại chúng TNHH Kasikornbank - Chi nhánh TP. HCM
63 533948 Citibank, N.A, - Chi nhánh Hà Nội
64 963668 BNP Paribas - Chi nhánh Hà Nội
65 970000 DEUTSCHE BANK TP HCM
66 970001 Malayan Banking Berhad (Maybank)
67 970002 First commercial bank