Tổng quan API Cổng Thanh Toán HiTechCloud Pay
Đặc tả REST API Cổng thanh toán HiTechCloud Pay: xác thực, ký chữ ký, mã phản hồi HTTP, phân trang và chuẩn dữ liệu dùng chung cho mọi endpoint.
Ngoài việc khởi tạo thanh toán qua form Checkout, HiTechCloud Pay cung cấp bộ REST API chuẩn cho phép máy chủ của bạn tra cứu trạng thái đơn hàng, đối soát các giao dịch đã thu và kiểm tra lịch sử thanh toán.
Base URLs
| Môi trường | Base URL |
|---|---|
| Production | https://pgapi.hitechcloud.vn |
| Sandbox | https://pgapi-sandbox.hitechcloud.vn |
Phương thức xác thực
Mọi cuộc gọi đến REST API Cổng thanh toán đều sử dụng HTTP Basic Authentication với username là merchant_id và password là secret_key.
Authorization: Basic base64(YOUR_MERCHANT_ID:YOUR_SECRET_KEY)
Content-Type: application/json
Accept: application/jsonBảng mã lỗi chi tiết (API Error Codes)
| Mã HTTP | Error Code | Ý nghĩa & Nguyên nhân | Cách xử lý |
|---|---|---|---|
400 | INVALID_SIGNATURE | Chữ ký HMAC-SHA256 không hợp lệ hoặc sai secret key | Kiểm tra thứ tự sắp xếp tham số và secret key |
400 | MISSING_REQUIRED_FIELD | Thiếu trường dữ liệu bắt buộc | Bổ sung đầy đủ merchant_id, order_invoice_number... |
401 | UNAUTHORIZED | Sai Merchant ID hoặc Secret Key | Xác thực lại cặp khóa trên my.hitechcloud.vn |
403 | IP_NOT_ALLOWED | Địa chỉ IP gọi API không nằm trong Whitelist | Đăng ký IP máy chủ tại mục Bảo mật API |
404 | ORDER_NOT_FOUND | Không tìm thấy đơn hàng với mã hóa đơn yêu cầu | Kiểm tra lại order_invoice_number |
409 | ORDER_ALREADY_PAID | Đơn hàng này đã được thanh toán trước đó | Không được phép khởi tạo thanh toán lại cho đơn đã thanh toán |
410 | ORDER_EXPIRED | Phiên thanh toán đã hết hạn | Khởi tạo phiên thanh toán mới cho khách |
422 | AMOUNT_BELOW_MINIMUM | Số tiền thanh toán nhỏ hơn mức tối thiểu (1,000 VNĐ) | Cập nhật số tiền đơn hàng hợp lệ |
429 | RATE_LIMIT_EXCEEDED | Vượt quá hạn mức 60 req/phút | Giảm tần suất polling, áp dụng Exponential Backoff |
500 | INTERNAL_SERVER_ERROR | Lỗi máy chủ HiTechCloud Pay | Liên hệ bộ phận kỹ thuật để hỗ trợ |
Cấu trúc phản hồi lỗi chuẩn (JSON)
{
"status": "error",
"code": "INVALID_SIGNATURE",
"message": "Chữ ký HMAC-SHA256 không khớp với dữ liệu gửi lên.",
"errors": {
"signature": [
"Signature verification failed for merchant HTC_MCH_123456"
]
},
"timestamp": 1759134700
}Rate Limiting Headers
| Header | Mô tả |
|---|---|
X-RateLimit-Limit | Số lượng request tối đa được phép trong 1 phút (mặc định 60) |
X-RateLimit-Remaining | Số lượng request còn lại trong cửa sổ thời gian hiện tại |
X-RateLimit-Reset | Thời điểm (Unix timestamp) giới hạn được reset lại |
Ngoài việc khởi tạo thanh toán qua form Checkout, HiTechCloud Pay cung cấp bộ REST API chuẩn cho phép máy chủ của bạn tra cứu trạng thái đơn hàng, đối soát các giao dịch đã thu và kiểm tra lịch sử thanh toán.
Base URLs
| Môi trường | Base URL |
|---|---|
| Production | https://pgapi.hitechcloud.vn |
| Sandbox | https://pgapi-sandbox.hitechcloud.vn |
Phương thức xác thực
Mọi cuộc gọi đến REST API Cổng thanh toán đều sử dụng HTTP Basic Authentication với username là merchant_id và password là secret_key.
Bảng mã lỗi chi tiết (API Error Codes)
| Mã HTTP | Error Code | Ý nghĩa & Nguyên nhân | Cách xử lý |
|---|---|---|---|
400 | INVALID_SIGNATURE | Chữ ký HMAC-SHA256 không hợp lệ hoặc sai secret key | Kiểm tra thứ tự sắp xếp tham số và secret key |
400 | MISSING_REQUIRED_FIELD | Thiếu trường dữ liệu bắt buộc | Bổ sung đầy đủ merchant_id, order_invoice_number... |
401 | UNAUTHORIZED | Sai Merchant ID hoặc Secret Key | Xác thực lại cặp khóa trên my.hitechcloud.vn |
403 | IP_NOT_ALLOWED | Địa chỉ IP gọi API không nằm trong Whitelist | Đăng ký IP máy chủ tại mục Bảo mật API |
404 | ORDER_NOT_FOUND | Không tìm thấy đơn hàng với mã hóa đơn yêu cầu | Kiểm tra lại order_invoice_number |
409 | ORDER_ALREADY_PAID | Đơn hàng này đã được thanh toán trước đó | Không được phép khởi tạo thanh toán lại cho đơn đã thanh toán |
410 | ORDER_EXPIRED | Phiên thanh toán đã hết hạn | Khởi tạo phiên thanh toán mới cho khách |
422 | AMOUNT_BELOW_MINIMUM | Số tiền thanh toán nhỏ hơn mức tối thiểu (1,000 VNĐ) | Cập nhật số tiền đơn hàng hợp lệ |
429 | RATE_LIMIT_EXCEEDED | Vượt quá hạn mức 60 req/phút | Giảm tần suất polling, áp dụng Exponential Backoff |
500 | INTERNAL_SERVER_ERROR | Lỗi máy chủ HiTechCloud Pay | Liên hệ bộ phận kỹ thuật để hỗ trợ |
Cấu trúc phản hồi lỗi chuẩn (JSON)
Rate Limiting Headers
| Header | Mô tả |
|---|---|
X-RateLimit-Limit | Số lượng request tối đa được phép trong 1 phút (mặc định 60) |
X-RateLimit-Remaining | Số lượng request còn lại trong cửa sổ thời gian hiện tại |
X-RateLimit-Reset | Thời điểm (Unix timestamp) giới hạn được reset lại |
Authorization: Basic base64(YOUR_MERCHANT_ID:YOUR_SECRET_KEY)
Content-Type: application/json
Accept: application/json{
"status": "error",
"code": "INVALID_SIGNATURE",
"message": "Chữ ký HMAC-SHA256 không khớp với dữ liệu gửi lên.",
"errors": {
"signature": [
"Signature verification failed for merchant HTC_MCH_123456"
]
},
"timestamp": 1759134700
}