Headers yêu cầu trong mỗi Request
| Header | Bắt buộc | Mô tả & Chuẩn |
|---|---|---|
| X-API-Key | Bắt buộc | Khóa bí mật API cấp riêng cho tài khoản. Chỉ truyền từ server-to-server. |
| Content-Type | Bắt buộc | application/json; charset=utf-8 |
| Idempotency-Key | Khuyến nghị cao | UUID v4 duy nhất cho mỗi giao dịch (RFC 8470). Chống trừ tiền trùng lặp khi mạng lag. |
X-API-Key: bg_live_8f3a9e2d1c4b7a6f...
Content-Type: application/json
Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6dQuy tắc quản lý vòng đời khóa
- 01Tách biệt khóa theo môi trường
Tạo khóa riêng cho môi trường Staging/Dev và khóa riêng cho Production để kiểm soát hạn mức độc lập.
- 02Cấu hình IP máy chủ
Chỉ định danh sách IP tĩnh của cụm máy chủ Backend được phép sử dụng khóa.
- 03Luân chuyển khóa định kỳ
BankGateway hỗ trợ tạo khóa mới trước, cập nhật vào hệ thống rồi mới thu hồi khóa cũ mà không gây gián đoạn dịch vụ.
- 04Thu hồi khẩn cấp
Nếu nghi ngờ lộ khóa, nhấn nút "Thu Hồi" trong Dashboard để vô hiệu hóa ngay tức thì.
Bảng mã lỗi xác thực
| Mã HTTP | Mã lỗi (error.code) | Nguyên nhân & Khắc phục |
|---|---|---|
| 401 | MISSING_CREDENTIALS | Chưa gửi header X-API-Key trong HTTP Request. |
| 401 | UNAUTHORIZED_API_KEY | Khóa API không hợp lệ hoặc đã bị thu hồi trong hệ thống. |
| 403 | IP_NOT_ALLOWED | Địa chỉ IP máy chủ gọi API không nằm trong danh sách IP Whitelist. |
| 403 | QUOTA_EXHAUSTED | Hạn mức requests được cấp cho API Key này đã hết. |
| 403 | ENDPOINT_BLOCKED | Khóa API này đang bị khóa quyền truy cập vào endpoint được gọi. |