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.

Collection payments

A set of APIs to accept payments
Disbursement payments

Send money to any bank account via instant transfers
Cash transfer by identification

Send cash money to customer

Benefits of Baokim

Fast integration
Instant transfers
Daily reconciliation
Simple & competitive pricing – no hidden fees

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==

You must replace YmFva2ltOmJrQDEyMzQ1Ng== with your account.

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	✓

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
Header	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
Header	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
}

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

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":"Ngân hàng TNHH MTV Woori Việt Nam",
          "BankShortName":"WOORIBANK",
          "BankBranch":"Hà 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",
    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	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"

Introduction

Collection payments

Disbursement payments

Cash transfer by identification

Benefits of Baokim

Regulations and requirements

Restful and Digital Signature

Restfull Web Service

Digital signature

Private key and public key

Disbursement payments

Definition API

Verify customer information

Request pamram

Response pamram

Transfer money

Request pamram

Response pamram

Look up for transfer info

Request pamram

Response pamram

Look up for Partner balance

Request param

Response param

Describe the mechanism handling the transaction timeout

Response Code

List of bank transfer assistance

Collection payments version 2

Definition API

Request information to BAOKIM

Response from BAOKIM to PARTNER

Register virtual account

Request pamram

Response pamram

Update virtual account informations

Request pamram

Response pamram

Virtual account information searching

Request pamram

Response pamram

Collection transaction status searching

Request pamram

Response pamram

Collection at point

Request pamram from BAOKIM

Partner response pamram to BaoKim

Notice of collection transaction (PARTNER Provide)

Request pamram

Partner response pamram to BaoKim

Notice of account bank switching (PARTNER Provide)

Request Header

Request pamram

Partner response pamram to BaoKim

Collection response code