Chuyển tới nội dung chính

Lệnh chi

Quy trình​

Mô tả:

  • Mỗi request là 1 lệnh chi cho 1 người nhận, định danh bằng ReferenceId do CashPlus sinh.
  • Amount phải bằng đúng số đã đăng ký cho người nhận đó.
  • Mỗi người nhận chỉ có 1 lệnh hiệu lực: chỉ gọi được khi người nhận chưa có lệnh ở Status 0, 99 hoặc 200.
  • Lệnh của người nhận này không chặn lệnh của người nhận khác.
  • Baokim không tự gọi lại khi lệnh thất bại. Lệnh Status=11 có Retryable=true thì CashPlus được gọi lệnh mới (với ReferenceId mới) trước cutoff.
  • Chỉ nhận lệnh mới trước cutoff 23:50:59 ngày T. Sau cutoff, phần chưa chi được Baokim tự quyết toán về Merchant (xem Tổng quan).

Kết quả trả về ngay trong response:

StatusKhi nàoCashPlus làm tiếp
200Lệnh realtime chi thành côngGhi nhận. Vẫn nhận webhook kết quả chi
99Lệnh realtime đã tiếp nhận, chưa có kết quả cuốiChờ webhook kết quả chi hoặc tra cứu. Không gọi lệnh mới cho người nhận này
11Lệnh realtime thất bại, tiền chưa raXem Retryable và ErrorCode
0Lệnh T+1 đã tiếp nhận, chờ chi theo kỳ quyết toánChờ webhook kết quả chi

Thông tin API​

Method: POST

URL: {BASE_URL}/transaction/v2/spend

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ườngKiểu dữ liệuBắt buộcMô tả
RequestIdString✅ID request. Tối đa 50 ký tự, chỉ gồm chữ, số và -
RequestTimeDatetime✅Thời gian request. Format: YYYY-MM-DD HH:mm:ss. Lệch không quá 5 phút so với giờ Baokim
PartnerCodeString✅Mã merchant của giao dịch thu hộ
TransactionIdString✅Mã giao dịch thu hộ Baokim
ReferenceIdString✅Mã lệnh chi phía CashPlus, tối đa 50 ký tự, duy nhất. Gọi lại cùng ReferenceId không tạo lệnh mới
ReceiverInteger✅Người nhận: 1 = User, 2 = Merchant, 3 = CashPlus
TypeInteger✅Hình thức chi: 1 = realtime, 2 = T+1. Xem quy tắc Type
AmountInteger✅Số tiền chi (VND), bằng đúng số đã đăng ký cho Receiver, đã bao gồm phí chi
CodeString✅ (khi Receiver = 1)Mã User đã đồng bộ tài khoản
AccountNoString✅ (khi Receiver = 1)Số tài khoản nhận của User. Phải khớp tài khoản đã đồng bộ
BankNoString✅ (khi Receiver = 1)Mã ngân hàng nhận. Phải khớp tài khoản đã đồng bộ
MemoString❌Nội dung chuyển tiền. Không truyền → dùng Memo đã đăng ký

Quy tắc Type​

ReceiverType hợp lệ
1 (User)Luôn 1
2 (Merchant)Đúng Merchant.Type đã đăng ký
3 (CashPlus)Luôn 2

Phí chi​

Người nhận chịu phí chi: SpendAmount = Amount − FeeAmount.

LệnhPhí
Realtime cho UserTheo biểu phí realtime
Realtime cho MerchantTheo biểu phí realtime; 0 khi giao dịch được miễn phí chi Merchant
Mọi lệnh T+10

Amount không đủ trả phí chi realtime → 125.

Ví dụ Request​

{
  "RequestId": "CP20250115100501",
  "RequestTime": "2025-01-15 10:05:01",
  "PartnerCode": "SHOP123",
  "TransactionId": "BK6AB9B10B92C04SZ",
  "ReferenceId": "CPSPEND0001",
  "Receiver": 2,
  "Type": 1,
  "Amount": 6860,
  "Memo": "Thanh toan don hang 1001"
}

Ví dụ Request — lệnh chi User​

{
  "RequestId": "CP20250115143001",
  "RequestTime": "2025-01-15 14:30:01",
  "PartnerCode": "SHOP123",
  "TransactionId": "BK6AB9B10B92C04SZ",
  "ReferenceId": "CPSPEND0002",
  "Receiver": 1,
  "Type": 1,
  "Amount": 7000,
  "Code": "USER001",
  "AccountNo": "0123******89",
  "BankNo": "970416"
}

Thứ tự kiểm tra​

Baokim kiểm tra lần lượt. Gặp điều kiện đầu tiên không đạt thì trả lỗi, không tạo lệnh.

BướcĐiều kiệnKết quả nếu không đạt
1Chữ ký hợp lệ120
2Tham số đúng định dạng102, 110, 138, …
3ReferenceId chưa tồn tại với PartnerCode nàyCùng nội dung: trả ResponseCode=200 + lệnh đã có. Khác nội dung: 142
4TransactionId tồn tại và thuộc PartnerCode112
5Trước cutoff 23:50:59 ngày T141
6TransactionId đã đăng ký số tiền chia sẻ133
7Giao dịch được đăng ký qua API v2143
8Người nhận không có lệnh nào đang ở Status 0, 99 hoặc 200134
9Với Receiver = 1: chưa có lệnh User thất bại vì lỗi tài khoản User119
10Type hợp lệ theo quy tắc Type107
11Amount bằng số đã đăng ký cho người nhận136
12Với Receiver = 1: tài khoản khớp tài khoản đã đồng bộ103, 104, 111
13Amount > phí chi (lệnh realtime)125

Response​

ghi chú

HTTP 200 - Thành công

Bảng tham số chính​

Tên trườngKiểu dữ liệuBắt buộcMô tả
ResponseCodeInteger✅Kết quả tiếp nhận request. 200 = lệnh đã được tạo (hoặc đã tồn tại)
ResponseMessageString✅Thông báo
DataObject❌Thông tin lệnh chi. Chỉ có khi ResponseCode=200

Data​

Tên trườngKiểu dữ liệuMô tả
TransactionIdStringMã giao dịch thu hộ
ReferenceIdStringMã lệnh chi phía CashPlus
TransIdPaymentStringMã lệnh chi phía Baokim. Không đổi trong suốt vòng đời lệnh
ReceiverIntegerNgười nhận
TypeIntegerHình thức chi
StatusIntegerKết quả lệnh chi: 0, 99, 200, 11 (xem Mã lỗi)
ErrorCodeStringMã lỗi chi tiết khi Status=11
RetryableBooleanChỉ có khi Status=11. true = được gọi lệnh mới, false = không gọi lại
RequestAmountIntegerSố tiền yêu cầu (= Amount)
FeeAmountIntegerPhí chi
SpendAmountIntegerSố tiền thực chuyển cho người nhận
SourceStringLuôn PARTNER với lệnh CashPlus gọi

Ví dụ Response — lệnh realtime đang xử lý​

{
  "ResponseCode": 200,
  "ResponseMessage": "Thành công",
  "Data": {
    "TransactionId": "BK6AB9B10B92C04SZ",
    "ReferenceId": "CPSPEND0001",
    "TransIdPayment": "TP2501151005010001",
    "Receiver": 2,
    "Type": 1,
    "Status": 99,
    "ErrorCode": null,
    "RequestAmount": 6860,
    "FeeAmount": 0,
    "SpendAmount": 6860,
    "Source": "PARTNER"
  }
}

Ví dụ Response — lệnh User thất bại do lỗi tài khoản​

{
  "ResponseCode": 200,
  "ResponseMessage": "Thành công",
  "Data": {
    "TransactionId": "BK6AB9B10B92C04SZ",
    "ReferenceId": "CPSPEND0002",
    "TransIdPayment": "TP2501151430010002",
    "Receiver": 1,
    "Type": 1,
    "Status": 11,
    "ErrorCode": "118",
    "Retryable": false,
    "RequestAmount": 7000,
    "FeeAmount": 2500,
    "SpendAmount": 4500,
    "Source": "PARTNER"
  }
}

Ví dụ Response — sai số tiền​

{
  "ResponseCode": 136,
  "ResponseMessage": "Số tiền phải bằng số đã đăng ký cho người nhận"
}

Xử lý timeout​

Lệnh realtime được Baokim xử lý đồng bộ trước khi trả response, có thể mất tới 30 giây. CashPlus nên đặt timeout khi gọi API này tối thiểu 35 giây.

Nếu CashPlus không nhận được response (timeout, mất kết nối):

  1. Gọi lại cùng ReferenceId với cùng nội dung (hoặc tra cứu theo ReferenceId). Baokim không tạo lệnh trùng.
  2. Chỉ dùng ReferenceId mới khi tra cứu trả 137 (lệnh không tồn tại) và còn trước cutoff.

Error Codes​

Mã lỗiMô tả
200Lệnh đã được tạo hoặc đã tồn tại (xem Data.Status)
101Lỗi trong quá trình xử lý bên Baokim. Gọi lại với cùng ReferenceId
102RequestId hoặc RequestTime không hợp lệ (sai định dạng hoặc lệch quá 5 phút)
103User Code không hợp lệ (chưa đồng bộ)
104Số tài khoản User không khớp tài khoản đã đồng bộ
107Type không hợp lệ
110Partner Code không hợp lệ
111Mã ngân hàng User không khớp tài khoản đã đồng bộ
112Transaction ID không hợp lệ
119Lệnh User trước đó đã thất bại vì lỗi tài khoản User, không gọi lại
120Chữ ký không chính xác
125Số tiền không đủ trả phí chi
133Chưa đăng ký số tiền chia sẻ
134Người nhận đang có lệnh hiệu lực (Status 0, 99 hoặc 200)
136Số tiền khác số đã đăng ký cho người nhận
138ReferenceId không hợp lệ
141Quá thời gian cutoff 23:50:59 ngày giao dịch
142ReferenceId đã dùng cho lệnh khác nội dung
143Giao dịch đã được đăng ký qua API v1

Mã lỗi chi tiết của lệnh (ErrorCode khi Status=11): xem Mã lỗi.