Partner API - Order Query Transaction

API do TAMOVE cung cấp, cho phép đối tác gọi vào để truy vấn trạng thái giao dịch. API này được sử dụng trong trường hợp kết quả gạch nợ trả về timeout hoặc không rõ ràng, nhằm xác định chính xác trạng thái cuối cùng của giao dịch để xử lý tiếp theo.

Về module Order Payment Confirm

Endpoint

URL Production POST {HOST}/PartnerAPI/Order/queryTransaction
URL Sandbox POST {HOST_SANDBOX}/PartnerAPI/Order/queryTransaction
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
transactionId string Yes Mã định danh giao dịch cần truy vấn (requestId khi gọi API gạch nợ bị timeout/lỗi)
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/queryTransaction' \
  --header 'Content-Type: application/json' \
  --header 'clientId: YOUR_CLIENT_ID' \
  --header 'apiKey: YOUR_API_KEY' \
  --data '{
    "requestId": "YOUR_REQUEST_ID",
    "transactionId": "YOUR_TRANSACTION_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 transactionId, 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 transactionId, 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ề trạng thái hiện tại của giao dịch cùng các thông tin liên quan 00

Success Response

Khi thành công (code = "00"), trường data chứa thông tin trạng thái giao dịch:

{
  "code": "00",
  "message": "Thanh cong",
  "data": {
    "orderId": "TEST_ORDER_PARTNER_PENDING_001",
    "amount": 91000,
    "transactionStatus": "Success",
    "updatedAt": "2026-04-02T14:00:00.000Z"
  }
}

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

Trường Kiểu Mô tả
orderId string Mã đơn hàng
amount number Tổng tiền thanh toán
transactionStatus string Trạng thái thanh toán (xem bảng trạng thái bên dưới)
updatedAt string Thời điểm cập nhật mới nhất, định dạng ISO 8601

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 giao dịch, trả về thông tin trạng thái giao dịch đầ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 Giao Dịch (transactionStatus)

Giá trị Ý nghĩa Mô tả & Hướng xử lý cho đối tác
New Mới ghi nhận giao dịch Mới ghi nhận giao dịch, đối tác gọi lại truy vấn giao dịch sau X thời gian
Processing Đang xử lý giao dịch Đang xử lý giao dịch gạch nợ, đối tác gọi lại truy vấn giao dịch sau X thời gian
Pending Đang chờ xử lý Đang chờ xử lý, đối tác gọi lại truy vấn giao dịch sau X thời gian
Failed Xử lý thất bại Giao dịch thất bại, đối tác cập nhật trạng thái mới & hoàn tiền (nếu cần)
Success Xử lý thành công Yêu cầu gạch nợ đã được xử lý thành công, đối tác cập nhật trạng thái mới & xác nhận
Canceled Huỷ thanh toán Thanh toán thất bại, đối tác cập nhật trạng thái mới & hoàn tiền (nếu cần)

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