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.

Xem Markdown

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ườngBase URL
Productionhttps://pgapi.hitechcloud.vn
Sandboxhttps://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.

Header xác thực
Authorization: Basic base64(YOUR_MERCHANT_ID:YOUR_SECRET_KEY)
Content-Type: application/json
Accept: application/json

Bảng mã lỗi chi tiết (API Error Codes)

Mã HTTPError CodeÝ nghĩa & Nguyên nhânCách xử lý
400INVALID_SIGNATUREChữ ký HMAC-SHA256 không hợp lệ hoặc sai secret keyKiểm tra thứ tự sắp xếp tham số và secret key
400MISSING_REQUIRED_FIELDThiếu trường dữ liệu bắt buộcBổ sung đầy đủ merchant_id, order_invoice_number...
401UNAUTHORIZEDSai Merchant ID hoặc Secret KeyXác thực lại cặp khóa trên my.hitechcloud.vn
403IP_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
404ORDER_NOT_FOUNDKhông tìm thấy đơn hàng với mã hóa đơn yêu cầuKiểm tra lại order_invoice_number
409ORDER_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
410ORDER_EXPIREDPhiên thanh toán đã hết hạnKhởi tạo phiên thanh toán mới cho khách
422AMOUNT_BELOW_MINIMUMSố 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ệ
429RATE_LIMIT_EXCEEDEDVượt quá hạn mức 60 req/phútGiảm tần suất polling, áp dụng Exponential Backoff
500INTERNAL_SERVER_ERRORLỗi máy chủ HiTechCloud PayLiên hệ bộ phận kỹ thuật để hỗ trợ

Cấu trúc phản hồi lỗi chuẩn (JSON)

Phản hồi khi có lỗi (400 Bad Request)
{
  "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

HeaderMô tả
X-RateLimit-LimitSố lượng request tối đa được phép trong 1 phút (mặc định 60)
X-RateLimit-RemainingSố lượng request còn lại trong cửa sổ thời gian hiện tại
X-RateLimit-ResetThời điểm (Unix timestamp) giới hạn được reset lại