Webhook thu hộ

Quy trình

Mô tả:

• Khi tài khoản ảo nhận được tiền, Baokim gửi webhook (POST) đến URL CashPlus đã đăng ký.
• CashPlus cần:
  1. Verify chữ ký ở header Signature (xem Bảo mật).
  2. Ghi nhận giao dịch theo TransIdBk.
  3. Trả response đúng format bên dưới để Baokim ghi nhận đã gửi thành công.
• Sau khi nhận webhook, CashPlus đăng ký số tiền chia sẻ cho giao dịch (dùng TransIdBk làm TransactionId) trước cutoff 23:50:59 ngày nhận tiền.

IsFull — thông tin tài khoản người trả

Webhook luôn có trường IsFull:

• IsFull = 0: Baokim chưa có thông tin tài khoản người chuyển tiền.
• IsFull = 1: Baokim đã có thông tin tài khoản người chuyển tiền. Code là mã User tương ứng nếu tài khoản này trùng tài khoản một User CashPlus đã đồng bộ.

Webhook đầu tiên được gửi ngay khi Baokim ghi nhận tiền, kể cả khi chưa có thông tin tài khoản người chuyển (IsFull = 0).

Khi thông tin tài khoản người chuyển được bổ sung sau, Baokim gửi đúng một webhook cập nhật với cùng TransIdBk, IsFull = 1 và Code (nếu khớp User đã đồng bộ). Giao dịch đã có IsFull = 1 ở webhook đầu thì không có bản cập nhật. CashPlus không coi bản cập nhật là webhook trùng: cập nhật thông tin người chuyển cho giao dịch đã có, không tạo giao dịch mới.

Thông tin API

Method: POST

URL: URL webhook do CashPlus cung cấp cho Baokim.

Header:

• Content-Type: application/json
• Signature: chữ ký RSA-SHA1 (Base64) của raw body bằng khóa riêng của Baokim

Request

(Baokim gửi cho CashPlus)

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 do Baokim sinh
RequestTime	Datetime	✅	Thời gian gửi. Format: YYYY-MM-DD HH:mm:ss
PartnerCode	String	✅	Luôn là BAOKIM
AccNo	String	✅	Số tài khoản ảo nhận tiền
TransIdBk	String	✅	Mã giao dịch thu hộ Baokim, duy nhất
TransAmount	Integer	✅	Số tiền giao dịch (VND)
TransTimeBk	Datetime	✅	Thời gian giao dịch. Format: YYYY-MM-DD HH:mm:ss
TransFeeAmount	Integer	✅	Phí thu hộ (VND)
AmountAfterFee	Integer	✅	TransAmount − TransFeeAmount
OrderId	String	✅	Mã đơn hàng CashPlus truyền khi tạo tài khoản ảo
Code	String	❌	Mã User của người chuyển tiền. null nếu chưa xác định được
Memo	String	✅	Nội dung chuyển tiền. Chuỗi rỗng nếu không có
IsFull	Integer	✅	0 = chưa có thông tin tài khoản người chuyển, 1 = đã có

Ví dụ Request

{
  "RequestId": "BK8F3K2A",
  "RequestTime": "2025-01-15 10:30:45",
  "PartnerCode": "BAOKIM",
  "AccNo": "1234567890",
  "TransIdBk": "BK6AB9B10B92C04SZ",
  "TransAmount": 15000,
  "TransTimeBk": "2025-01-15 10:30:30",
  "TransFeeAmount": 990,
  "AmountAfterFee": 14010,
  "OrderId": "ORD202501150001",
  "Code": "USER001",
  "Memo": "Thanh toan don hang",
  "IsFull": 1
}

Response

(CashPlus trả cho Baokim)

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 = đã nhận. Mã khác → Baokim gửi lại
ResponseMessage	String	✅	Thông báo
ReferenceId	String	✅	Mã giao dịch phía CashPlus tương ứng với TransIdBk
AccNo	String	✅	Số tài khoản ảo của giao dịch (trả lại AccNo đã nhận)

Ví dụ Response

{
  "ResponseCode": 200,
  "ResponseMessage": "Thành công",
  "ReferenceId": "CPTXN0001",
  "AccNo": "1234567890"
}

Chính sách gửi lại

Baokim ghi nhận gửi thành công chỉ khi CashPlus trả HTTP 200, body JSON có đủ 4 trường ResponseCode, ResponseMessage, ReferenceId, AccNo, và ResponseCode = 200.

Các trường hợp còn lại Baokim coi là thất bại và gửi lại:

• Không phản hồi trong 30 giây.
• Lỗi kết nối, HTTP 4xx/5xx.
• Body không phải JSON hoặc thiếu một trong 4 trường trên.
• ResponseCode khác 200.

Số lần gửi: tối đa 6 lần (1 lần đầu + 5 lần gửi lại), mỗi lần cách nhau ít nhất 1 phút. Sau đó Baokim dừng gửi. CashPlus dùng Tra cứu giao dịch để đối soát.

ghi chú

Xử lý idempotent theo TransIdBk: nhận lại cùng một TransIdBk do gửi lại thì trả ResponseCode=200 và không ghi nhận giao dịch lần hai. Ngoại lệ là webhook bổ sung IsFull = 1 mô tả ở trên.