Định dạng Response (Envelope)

Khung phản hồi chuẩn của HiTechCloud Pay API: mọi endpoint đều trả JSON gồm status, data và meta để bạn xử lý kết quả và phân trang nhất quán.

Xem Markdown

Mọi phản hồi từ HiTechCloud Pay API đều được gói trong một cấu trúc nhất quán gọi là Envelope. Nhờ đó mã client của bạn chỉ cần viết một lớp xử lý chung cho tất cả endpoint, bất kể là tài khoản ngân hàng, giao dịch hay tài khoản ảo.

Các trường trong Envelope

TrườngKiểuMô tả
statusstringsuccess khi thành công, error khi có lỗi
dataobject | arrayDữ liệu chính: mảng khi truy vấn danh sách, object khi lấy chi tiết
metaobjectSiêu dữ liệu, chứa pagination khi phản hồi là danh sách
codestringChỉ xuất hiện khi lỗi: mã lỗi dạng chuỗi (ví dụ UNAUTHORIZED)
messagestringChỉ xuất hiện khi lỗi: mô tả lỗi bằng tiếng Việt dễ hiểu

Phản hồi danh sách (list)

Envelope khi trả về danh sách
{
  "status": "success",
  "data": [
    { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "amount_in": 1500000 }
  ],
  "meta": {
    "pagination": {
      "total": 125,
      "per_page": 20,
      "current_page": 1,
      "last_page": 7,
      "has_more": true
    }
  }
}

Phản hồi chi tiết (single)

Envelope khi trả về một bản ghi
{
  "status": "success",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount_in": 1500000,
    "transaction_content": "DH100234 chuyen tien mua VPS"
  }
}

Phản hồi lỗi (error)

Envelope khi có lỗi
{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "Tham số from_date không đúng định dạng ngày."
}
Luôn kiểm tra trường status trước khi đọc data. Khi status là error, trường data sẽ không xuất hiện; thay vào đó hãy đọc code và message.