Partner API - Order Query Transaction Batch

Truy vấn trạng thái giao dịch của nhiều đơn hàng trong một request (tối đa 100 đơn).

Endpoint

URL	/PartnerAPI/Order/queryTransactionBatch
Method	POST

Headers schema

Header	Required	Mô tả
clientId hoặc clientid	Yes	Mã định danh đối tác
apiKey hoặc apikey	Yes	Khóa xác thực API của đối tác

Body schema

Field	Type	Required	Rule	Mô tả
items	array	Yes	min 1, max 100	Danh sách giao dịch cần truy vấn
items[].requestId	string	No	—	Mã định danh request từ phía đối tác (tuỳ chọn)
items[].transactionId	string	No	—	Mã giao dịch từ phía đối tác (tuỳ chọn)
items[].orderId	string	Yes	—	Mã đơn hàng cần truy vấn
items[].amount	integer	Yes	>= 1	Tổng tiền đơn hàng (dùng để xác thực khớp với hệ thống)

Sample Request

curl --location '{HOST_NAME}/PartnerAPI/Order/queryTransactionBatch' \
  --header 'Content-Type: application/json' \
  --header 'clientId: TESTCLIENT' \
  --header 'apiKey: 07e73e61-0dce-4b39-8ecf-06ef70b35c08' \
  --data '{
    "items": [
      {
        "requestId": "TEST_REQ_QUERY_TRANSACTION_001",
        "transactionId": "TEST_TXN_QUERY_OK_001",
        "orderId": "TEST_ORDER_PARTNER_PENDING_001",
        "amount": 91000
      }
    ]
  }'

Success response

{
  "statusCode": 200,
  "error": null,
  "message": "Success",
  "data": [
    {
      "index": 0,
      "orderId": "TEST_ORDER_PARTNER_PENDING_001",
      "amount": 91000,
      "transactionStatus": "New",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Mã lỗi

HTTP	Mã lỗi	errorCode	Mô tả
400	Validation Error	—	Payload không đúng schema (thiếu field bắt buộc, sai kiểu, vượt giới hạn).
429	`QUOTA_EXCEEDED`	—	apiKey không hợp lệ hoặc vượt quota.
500	`ORDER_NOT_FOUND`	`03`	Không tìm thấy đơn hàng theo `orderId` đã cung cấp.
500	`AMOUNT_MISMATCH`	`05`	Số tiền trong request không khớp với tổng tiền của đơn hàng.
500	`INVALID_BATCH_PAYLOAD`	`02`	Cấu trúc batch không hợp lệ.
500	`UNKNOWN_ERROR`	`99`	Lỗi không xác định.

Cấu trúc response lỗi (ví dụ ORDER_NOT_FOUND):

{
  "statusCode": 500,
  "error": "ORDER_NOT_FOUND",
  "message": "An internal server error occurred",
  "errorCode": "03"
}

Xem đầy đủ bảng errorCode tại Quy chuẩn chung → Partner Order Error Code.

Tham khảo

Quy chuẩn chung → Common Error — danh sách mã lỗi hệ thống trả về trong trường error.
Quy chuẩn chung → Partner Order Error Code — bảng mã số errorCode đi kèm response lỗi.
Quy chuẩn chung → Order Payment Status — danh sách giá trị hợp lệ của trường transactionStatus.

Data test cho developer

clientId: TESTCLIENT
apiKey: 07e73e61-0dce-4b39-8ecf-06ef70b35c08
requestId: TEST_REQ_QUERY_TRANSACTION_001
transactionId (happy): TEST_TXN_QUERY_OK_001
transactionId (missing): TEST_TXN_QUERY_MISSING_001
orderId (happy): TEST_ORDER_PARTNER_PENDING_001
orderId (not found): TEST_ORDER_PARTNER_NOT_FOUND_001
amount (happy): 91000
amount (mismatch): 12345

Cần thay bằng dữ liệu môi trường thật khi tích hợp.