Tài liệu nhà phát triển

Tra cứu thanh toán và trạng thái đơn

Tra cứu theo mã đơn người bán. Phân biệt xác nhận, gửi thông báo và giao hàng.

POST /api/v1/order/status

Yêu cầu xác thực

Bao gồm X-Bolt-Key, X-Bolt-Timestamp và X-Bolt-Signature. Sử dụng timestamp mili giây hiện tại và ký timestamp cùng với nội dung yêu cầu chính xác.

01. Tham số yêu cầu

application/json
externalOrderIdBắt buộc
String

Gửi cho người bán externalOrderId được sử dụng khi tạo đơn hàng, không phải orderToken. Chỉ có thể truy vấn các đơn hàng thuộc khóa API hiện tại.

Giá trị mẫu

{"externalOrderId": "INV-20260209-99281"}

Chuỗi bắt buộc, 6–64 ký tự. Cho phép sử dụng chữ cái, chữ số, dấu gạch dưới (_) và dấu gạch ngang (-).

Body

Trạng thái đơn hàng và quá trình thực hiện

PENDING

Đang chờ thanh toán: chưa có giao dịch chuyển khoản đủ điều kiện nào được khớp.

PAID

Đã phát hiện khoản thanh toán, đang chờ xác nhận chuỗi khối.

CONFIRMED

Thanh toán được xác nhận hoặc chấp nhận thông qua đánh giá của người bán; việc gửi lại có thể vẫn đang chờ xử lý.

COMPLETED

Khoản thanh toán đã được xác nhận và BoltUtil đã nhận được phản hồi gọi lại thành công.

EXPIRED

Thời hạn thanh toán đã kết thúc mà không có giao dịch chuyển khoản đủ điều kiện phù hợp. Việc chuyển tiền đúng hạn nhưng xác nhận chậm trễ vẫn có thể được ghi nhận sau đó.

FAILED

Đơn hàng đang ở trạng thái không thành công. Đừng coi đó là thanh toán thành công.

CANCELLED

Đơn đặt hàng đã bị hủy. Đừng coi đó là thanh toán thành công.

PAID nghĩa là đang chờ xác nhận; không giao hàng chỉ dựa vào trạng thái này. CONFIRMED hoặc COMPLETED nghĩa là thanh toán đã được xác nhận; chỉ giao một lần cho mỗi externalOrderId. COMPLETED nghĩa là BoltUtil nhận được phản hồi thành công cho thông báo, không chứng minh doanh nghiệp đã giao hàng. Với khoản thanh toán được kiểm tra thủ công, hãy kiểm tra thêm số tiền thực trả và loại quyết toán.

02. Các trường phản hồi (data)

application/json
statusString
Trạng thái đơn hàng hiện tại. Xem mô tả trạng thái ở trên; một đơn hàng không cần phải đi qua mọi tiểu bang.
amountString
Số tiền đặt hàng phải trả, được trả về dưới dạng chuỗi. Sử dụng paidAmount cho số tiền đã thanh toán được ghi lại.
paidAmountString / null
Số tiền đã thanh toán được ghi lại dưới dạng chuỗi; có thể là null trước khi thanh toán. Đối với các đơn hàng đã thanh toán cũ hơn mà không có số tiền thanh toán riêng, số tiền sẽ quay trở lại số tiền phải trả.
shortfallAmountString / null
Sự thiếu hụt được ghi lại dưới dạng chuỗi; có thể là null trước khi thanh toán. Các khoản thanh toán vượt mức được chấp nhận theo cách thủ công có thể trả về 0 tại đây. Để tính chênh lệch có dấu, hãy trừ paidAmount khỏi amount.
settlementTypeString / null
EXACT: khớp chính xác; MANUAL_UNDERPAID: chấp nhận thanh toán thiếu; MANUAL_OVERPAID: chấp nhận thanh toán vượt mức; MANUAL_AMBIGUOUS: một liên kết khác được xem xét thủ công. Có thể là null trước khi thanh toán.
paymentRouteString / null
Kênh thực tế: DIRECT là chuyển trực tiếp, SPLIT là chia khoản thanh toán. Truy vấn có thể trả null trước quyết toán; không phải xác nhận thanh toán.
platformFeeString / null
Phí nền tảng thực tế theo currency, dạng chuỗi; có thể null khi chưa ghi nhận. Thanh toán trực tiếp hoặc miễn phí là 0; không gồm phí mạng.
merchantNetAmountString / null
Thực nhận ròng của người bán theo currency, dạng chuỗi. Khi chia tiền: tổng đã trả trừ phí nền tảng. Có thể null trước khi ghi nhận; callback cũ có thể dùng số đã trả.
manuallyAcceptedBoolean
Hiện tại true chỉ dành cho MANUAL_UNDERPAID. Nó không xác định mọi hành động thủ công; sử dụng settlementType cho loại cụ thể.
externalOrderIdString
Đơn đặt hàng ID được cung cấp khi tạo, được sử dụng để truy vấn và liên kết đơn đặt hàng kinh doanh của bạn.
txHashString / null
Băm giao dịch của khoản thanh toán liên quan; có thể là null trước khi liên kết. Chỉ riêng hàm băm không chứng minh được xác nhận thanh toán.
destinationAddressString
Người bán nhận ví được đơn đặt hàng này sử dụng; nhiều đơn hàng có thể chia sẻ nó.
confirmationsInteger / null
Số lượng xác nhận blockchain được ghi lại; có thể là null. Quy tắc xác nhận khác nhau tùy theo mạng. Sử dụng status để xác định xác nhận thanh toán.
currencyString
Mã đơn vị tiền tệ thanh toán, chẳng hạn như USDT hoặc USDC.
networkString
Mã mạng thanh toán: TRC20, ERC20, BEP20, POLYGON, SOLANA hoặc BASE.
paidAtString / null
Thời gian thanh toán được ghi lại dưới dạng chuỗi ngày giờ; null trước khi khoản thanh toán được ghi lại.
confirmedAtString / null
Thời gian xác nhận thanh toán được ghi lại dưới dạng chuỗi ngày giờ; null trước khi xác nhận.
completedAtString / null
Thời gian đơn hàng được nhập lần đầu tiên COMPLETED, dưới dạng chuỗi ngày giờ; null trước khi hoàn thành. Việc phân phối lặp lại thành công không ghi đè lên nó. Các đơn hàng đã hoàn thành trước đó sẽ giữ lại thời gian đã ghi trong lịch sử của chúng.
metadataObject
Đối tượng JSON tùy chỉnh được cung cấp khi tạo đơn hàng. Nó không được sử dụng để khớp thanh toán.

Ghi chú truy vấn

  • Truy vấn trả về trạng thái đơn hàng được lưu trữ; nó không quét blockchain ngay lập tức. Xác nhận là giá trị được ghi lại. Sử dụng status để xác định xác nhận thanh toán.
  • Nếu không có khoản thanh toán phù hợp, paidAmount, shortfallAmount, settlementType, txHash và các thời điểm liên quan có thể là null. Đây không phải là lỗi truy vấn.
  • Chỉ có thể truy vấn các đơn đặt hàng của riêng bạn. Tài khoản miễn phí có thể truy cập các đơn hàng được tạo trong vòng 30 ngày qua; thành viên tích cực có thể truy cập tất cả lịch sử. Đơn hàng bị thiếu hoặc không thể truy cập được trả lại đơn hàng không tìm thấy.
  • paidAt, confirmedAt và completedAt là các chuỗi ngày giờ, chẳng hạn như 2026-02-09T18:20:50.790, không có chênh lệch múi giờ. Chúng không phải là dấu thời gian tính bằng mili giây.

Các lỗi thường gặp

Đây là những trường hợp phổ biến. Sử dụng trạng thái HTTP thực tế và mã/thông báo phản hồi để chẩn đoán lỗi. Phản hồi lỗi không phải là kết quả thanh toán.

  • 401: Kiểm tra Khóa API, chữ ký nội dung thô và timestamp mili giây hiện tại (trong vòng 5 phút tính từ đồng hồ máy chủ).
  • 404: Đơn hàng bị thiếu, thuộc về người bán khác hoặc nằm ngoài lịch sử mà gói của bạn cho phép.
status / cURL
# Run against your account only when ready; this sends an API request.
: "${BOLTUTIL_API_KEY:?Set your complete API Key}"
: "${BOLTUTIL_WEBHOOK_SECRET:?Set your Webhook secret}"
timestamp=$(python3 -c 'import time; print(int(time.time()*1000))')
body='{"externalOrderId":"INV-20260209-99281"}'
signature=$(printf '%s.%s' "$timestamp" "$body" | openssl dgst -sha256 -hmac "$BOLTUTIL_WEBHOOK_SECRET" | awk '{print $NF}')

curl --request POST "https://api.boltutil.com/api/v1/order/status" \
  --header 'Content-Type: application/json' \
  --header "X-Bolt-Key: $BOLTUTIL_API_KEY" \
  --header "X-Bolt-Timestamp: $timestamp" \
  --header "X-Bolt-Signature: $signature" \
  --data-binary "$body"

Địa chỉ, băm giao dịch và đơn đặt hàng là ví dụ. Thay thế chúng bằng bài kiểm tra data của riêng bạn.

Base URL

PROD
https://api.boltutil.com