Mã lỗi
Luồng chia sẻ tiền dùng 3 loại mã khác nhau:
| Loại | Trường | Ý nghĩa |
|---|---|---|
| Mã phản hồi | ResponseCode | Request có được Baokim tiếp nhận hay không |
| Trạng thái lệnh chi | Data.Status | Kết quả chuyển tiền của lệnh chi |
| Mã lỗi chi tiết | Data.ErrorCode, Data.Retryable | Nguyên nhân khi lệnh chi thất bại (Status=11) và có được gọi lại không |
ResponseCode=200 chỉ có nghĩa là Baokim đã nhận request. Muốn biết tiền đã chuyển hay chưa, xem Status.
Mã lỗi của nhóm API thu hộ và tra cứu dữ liệu được ghi ở từng trang API tương ứng.
ResponseCode — Mã phản hồi
| Mã | Ý nghĩa | API | CashPlus nên làm |
|---|---|---|---|
| 200 | Thành công | Tất cả | Đọc Data |
| 11 | Yêu cầu thất bại | Đăng ký, Tra cứu | Kiểm tra lại request (thiếu object hoặc trường bắt buộc) |
| 101 | Lỗi trong quá trình xử lý bên Baokim | Tất cả | Gọi lại. Với lệnh chi: gọi lại cùng ReferenceId |
| 102 | RequestId hoặc RequestTime không hợp lệ | Tất cả | Sửa RequestId/RequestTime, gọi lại |
| 103 | User Code không hợp lệ | Đăng ký, Lệnh chi (User) | Kiểm tra User đã đồng bộ tài khoản |
| 104 | User Account Number không hợp lệ | Đăng ký, Lệnh chi (User) | Sửa số tài khoản cho khớp tài khoản đã đồng bộ |
| 105 | User Amount không hợp lệ | Đăng ký | Sửa User.Amount |
| 106 | Merchant Amount không hợp lệ | Đăng ký | Sửa Merchant.Amount |
| 107 | Merchant Type / Type không hợp lệ | Đăng ký, Lệnh chi | Sửa Type theo quy tắc Type |
| 108 | Partner Amount không hợp lệ | Đăng ký | Sửa Partner.Amount |
| 109 | Total Amount không hợp lệ (U + M + P > N) | Đăng ký | Giảm số chia |
| 110 | Partner Code không hợp lệ | Tất cả | Kiểm tra PartnerCode |
| 111 | User Bank No không hợp lệ | Đăng ký, Lệnh chi (User) | Sửa mã ngân hàng cho khớp tài khoản đã đồng bộ |
| 112 | Transaction ID không hợp lệ | Đăng ký, Lệnh chi, Tra cứu | Giao dịch không tồn tại hoặc không thuộc PartnerCode |
| 113 | User memo không hợp lệ | Đăng ký | Bổ sung User.Memo |
| 114 | Merchant memo không hợp lệ | Đăng ký | Bổ sung Merchant.Memo |
| 115 | User Is New User không hợp lệ | Đăng ký | User.IsNewUser = 1 hoặc 2 |
| 119 | Tài khoản User không nhận được tiền | Lệnh chi (User) | Lệnh User trước đó đã thất bại vì lỗi tài khoản User. Không gọi lại; phần User về Merchant T+1 |
| 120 | Chữ ký không chính xác | Tất cả | Kiểm tra chữ ký |
| 125 | Số tiền không đủ trả phí chi | Lệnh chi | Số đăng ký cho người nhận không đủ trả phí realtime |
| 133 | Chưa đăng ký số tiền chia sẻ | Lệnh chi | Gọi Đăng ký số tiền chia sẻ trước |
| 134 | Người nhận đang có lệnh hiệu lực (Status 0, 99 hoặc 200) | Lệnh chi | Tra cứu lệnh cũ, không gọi lệnh mới |
| 136 | Số tiền khác số đã đăng ký cho người nhận | Lệnh chi | Gửi Amount bằng đúng số đã đăng ký |
| 137 | Lệnh chi không tồn tại | Tra cứu | Nếu còn trước cutoff: gọi lại lệnh (nên dùng cùng ReferenceId) |
| 138 | ReferenceId không hợp lệ | Lệnh chi, Tra cứu | Sửa ReferenceId |
| 141 | Quá thời gian cutoff 23:50:59 ngày giao dịch | Đăng ký, Lệnh chi | Dừng, không gọi lại. Phần tiền được quyết toán T+1 về Merchant |
| 142 | ReferenceId đã dùng cho lệnh khác nội dung | Lệnh chi | Dùng ReferenceId mới cho lệnh mới; tra cứu ReferenceId cũ nếu cần |
| 143 | Giao dịch đã đăng ký qua phiên bản API khác, hoặc API v1 đã ngừng | Đăng ký, Lệnh chi | Dùng đúng phiên bản đã đăng ký giao dịch (xem Phiên bản API) |
Status — Trạng thái lệnh chi
| Status | Ý nghĩa | Trạng thái cuối | Tiền của người nhận | CashPlus nên làm |
|---|---|---|---|---|
| 0 | Lệnh T+1 đã tiếp nhận, chờ chi theo kỳ quyết toán | ❌ | Đang giữ | Chờ webhook |
| 99 | Baokim đang xử lý, chưa có kết quả cuối | ❌ | Đang giữ | Chờ webhook hoặc tra cứu. Không gọi lệnh mới cho người nhận này |
| 200 | Chi thành công | ✅ | Đã chi | Ghi nhận thành công |
| 11 | Chi thất bại, tiền chưa ra | ✅ | Chưa chi | Xem Retryable và ErrorCode |
200và11là trạng thái cuối, không thay đổi nữa.- Baokim chỉ trả
11khi chắc chắn tiền chưa ra. Chưa chắc chắn thì lệnh giữ99cho tới khi có kết quả. - Lệnh
11không được Baokim tự chi lại. Không gọi lại trước cutoff thì phần tiền đó về Merchant T+1.
ErrorCode — Mã lỗi chi tiết của lệnh chi
Khi Status=11, lệnh có thêm:
ErrorCode: mã lỗi từ hệ thống chi.Retryable:true= được gọi lệnh mới (vớiReferenceIdmới, trước cutoff);false= không gọi lại.
| Nhóm | Retryable | Ví dụ | CashPlus nên làm |
|---|---|---|---|
| Lỗi tài khoản nhận của User (tài khoản không tồn tại, bị khóa, ví điện tử, tài khoản định danh không nhận chuyển khoản) | false | 118 | Không gọi lại lệnh User. Báo cho khách. Phần User về Merchant T+1 |
| Vượt hạn mức, lỗi ngân hàng, lỗi hệ thống | true | 129, 130 | Gọi lệnh mới trước cutoff, hoặc để phần đó về Merchant T+1 |
Danh sách đầy đủ ErrorCode theo từng nhóm được Baokim cung cấp khi tích hợp. CashPlus nên dựa vào Retryable, không tự phân loại theo ErrorCode.
Ví dụ
Gọi trùng ReferenceId — Lần 1 timeout, CashPlus gọi lại cùng ReferenceId=CPSPEND0001 với cùng nội dung → ResponseCode=200, Data là lệnh đã tạo ở lần 1, không phát sinh lệnh mới. Gọi lại cùng ReferenceId nhưng khác Amount → 142.
Người nhận đang có lệnh hiệu lực — Lệnh Merchant CPSPEND0001 đang Status=99, CashPlus gọi Merchant với ReferenceId=CPSPEND0002 → ResponseCode=134.
Hết hạn mức — Lệnh User trả Status=11, ErrorCode=129, Retryable=true. CashPlus gọi lệnh User mới với ReferenceId mới trước 23:50:59.
Lỗi tài khoản User — Lệnh User trả Status=11, ErrorCode=118, Retryable=false. CashPlus gọi lệnh User mới → 119. Phần User được quyết toán về Merchant tại cutoff.