Tạo tài khoản ảo (VA)

Quy trình

Mô tả:

• CashPlus gọi API này để tạo tài khoản ảo (VA) và mã VietQR cho một đơn hàng. Khách hàng chuyển tiền vào VA, Baokim gửi Webhook thu hộ cho CashPlus.
• Mỗi OrderId chỉ có 1 VA. Gọi lại với OrderId đã tạo → Baokim trả ResponseCode=200 kèm thông tin VA đã tạo trước đó, không tạo VA mới.
• QR tĩnh: OrderId chứa chuỗi QRTINH → mã QR không gắn số tiền và VA không hết hạn (bỏ qua ExpireDate).
• QR theo số tiền: khi CollectAmountMin = CollectAmountMax, mã QR gắn sẵn số tiền này. Khi khác nhau, mã QR không gắn số tiền.

Thông tin API

Method: POST

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

• {env}: live (production) hoặc sanbox (test)

Header: Signature — chữ ký RSA-SHA1 của raw body (xem Bảo mật).

Request

Bảng tham số chính

Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
RequestId	String	✅	ID request, không trùng request trước. Tối đa 50 ký tự, chỉ gồm chữ, số, _, ., -
RequestTime	Datetime	✅	Thời gian request. Format: YYYY-MM-DD HH:mm:ss. Lệch không quá 10 phút so với giờ Baokim
PartnerCode	String	✅	Mã đối tác Baokim cung cấp
Operation	String	✅	Luôn truyền 9001
CreateType	Integer	✅	Luôn truyền 2
AccName	String	✅	Tên hiển thị của VA. Tối đa 50 ký tự, gồm chữ (có dấu), số, khoảng trắng, ., -, _
SubMerchant	String	❌	Mã sub merchant đã đăng ký với Baokim
StoreCode	String	❌	Mã cửa hàng. Bắt buộc nếu sub merchant đăng ký theo mô hình nhiều cửa hàng
CollectAmountMin	Integer	✅	Số tiền tối thiểu (VND), số nguyên, trong giới hạn Baokim cấu hình cho đối tác
CollectAmountMax	Integer	✅	Số tiền tối đa (VND), số nguyên, ≥ CollectAmountMin
OrderId	String	✅	Mã đơn hàng phía CashPlus. Tối đa 25 ký tự, không chứa khoảng trắng và ký tự đặc biệt
ExpireDate	Datetime	❌	Thời điểm hết hạn VA. Format: YYYY-MM-DD HH:mm:ss. Không truyền → VA không hết hạn
Memo	String	❌	Nội dung gắn vào mã QR. Baokim chuyển sang không dấu và bỏ ký tự đặc biệt

Ví dụ Request

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

Response

ghi chú

HTTP 200 - Thành công

Bảng tham số chính

Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
ResponseCode	Integer	✅	200 = thành công
ResponseMessage	String	✅	Thông báo
PartnerCode	String	❌	Luôn là BAOKIM. Chỉ có khi thành công
OrderId	String	❌	Mã đơn hàng
CollectAmountMin	Integer	❌	Số tiền tối thiểu
CollectAmountMax	Integer	❌	Số tiền tối đa
ExpireDate	Datetime	❌	Thời điểm hết hạn VA
AccountInfo	Object	❌	Thông tin VA. Xem bảng AccountInfo

AccountInfo.BANK

Tên trường	Kiểu dữ liệu	Mô tả
BankName	String	Tên ngân hàng của VA
BankShortName	String	Tên viết tắt ngân hàng (ví dụ BIDV, MSB, VPBANK)
BankBranch	String	Chi nhánh
AccNo	String	Số tài khoản ảo
AccName	String	Tên tài khoản ảo
Qr	String	Chuỗi nội dung mã VietQR. CashPlus dùng chuỗi này để tự hiển thị mã QR. Có thể null
QrPath	String	Đường dẫn ảnh mã QR. Có thể null

Ví dụ Response

{
  "ResponseCode": 200,
  "ResponseMessage": "Thành công",
  "PartnerCode": "BAOKIM",
  "OrderId": "ORD202501150001",
  "CollectAmountMin": 15000,
  "CollectAmountMax": 15000,
  "ExpireDate": "2025-01-16 10:30:00",
  "AccountInfo": {
    "BANK": {
      "BankName": "Ngân hàng Thương mại Cổ phần Đầu tư và Phát triển Việt Nam",
      "BankShortName": "BIDV",
      "BankBranch": "Hà Nội",
      "AccNo": "9620000123456",
      "AccName": "Cua hang A",
      "Qr": "00020101021238570010A000000727012700069704180113962000012345602...",
      "QrPath": "https://{QR_DOMAIN}/qr/ORD202501150001.png"
    }
  }
}

Ví dụ Response lỗi

{
  "ResponseCode": 109,
  "ResponseMessage": "CollectAmount không hợp lệ"
}

Error Codes

Mã lỗi	Mô tả
200	Thành công (kể cả gọi lại OrderId đã tạo)
11	Lỗi trong quá trình xử lý bên Baokim
103	Operation không hợp lệ (khác 9001)
104	RequestId hoặc RequestTime không hợp lệ (sai định dạng, trùng RequestId, hoặc lệch quá 10 phút)
105	Partner code không hợp lệ
106	AccName không hợp lệ
109	CollectAmount không hợp lệ (thiếu, không phải số nguyên, ngoài giới hạn, hoặc Min > Max)
110	ExpireDate không hợp lệ
120	Chữ ký không hợp lệ
122	OrderId không hợp lệ
123	CreateType không hợp lệ (khác 2)
124	SubMerchant không hợp lệ
125	StoreCode không hợp lệ