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

Tra cứu lệnh chi

Quy trình​

Mô tả:

  • CashPlus gọi API này để lấy trạng thái hiện tại của lệnh chi. Gửi một trong hai:
    • ReferenceId: trả 1 lệnh.
    • TransactionId: trả phân bổ đã đăng ký và mọi lệnh của giao dịch, gồm lệnh Baokim tự tạo sau cutoff (Source=AUTO) và lệnh chi tay (Source=MANUAL).
  • Nên dùng khi:
    • Không nhận được response của Lệnh chi (timeout).
    • Lệnh đang Status=99 và chưa nhận được webhook kết quả chi.
    • Không nhận được webhook của lệnh AUTO (lệnh này không có ReferenceId, chỉ tra được theo TransactionId).
  • Với lệnh đang Status=99, Baokim cập nhật trạng thái mới nhất trước khi trả kết quả.
  • Tra cứu dùng được cả sau cutoff, không giới hạn thời gian.
  • Không có lệnh với ReferenceId này → 137. Khi đó, nếu còn trước cutoff, CashPlus có thể gọi lại lệnh chi.

Thông tin API​

Method: POST

URL: {BASE_URL}/transaction/v2/spend-result

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ộ
ReferenceIdString⚠️Mã lệnh chi phía CashPlus. Gửi một trong hai ReferenceId hoặc TransactionId
TransactionIdString⚠️Mã giao dịch thu hộ Baokim

Ví dụ Request — theo ReferenceId​

{
  "RequestId": "CP20250115103001",
  "RequestTime": "2025-01-15 10:30:01",
  "PartnerCode": "SHOP123",
  "ReferenceId": "CPSPEND0001"
}

Ví dụ Request — theo TransactionId​

{
  "RequestId": "CP20250116090001",
  "RequestTime": "2025-01-16 09:00:01",
  "PartnerCode": "SHOP123",
  "TransactionId": "BK6AB9B10B92C04SZ"
}

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✅200 = thành công
ResponseMessageString✅Thông báo
DataObject❌Chỉ có khi ResponseCode=200. Tra theo ReferenceId: một Lệnh chi. Tra theo TransactionId: {Allocation, Orders}

Lệnh chi​

Tên trườngKiểu dữ liệuMô tả
TransactionIdStringMã giao dịch thu hộ
ReferenceIdStringMã lệnh chi phía CashPlus. null với lệnh AUTO. Lệnh MANUAL mang ReferenceId của lệnh gốc
TransIdPaymentStringMã lệnh chi phía Baokim
ReceiverIntegerNgười nhận: 1 = User, 2 = Merchant, 3 = CashPlus
TypeIntegerHình thức chi: 1 = realtime, 2 = T+1
StatusIntegerTrạng thái lệnh: 0, 99, 200, 11 (xem Mã lỗi)
ErrorCodeStringMã lỗi chi tiết khi Status=11
RetryableBooleanChỉ có khi Status=11
RequestAmountIntegerSố tiền yêu cầu
FeeAmountIntegerPhí chi
SpendAmountIntegerSố tiền thực chuyển
SourceStringPARTNER, AUTO hoặc MANUAL
AccountNoStringSố tài khoản nhận
BankNoStringMã ngân hàng nhận

Allocation (khi tra theo TransactionId)​

TransactionId, AmountAfterFee (N), User.Amount, Merchant.Amount, Merchant.Type, Partner.Amount, UnallocatedAmount. Giao dịch chưa đăng ký thì ResponseCode=200, Allocation = null, Orders rỗng (hoặc chỉ có lệnh AUTO nếu Baokim đã tạo).

Orders là mảng Lệnh chi, có thể rỗng.

Ví dụ Response — theo ReferenceId​

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

Ví dụ Response — theo TransactionId, có lệnh AUTO​

{
  "ResponseCode": 200,
  "ResponseMessage": "Thành công",
  "Data": {
    "Allocation": {
      "TransactionId": "BK6AB9B10B92C04SZ",
      "AmountAfterFee": 14010,
      "User": { "Amount": 7000 },
      "Merchant": { "Amount": 6860, "Type": 1 },
      "Partner": { "Amount": 150 },
      "UnallocatedAmount": 0
    },
    "Orders": [
      {
        "TransactionId": "BK6AB9B10B92C04SZ",
        "ReferenceId": "CPSPEND0001",
        "TransIdPayment": "TP2501151005010001",
        "Receiver": 2,
        "Type": 1,
        "Status": 200,
        "ErrorCode": null,
        "RequestAmount": 6860,
        "FeeAmount": 0,
        "SpendAmount": 6860,
        "Source": "PARTNER",
        "AccountNo": "0123******89",
        "BankNo": "970436"
      },
      {
        "TransactionId": "BK6AB9B10B92C04SZ",
        "ReferenceId": null,
        "TransIdPayment": "TP2501152350590003",
        "Receiver": 2,
        "Type": 2,
        "Status": 0,
        "ErrorCode": null,
        "RequestAmount": 7150,
        "FeeAmount": 0,
        "SpendAmount": 7150,
        "Source": "AUTO",
        "AccountNo": "0123******89",
        "BankNo": "970436"
      }
    ]
  }
}

Ví dụ Response — không tìm thấy lệnh​

{
  "ResponseCode": 137,
  "ResponseMessage": "Lệnh chi không tồn tại"
}

Error Codes​

Mã lỗiMô tả
200Thành công
11Thiếu cả ReferenceId lẫn TransactionId, hoặc gửi cả hai
101Lỗi trong quá trình xử lý bên Baokim. Gọi lại sau ít phút
102RequestId hoặc RequestTime không hợp lệ (sai định dạng hoặc lệch quá 5 phút)
110Partner Code không hợp lệ
112Transaction ID không tồn tại hoặc không thuộc PartnerCode
120Chữ ký không chính xác
137Lệnh chi không tồn tại
138ReferenceId không hợp lệ