Đăng ký số tiền chia sẻ

Quy trình

Mô tả:

• Sau khi nhận webhook thu hộ, CashPlus gọi API này để đăng ký số tiền chia cho 3 người nhận của giao dịch:

Người nhận	Trường	Hình thức chi
User (cashback)	User.Amount (U)	Luôn realtime
Merchant	Merchant.Amount (M)	Theo Merchant.Type: realtime hoặc T+1
CashPlus	Partner.Amount (P)	Luôn T+1

• API này chỉ ghi nhận số đăng ký, không chuyển tiền. Tiền chỉ được chi khi CashPlus gọi Lệnh chi cho từng người nhận.
• Đăng ký không cần tài khoản User. Chưa xác định được User thì vẫn đăng ký U; nếu tới cutoff không gọi chi được cho User thì phần U về Merchant.
• U + M + P phải nhỏ hơn hoặc bằng N (xem Tổng quan). Phần dư N − U − M − P (UnallocatedAmount) không gọi chi được và được quyết toán về Merchant tại cutoff.
• Mỗi TransactionId chỉ đăng ký 1 lần. Gọi lại với cùng TransactionId (dù số khác) → Baokim trả ResponseCode=200 kèm phân bổ của lần đầu, không ghi đè. Không có API sửa số đã đăng ký.

Thời hạn đăng ký

• Chỉ nhận trước cutoff 23:50:59 ngày T (ngày Baokim nhận tiền), theo giờ hệ thống Baokim (GMT+7) lúc nhận request.
• Quá hạn → 141, Baokim không ghi nhận. Toàn bộ N được quyết toán về Merchant theo T+1 (lệnh AUTO, xem Tổng quan).
• Giao dịch nhận tiền từ 23:50:59 đến 23:59:59 ngày T: không nhận đăng ký.
• Nên gọi trước 23:45 để tránh request bị xử lý sau cutoff.

Chính sách miễn phí

Áp dụng khi giao dịch thỏa cả 2 điều kiện:

• User.IsNewUser = 1 (User mới).
• Sub merchant đăng ký với Baokim chưa quá 3 tháng (tính từ ngày đăng ký đầu tiên còn hiệu lực).

Loại	Kết quả	Hạn mức
Miễn phí thu hộ	Baokim áp ngay khi đăng ký: TransFeeAmount = 0, N = TransAmount. Response trả N mới	Theo số lượt / sub merchant Baokim thông báo
Miễn phí chi realtime cho Merchant	Lệnh chi realtime cho Merchant (Receiver=2, Type=1) của giao dịch này có FeeAmount = 0	Theo số lượt / sub merchant Baokim thông báo, tính riêng với miễn phí thu hộ

Khi được miễn phí thu hộ, kiểm tra U + M + P ≤ N dùng N sau miễn phí.

Thông tin API

Method: POST

URL: {BASE_URL}/transaction/v2/share-amount

Header: Signature — chữ ký RSA-SHA1 của raw body (xem Bảo mật). Baokim kiểm chữ ký trước mọi kiểm tra khác.

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. Tối đa 50 ký tự, chỉ gồm chữ, số và -
RequestTime	Datetime	✅	Thời gian request. Format: YYYY-MM-DD HH:mm:ss. Lệch không quá 5 phút so với giờ Baokim
PartnerCode	String	✅	Mã merchant (sub merchant) của giao dịch thu hộ
TransactionId	String	✅	Mã giao dịch thu hộ Baokim (TransIdBk trong webhook thu hộ)
User	Object	✅	Phần chia cho User. Xem bảng User
Merchant	Object	✅	Phần chia cho Merchant. Xem bảng Merchant
Partner	Object	✅	Phần chia cho CashPlus. Xem bảng Partner

User

Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
Amount	Integer	✅	Số tiền cashback cho User (VND), ≥ 0. 0 = không có cashback, các trường còn lại của User không bắt buộc. Khác 0 thì tối thiểu 4.500
IsNewUser	Integer	✅ (khi Amount > 0)	1 = User mới, 2 = User cũ. Dùng cho chính sách miễn phí
Memo	String	✅ (khi Amount > 0)	Nội dung chuyển tiền mặc định cho lệnh chi User
Code	String	❌	Mã User đã đồng bộ tài khoản, nếu đã biết. Có thì phải khớp tài khoản đã đồng bộ (103)
AccNo	String	❌	Số tài khoản nhận của User, nếu đã biết (104)
BankNo	String	❌	Mã ngân hàng của tài khoản nhận, nếu đã biết (111)

Tài khoản nhận của User được chốt ở Lệnh chi cho User, không phải ở bước này.

Merchant

Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
Amount	Integer	✅	Số tiền chia cho Merchant (VND), ≥ 0. Với Type=1 và khác 0: phải lớn hơn phí chi realtime
Type	Integer	✅	Hình thức chi cho Merchant: 1 = realtime, 2 = T+1. Lệnh chi Merchant phải dùng đúng Type này
Memo	String	✅ (khi Type = 1)	Nội dung chuyển tiền cho Merchant

Partner

Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
Amount	Integer	✅	Số tiền chia cho CashPlus (VND), ≥ 0. Luôn chi T+1, miễn phí

Ví dụ Request

{
  "RequestId": "CP20250115100001",
  "RequestTime": "2025-01-15 10:00:01",
  "PartnerCode": "SHOP123",
  "TransactionId": "BK6AB9B10B92C04SZ",
  "User": {
    "Amount": 7000,
    "IsNewUser": 2,
    "Memo": "Hoan tien don hang 1001"
  },
  "Merchant": {
    "Amount": 6860,
    "Type": 1,
    "Memo": "Thanh toan don hang 1001"
  },
  "Partner": {
    "Amount": 150
  }
}

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	✅	Mã kết quả. 200 = đã đăng ký (hoặc đã đăng ký từ trước)
ResponseMessage	String	✅	Thông báo
Data	Object	❌	Phân bổ đã lưu. Chỉ có khi ResponseCode=200

Data

Tên trường	Kiểu dữ liệu	Mô tả
TransactionId	String	Mã giao dịch thu hộ
TransFeeAmount	Integer	Phí thu hộ sau khi áp chính sách miễn phí
AmountAfterFee	Integer	N dùng để chia
User	Object	Amount, Code, Memo, Type (luôn 1)
Merchant	Object	Amount, Type, Memo, FeeAmount (phí chi realtime dự kiến; 0 nếu Type 2 hoặc được miễn)
Partner	Object	Amount, Type (luôn 2)
UnallocatedAmount	Integer	Phần dư N − U − M − P, về Merchant tại cutoff

Ví dụ Response

{
  "ResponseCode": 200,
  "ResponseMessage": "Thành công",
  "Data": {
    "TransactionId": "BK6AB9B10B92C04SZ",
    "TransFeeAmount": 990,
    "AmountAfterFee": 14010,
    "User": {
      "Amount": 7000,
      "Code": null,
      "Memo": "Hoan tien don hang 1001",
      "Type": 1
    },
    "Merchant": {
      "Amount": 6860,
      "Type": 1,
      "Memo": "Thanh toan don hang 1001",
      "FeeAmount": 0
    },
    "Partner": {
      "Amount": 150,
      "Type": 2
    },
    "UnallocatedAmount": 0
  }
}

Error Codes

Mã lỗi	Mô tả
200	Thành công (kể cả gọi trùng TransactionId, trả phân bổ lần đầu)
11	Yêu cầu thất bại (thiếu object User/Merchant/Partner hoặc thiếu trường bắt buộc)
101	Lỗi trong quá trình xử lý bên Baokim
102	RequestId hoặc RequestTime không hợp lệ (sai định dạng hoặc lệch quá 5 phút)
103	User Code không hợp lệ (không khớp tài khoản đã đồng bộ)
104	User Account Number không hợp lệ
105	User Amount không hợp lệ (không phải số nguyên, < 0, hoặc khác 0 mà dưới 4.500)
106	Merchant Amount không hợp lệ (không phải số nguyên, < 0, hoặc Type=1 mà không đủ trả phí chi)
107	Merchant Type không hợp lệ
108	Partner Amount không hợp lệ
109	Total Amount không hợp lệ (U + M + P lớn hơn N)
110	Partner Code không hợp lệ
111	User Bank No không hợp lệ
112	Transaction ID không hợp lệ (không tồn tại hoặc không thuộc PartnerCode)
113	User memo không hợp lệ
114	Merchant memo không hợp lệ
115	User Is New User không hợp lệ
120	Chữ ký không chính xác
141	Quá thời gian cutoff 23:50:59 ngày giao dịch
143	Giao dịch đã được đăng ký qua API v1