Partner API - Order Query Order

API do TAMOVE cung cấp cho phép đối tác gọi để kiểm tra thông tin và trạng thái đơn hàng trước hoặc trong quá trình xử lý thanh toán.

Về module Order Payment Confirm

Endpoint

URL Production POST {HOST}/PartnerAPI/Order/queryOrder
URL Sandbox POST {HOST_SANDBOX}/PartnerAPI/Order/queryOrder
HTTP Method POST
Content-Type application/json
Encoding UTF-8
Timeout Phản hồi trong vòng 30 giây

Headers schema

Header Required Mô tả
clientId Yes Định danh đối tác do TAMOVE cấp
apiKey Yes Khóa xác thực API do TAMOVE cấp. Giữ bí mật tuyệt đối

Lưu ý: TAMOVE sẽ từ chối toàn bộ request thiếu hoặc sai thông tin xác thực với HTTP 401 (code "01").

Body schema (JSON)

Field Type Required Mô tả
requestId string Yes Mã giao dịch phía đối tác – dùng để đối soát và ghi nhận nguồn thanh toán
orderId string Yes Mã đơn hàng trong hệ thống TAMOVE cần truy vấn
amount number Yes Số tiền cần xác nhận khớp với đơn hàng (đơn vị: VNĐ, kiểu số nguyên dương). Ví dụ: 150000

Sample Request 

curl --location '{HOST_NAME}/PartnerAPI/Order/queryOrder' \
  --header 'Content-Type: application/json' \
  --header 'clientId: YOUR_CLIENT_ID' \
  --header 'apiKey: YOUR_API_KEY' \
  --data '{
    "requestId": "YOUR_REQUEST_ID",
    "orderId": "TEST_ORDER_PARTNER_PENDING_001",
    "amount": 91000
  }'

Logic Xử Lý Phía TAMOVE

TAMOVE thực hiện kiểm tra tuần tự theo thứ tự sau. Bước nào thất bại sẽ dừng và trả lỗi ngay lập tức:

Bước Kiểm tra Mô tả Lỗi nếu thất bại
1 Xác thực clientId & apiKey Kiểm tra header clientId và apiKey hợp lệ và được cấp quyền truy vấn 01
2 Kiểm tra input orderId không rỗng; amount là số nguyên dương 02
3 Kiểm tra đơn tồn tại Tra cứu orderId trong hệ thống TAMOVE 03
4 Kiểm tra số tiền amount trong request phải khớp chính xác với số tiền đơn hàng 05
5 Trả kết quả Trả về thông tin chi tiết đơn hàng bao gồm trạng thái, thông tin khách hàng 00

Success Response

Khi thành công (code = "00"), trường data chứa thông tin chi tiết đơn hàng:

{
  "code": "00",
  "message": "Thanh cong",
  "data": {
    "orderId": "TEST_ORDER_PARTNER_PENDING_001",
    "totalAmount": 91000,
    "discountAmount": 0,
    "taxAmount": 0,
    "paymentStatus": "NEW",
    "createdAt": "2026-04-02T14:00:00+07:00",
    "phoneNumber": "0901234567",
    "firstName": "Nguyen Van A",
    "orderItems": [
      {
        "orderItemName": "Goi cuoc dich vu",
        "quantity": 1,
        "payAmount": 91000
      }
    ]
  }
}

Chi tiết cấu trúc data response:

Trường Kiểu Mô tả
orderId string Mã đơn hàng
totalAmount number Tổng tiền đơn hàng (VNĐ, sau giảm giá và thuế)
discountAmount number Số tiền được giảm giá (VNĐ). 0 nếu không có
taxAmount number Số tiền thuế (VNĐ). 0 nếu không có
paymentStatus string Trạng thái thanh toán (xem bảng trạng thái bên dưới)
createdAt string Thời điểm tạo đơn, định dạng ISO 8601. Ví dụ: "2026-04-02T14:30:00+07:00"
phoneNumber string Số điện thoại người mua
firstName string | null Họ và tên người mua (nếu có, có thể null)
orderItems array Danh sách sản phẩm/dịch vụ trong đơn hàng (Xem chi tiết orderItem bên dưới)

Chi tiết Object orderItem:

Trường Kiểu Mô tả
orderItemName string Tên sản phẩm / dịch vụ
quantity number Số lượng
payAmount number Thành tiền của item, sau giảm giá và VAT (VNĐ). Ví dụ: quantity=2, payAmount=100000 nghĩa là 2 x 50,000

Mã lỗi & Ví dụ Response

Cấu trúc Response Body chung:

Trường Kiểu Mô tả
code String Mã kết quả xử lý (xem bảng mã bên dưới)
message String Mô tả kết quả
data Object | null Dữ liệu bổ sung hoặc thông tin lỗi (tuỳ từng trường hợp, có thể null)

Bảng Mã Kết Quả:

Code HTTP Ý nghĩa Mô tả & Hướng xử lý cho đối tác
00 200 OK Thành công Tìm thấy đơn hàng, trả về thông tin đầy đủ trong data.
01 400 Unauthorized / 401 Xác thực thất bại clientId hoặc apiKey không hợp lệ hoặc không được cấp quyền.
02 400 Bad Request Thiếu hoặc sai tham số Một hoặc nhiều trường bắt buộc bị thiếu, sai kiểu hoặc không hợp lệ.
03 400 Not Found Không tìm thấy đơn hàng orderId không tồn tại trong hệ thống TAMOVE.
05 500 Unprocessable Entity Số tiền không khớp amount trong request khác số tiền thực tế của đơn. data trả về amount đúng.
99 500 Internal Error Lỗi hệ thống Lỗi nội bộ TAMOVE – liên hệ hỗ trợ nếu lặp lại.

Ví dụ Response lỗi:

1. Sai clientId hoặc apiKey (HTTP 400/401 Unauthorized):

{ "code": "01", "message": "Xac thuc that bai", "data": null }

2. Thiếu hoặc sai tham số đầu vào (HTTP 400 Bad Request):

{ "code": "02", "message": "Thieu tham so bat buoc: orderId", "data": null }

3. Không tìm thấy đơn hàng (HTTP 400 Not Found):

{ "code": "03", "message": "Khong tim thay don hang", "data": null }

4. Số tiền không khớp (HTTP 500 Unprocessable Entity):

{ "code": "05", "message": "So tien khong khop", "data": { "amount": 150000 } }

Bảng Trạng Thái Đơn Hàng (paymentStatus)

Giá trị Ý nghĩa Mô tả & Hướng xử lý cho đối tác
New Chờ thanh toán Đơn hàng hợp lệ, có thể tiến hành thanh toán
Processing Đang thanh toán Đang xử lý thanh toán, có thể tiến hành thanh toán
Pending Chờ thanh toán Chờ thanh toán, có thể tiến hành thanh toán
Failed Thanh toán thất bại Thanh toán thất bại, có thể tiến hành thanh toán lại
Success Thanh toán thành công Thanh toán thành công, không thanh toán lại
Canceled Huỷ thanh toán Huỷ thanh toán, không thanh toán lại

Quy Tắc Quan Trọng

Bảo Mật

Tham khảo

Thông Tin Liên Hệ

Thông tin Giá trị
Endpoint Sandbox https://tamove-develop-server.service.makefamousapp.com
Endpoint Production (Liên hệ sau)
API Gạch Nợ liên quan POST /PartnerAPI/Order/paymentConfirm
Email kỹ thuật tech@tamove.vn
Hotline hỗ trợ 1800 xxxx (8:00 – 17:30, Thứ 2 – Thứ 6)
Đầu mối liên hệ Team TAMOVE
Sao chép thành công