GET - Lấy thông tin hóa đơn

Truy xuất trạng thái và chi tiết hóa đơn theo trans_id. Trả về trạng thái thanh toán, số tiền, thông tin token/network (nếu đã chọn), và chi tiết giao dịch (nếu đã hoàn thành). Chỉ trả về hóa đơn thuộc Store liên kết với API Key.

Endpoint

GET https://api.payerscan.com/invoice/:trans_id

Ví dụ: GET https://api.payerscan.com/invoice/TID-ABC123DEF4567890

Headers

Header	Bắt buộc	Mô tả
x-api-key	Có	API Key của Store

Response

Thành công (HTTP 200)

Response cơ bản (luôn bao gồm):

{
  "status": "success",
  "data": {
    "trans_id": "TID-ABC123DEF4567890",
    "request_id": "ORDER_123456",
    "status": "waiting",
    "amount": "100",
    "name": "Top-up balance",
    "description": "Top-up the balance for username: JohnDoe",
    "created_at": 1738742400,
    "expires_at": 1738746000
  }
}

Khi khách chọn token/network trên trang thanh toán, data có thêm:

{
  "token_symbol": "USDT",
  "network_symbol": "BSC",
  "token_amount": "100.0026",
  "token_price": "1",
  "to_address": "0xc221460115e2CfCa5bF089A7e647b11cb9631efE"
}

Khi status = "completed", data có thêm:

{
  "transaction_hash": "0xd346b32b83b35376d42a2464598fbf565fffb39e...",
  "from_address": "0x8894e0a0c962cb723c1976a4421c95949be2d4e3",
  "fee_amount": "0.2",
  "callback_status": "success"
}

Mô tả các trường

Trường	Mô tả
trans_id	Mã hóa đơn duy nhất.
request_id	ID đơn hàng của bạn (nếu có khi tạo).
status	waiting | processing | completed | expired.
amount	Số tiền USD (string).
name	Tên/title hóa đơn (nếu có khi tạo).
description	Mô tả hóa đơn (nếu có khi tạo).
created_at	Thời gian tạo (Unix timestamp, giây).
expires_at	Thời gian hết hạn (Unix timestamp, giây).
token_symbol	Token đã chọn (ví dụ: USDT, BNB). Chỉ sau khi khách chọn.
network_symbol	Mạng lưới (ví dụ: BSC, TRC20, ETH, BINANCE_PAY). Chỉ sau khi khách chọn.
token_amount	Số lượng crypto cần chuyển. Chỉ sau khi khách chọn.
token_price	Tỷ giá tại thời điểm chọn. Chỉ sau khi khách chọn.
to_address	Địa chỉ ví nhận. Chỉ sau khi khách chọn.
transaction_hash	Hash giao dịch blockchain. Chỉ khi status = "completed".
from_address	Địa chỉ ví người gửi. Chỉ khi status = "completed".
fee_amount	Phí đã trừ (USD). Chỉ khi status = "completed".
callback_status	Trạng thái gửi webhook: success | failed | null. Chỉ khi status = "completed".

Lỗi (4xx / 5xx)

HTTP	error_code	Mô tả
400	MISSING_TRANS_ID	Thiếu trans_id trong URL.
400	INVALID_TRANS_ID_FORMAT	trans_id không đúng định dạng. Yêu cầu: TID-XXXXXXXXXXXXXXXX (16 ký tự chữ-số viết hoa). details có trans_id và expected_format.
401	MISSING_API_KEY	Không có header x-api-key.
401	INVALID_API_KEY	API key không hợp lệ hoặc không tồn tại.
403	ACCOUNT_INACTIVE	Tài khoản liên kết với API key này đã bị vô hiệu hóa.
403	STORE_INACTIVE	Store liên kết với API key này đã bị vô hiệu hóa.
404	INVOICE_NOT_FOUND	Không tìm thấy hóa đơn hoặc không thuộc Store của API Key. details.trans_id chứa giá trị đã gửi.
429	RATE_LIMIT_EXCEEDED	Vượt giới hạn request.
500	INTERNAL_ERROR	Lỗi server.

Định dạng body lỗi:

{
  "status": "error",
  "message": "Invoice not found.",
  "error_code": "INVOICE_NOT_FOUND",
  "details": { "trans_id": "TID-ABC123DEF4567890" }
}

Rate Limit

• Burst: 20 request/giây (theo API Key hoặc IP).
• Sustained: 200 request/phút (theo API Key hoặc IP).

Trường hợp sử dụng

• Polling: Gọi định kỳ GET https://api.payerscan.com/invoice/:trans_id để cập nhật trạng thái UI (khi không dùng webhook làm nguồn chính).
• Đối soát: Tra cứu hóa đơn theo trans_id từ email, ticket, v.v.
• Trang hiển thị trạng thái: Sau khi khách thanh toán, hiển thị thông tin từ API này.