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

Xử lý Timeout

Khuyến nghị​

Các nguyên tắc dưới đây là khuyến nghị chung, suy ra từ cơ chế Idempotency (request_id) đã mô tả tại trang Bảo mật — phần lớn tài liệu gốc của từng nhóm API (VA, BNPL, Installment, Thẻ quốc tế, Master Basic/Pro, Master VA, Master Thẻ tín dụng) không có mục Xử lý timeout riêng, nên đây chưa phải spec chính thức được dev xác nhận cho từng API.

Client nên đặt timeout hợp lý để tránh hai tình huống cực đoan:

  • Chờ vô hạn — gây treo ứng dụng nếu server không phản hồi.
  • Cắt quá sớm — huỷ request khi server đang xử lý bình thường (đặc biệt với các API thanh toán cần thời gian xử lý với ngân hàng).

Khuyến nghị: đặt timeout 30–60 giây cho các API tạo giao dịch.

Yêu cầu về timeout​

Khi gặp timeout, không được retry mù quáng (blind retry). Thay vào đó:

  1. Gọi API tra cứu giao dịch (Get Transaction Status) để kiểm tra xem giao dịch đã được tạo hay chưa.
  2. Chỉ tạo lại giao dịch nếu xác nhận giao dịch chưa tồn tại.

Khóa Idempotency​

request_id là Idempotency key bắt buộc với tất cả API tạo giao dịch (Create Payment). Khi retry sau timeout, Merchant giữ nguyên request_id cũ để Baokim nhận ra đây là request đã xử lý và trả về kết quả cũ thay vì tạo giao dịch mới — giúp tránh duplicate charge.

Thử lại APIs​

Các API có thể retry an toàn (idempotent by nature):

  • GET tra cứu trạng thái giao dịch
  • GET lấy danh sách ngân hàng / gói vay

Các API không nên retry mù quáng:

  • Tất cả API tạo giao dịch (Create Payment, tạo đơn hàng, tạo VA...) nếu không có request_id mới hoặc chưa kiểm tra trạng thái trước.

Lưu ý riêng cho QRPay/QRGlobal​

Khi MERCHANT gọi API QRPay mà không nhận được phản hồi:

  • Không tự kết luận giao dịch thất bại. Trạng thái cuối cùng luôn căn cứ theo Webhook thông báo giao dịch hoặc kết quả tra cứu.

  • Với API Tạo mã QR: gọi API Tra cứu giao dịch theo mrc_order_id để xác nhận đơn đã được khởi tạo hay chưa trước khi gọi lại. Nếu gọi lại với mrc_order_id đã tồn tại, hệ thống trả về mã lỗi 707.

  • Với API Hoàn tiền (luồng bất đồng bộ): nếu không nhận được phản hồi tiếp nhận, gọi lại với request_id mới; hệ thống đảm bảo không xử lý trùng yêu cầu hoàn tiền vượt quá số tiền có thể hoàn của giao dịch gốc.

  • Không nhận được Webhook sau thời gian chờ dự kiến: MERCHANT chủ động gọi API Tra cứu giao dịch để đồng bộ trạng thái.

Khi MERCHANT gọi API Deeplink mà không nhận được phản hồi:

  • Không tự kết luận giao dịch thất bại. Trạng thái cuối cùng luôn căn cứ theo thông báo kết quả từ Baokim.
  • Với API Tạo Deeplink: không retry ngay lập tức. Kiểm tra xem request_id đã được xử lý chưa trước khi gọi lại. Nếu retry, sử dụng cùng request_id cũ để tránh tạo trùng giao dịch.
  • Deeplink có thời hạn (expired_at): nếu Deeplink đã hết hạn mà người dùng chưa thanh toán, cần tạo lại Deeplink mới với request_id mới.
  • Với API Lấy danh sách ngân hàng (GET): có thể retry an toàn vì là API tra cứu thuần tuý.