Create Virtual Account (VA)

Process

Description:

• CashPlus calls this API to create a virtual account (VA) and VietQR code for an order. Customer transfers money into the VA, Baokim sends Collection Webhook to CashPlus.
• Each OrderId has only 1 VA. Calling again with an already created OrderId → Baokim returns ResponseCode=200 with the previously created VA information, does not create new VA.
• Static QR: if OrderId contains QRTINH → QR code is not embedded with amount and VA has no expiration (ignores ExpireDate).
• Dynamic QR by amount: when CollectAmountMin = CollectAmountMax, QR code is embedded with this amount. When different, QR code is not embedded with amount.

API Information

Method: POST

URL: {BASE_URL}/collection/{env}/v1

• {env}: live (production) or sanbox (test)

Header: Signature — RSA-SHA1 signature of raw body (see Security).

Request

Main Parameter Table

Field Name	Data Type	Required	Description
RequestId	String	✅	Request ID, unique. Max 50 characters, alphanumeric and _, ., -
RequestTime	Datetime	✅	Request time. Format: YYYY-MM-DD HH:mm:ss. Time difference must not exceed 10 minutes from Baokim time
PartnerCode	String	✅	Partner code provided by Baokim
Operation	String	✅	Always 9001
CreateType	Integer	✅	Always 2
AccName	String	✅	Display name of the VA. Max 50 characters, letters (with diacritics), digits, spaces, ., -, _
SubMerchant	String	❌	Sub merchant code registered with Baokim
StoreCode	String	❌	Store code. Required if sub merchant uses multi-store model
CollectAmountMin	Integer	✅	Minimum collect amount (VND), integer, within Baokim's limit for partner
CollectAmountMax	Integer	✅	Maximum collect amount (VND), integer, ≥ CollectAmountMin
OrderId	String	✅	Order ID from CashPlus side. Max 25 characters, no spaces or special characters
ExpireDate	Datetime	❌	VA expiration time. Format: YYYY-MM-DD HH:mm:ss. If not provided → VA has no expiration
Memo	String	❌	Memo attached to QR code. Baokim converts to non-diacritical and removes special characters

Request Example

{
  "RequestId": "CP20250115103000",
  "RequestTime": "2025-01-15 10:30:00",
  "PartnerCode": "CASHPLUS",
  "Operation": "9001",
  "CreateType": 2,
  "AccName": "Store A",
  "SubMerchant": "SHOP123",
  "StoreCode": "STORE001",
  "CollectAmountMin": 15000,
  "CollectAmountMax": 15000,
  "OrderId": "ORD202501150001",
  "ExpireDate": "2025-01-16 10:30:00",
  "Memo": "Order payment"
}

Response

note

HTTP 200 - Success

Main Parameter Table

Field Name	Data Type	Required	Description
ResponseCode	Integer	✅	200 = success
ResponseMessage	String	✅	Response message
PartnerCode	String	❌	Always BAOKIM. Only present when successful
OrderId	String	❌	Order ID
CollectAmountMin	Integer	❌	Minimum collect amount
CollectAmountMax	Integer	❌	Maximum collect amount
ExpireDate	Datetime	❌	VA expiration time
AccountInfo	Object	❌	VA information. See AccountInfo table

AccountInfo.BANK

Field Name	Data Type	Description
BankName	String	Bank name of the VA
BankShortName	String	Bank short name (e.g. BIDV, MSB, VPBANK)
BankBranch	String	Branch
AccNo	String	Virtual account number
AccName	String	Virtual account name
Qr	String	VietQR code string. CashPlus uses this string to display the QR code themselves. Can be null
QrPath	String	QR code image path. Can be null

Response Example

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "PartnerCode": "BAOKIM",
  "OrderId": "ORD202501150001",
  "CollectAmountMin": 15000,
  "CollectAmountMax": 15000,
  "ExpireDate": "2025-01-16 10:30:00",
  "AccountInfo": {
    "BANK": {
      "BankName": "Joint Stock Commercial Bank for Investment and Development of Vietnam",
      "BankShortName": "BIDV",
      "BankBranch": "Ha Noi",
      "AccNo": "9620000123456",
      "AccName": "Store A",
      "Qr": "00020101021238570010A000000727012700069704180113962000012345602...",
      "QrPath": "https://{QR_DOMAIN}/qr/ORD202501150001.png"
    }
  }
}

Error Response Example

{
  "ResponseCode": 109,
  "ResponseMessage": "CollectAmount is invalid"
}

Error Codes

Error Code	Description
200	Success (including retry with already created OrderId)
11	Error during Baokim processing
103	Operation is invalid (not 9001)
104	RequestId or RequestTime is invalid (wrong format, duplicate RequestId, or time difference exceeds 10 minutes)
105	Partner code is invalid
106	AccName is invalid
109	CollectAmount is invalid (missing, not integer, out of limits, or Min > Max)
110	ExpireDate is invalid
120	Signature is invalid
122	OrderId is invalid
123	CreateType is invalid (not 2)
124	SubMerchant is invalid
125	StoreCode is invalid