Webhook kết quả chi

Quy trình

Mô tả:

• Baokim gửi webhook cho CashPlus khi một lệnh chi có kết quả cuối: Status=200 (thành công) hoặc Status=11 (thất bại).
• Áp dụng cho mọi lệnh:

Lệnh	Source	ReferenceId	Khi nào gửi
Lệnh realtime CashPlus gọi	PARTNER	Của lệnh	Khi có kết quả cuối, kể cả khi đã trả 200/11 ngay trong response
Lệnh T+1 CashPlus gọi (Merchant Type=2, CashPlus)	PARTNER	Của lệnh	Sau khi kỳ quyết toán T+1 xử lý xong
Lệnh Baokim tự tạo lúc 00:05 ngày T+1 cho phần chưa chi	AUTO	null	Sau khi kỳ quyết toán T+1 xử lý xong
Lệnh chi tay (lệnh 99 qua cutoff rồi thất bại, hoặc lệnh T+1 thất bại khi quyết toán)	MANUAL	Của lệnh gốc	Khi Baokim chi tay xong, TransIdPayment mới. Receiver là người thực nhận: người nhận gốc, hoặc 2 (Merchant) nếu lệnh gốc Retryable=false hoặc chi lại không được

• Mỗi lệnh có 1 kết quả cuối. Do cơ chế gửi lại, CashPlus có thể nhận cùng một webhook nhiều lần → xử lý idempotent theo TransIdPayment.
• Thứ tự webhook giữa các lệnh không được bảo đảm.

Gửi lại:

• Baokim ghi nhận thành công khi CashPlus trả HTTP 200 và body JSON có ResponseCode=200 trong 30 giây.
• Trường hợp khác, Baokim gửi lạ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.
• Hết số lần gửi lại mà vẫn thất bại, CashPlus dùng Tra cứu lệnh chi (với lệnh AUTO: tra theo TransactionId).

Thông tin API

Method: POST

URL: URL webhook kết quả chi do CashPlus cung cấp cho Baokim.

Header: Signature — chữ ký RSA-SHA1 của raw body bằng khóa riêng của Baokim. CashPlus verify bằng khóa công khai Baokim cung cấp (xem Bảo mật).

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
RequestTime	Datetime	✅	Thời gian gửi. Format: YYYY-MM-DD HH:mm:ss
PartnerCode	String	✅	Mã merchant của giao dịch thu hộ
TransactionId	String	✅	Mã giao dịch thu hộ
ReferenceId	String	❌	Mã lệnh chi phía CashPlus. null với lệnh AUTO
TransIdPayment	String	✅	Mã lệnh chi phía Baokim
Source	String	✅	PARTNER, AUTO hoặc MANUAL
Receiver	Integer	✅	Người nhận: 1 = User, 2 = Merchant, 3 = CashPlus
Type	Integer	✅	Hình thức chi: 1 = realtime, 2 = T+1
Status	Integer	✅	200 = thành công, 11 = thất bại
ErrorCode	String	❌	Mã lỗi chi tiết khi Status=11 (xem Mã lỗi)
Retryable	Boolean	❌	Chỉ có khi Status=11
Code	String	❌	Mã User (lệnh User)
RequestAmount	Integer	✅	Số tiền yêu cầu
FeeAmount	Integer	✅	Phí chi
SpendAmount	Integer	✅	Số tiền thực chuyển
AccountNo	String	✅	Số tài khoản nhận
BankNo	String	✅	Mã ngân hàng nhận
CreatedAt	Datetime	✅	Thời gian tạo lệnh
UpdatedAt	Datetime	✅	Thời gian có kết quả cuối

Ví dụ Request — lệnh CashPlus gọi

{
  "RequestId": "BK20250115100512",
  "RequestTime": "2025-01-15 10:05:12",
  "PartnerCode": "SHOP123",
  "TransactionId": "BK6AB9B10B92C04SZ",
  "ReferenceId": "CPSPEND0001",
  "TransIdPayment": "TP2501151005010001",
  "Source": "PARTNER",
  "Receiver": 2,
  "Type": 1,
  "Status": 200,
  "ErrorCode": null,
  "Code": null,
  "RequestAmount": 6860,
  "FeeAmount": 0,
  "SpendAmount": 6860,
  "AccountNo": "0123******89",
  "BankNo": "970436",
  "CreatedAt": "2025-01-15 10:05:01",
  "UpdatedAt": "2025-01-15 10:05:10"
}

Ví dụ Request — lệnh AUTO

{
  "RequestId": "BK20250116103015",
  "RequestTime": "2025-01-16 10:30:15",
  "PartnerCode": "SHOP123",
  "TransactionId": "BK6AB9B10B92C04SZ",
  "ReferenceId": null,
  "TransIdPayment": "TP2501152350590003",
  "Source": "AUTO",
  "Receiver": 2,
  "Type": 2,
  "Status": 200,
  "ErrorCode": null,
  "Code": null,
  "RequestAmount": 7150,
  "FeeAmount": 0,
  "SpendAmount": 7150,
  "AccountNo": "0123******89",
  "BankNo": "970436",
  "CreatedAt": "2025-01-15 23:50:59",
  "UpdatedAt": "2025-01-16 10:30:00"
}

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

Ví dụ Response

{
  "ResponseCode": 200,
  "ResponseMessage": "Success"
}

Xử lý phía CashPlus

1. Verify Signature. Sai chữ ký → không xử lý, trả ResponseCode khác 200.
2. Đã xử lý TransIdPayment này trước đó → trả ResponseCode=200, không xử lý lại.
3. Status=200 → ghi nhận chi thành công.
4. Status=11:
   • Retryable=true và còn trước cutoff: có thể gọi Lệnh chi mới với ReferenceId mới. Không gọi thì phần đó về Merchant T+1.
   • Retryable=false: không gọi lại. Với lệnh User: báo cho khách, phần User về Merchant T+1.
   • Lệnh 99 qua cutoff rồi thất bại: không gọi lại được (sau cutoff). Baokim sẽ chi tay và gửi thêm webhook Source=MANUAL.
5. Source=AUTO → ghi nhận phần tiền chưa chi của giao dịch đã được quyết toán về Merchant.
6. Source=MANUAL với Receiver khác lệnh gốc → phần tiền đã được chi về Merchant thay cho người nhận gốc. Với lệnh User: báo cho khách.