GET - Get Invoice

Retrieve the current status and details of an invoice by trans_id. Returns payment status, amount, token/network information (if selected), and transaction details (if completed). Only returns invoices belonging to the Store associated with the API Key.

Endpoint

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

Example: GET https://api.payerscan.com/invoice/TID-ABC123DEF4567890

Headers

Header	Required	Description
x-api-key	Yes	Store's API Key

Response

Success (HTTP 200)

Base response (always included):

{
  "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
  }
}

When the customer selects a token/network on the checkout page, data includes additional fields:

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

When status = "completed", data includes additional fields:

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

Field Descriptions

Field	Description
trans_id	Unique invoice code.
request_id	Your order ID (if provided when creating).
status	waiting | processing | completed | expired.
amount	USD amount (string).
name	Invoice name/title (if provided when creating).
description	Invoice description (if provided when creating).
created_at	Creation time (Unix timestamp, seconds).
expires_at	Expiration time (Unix timestamp, seconds).
token_symbol	Selected token (e.g., USDT, BNB). Only after customer selects.
network_symbol	Network (e.g., BSC, TRC20, ETH, BINANCE_PAY). Only after customer selects.
token_amount	Amount of crypto to transfer. Only after customer selects.
token_price	Exchange rate at time of selection. Only after customer selects.
to_address	Receiving wallet address. Only after customer selects.
transaction_hash	Blockchain transaction hash. Only when status = "completed".
from_address	Sender's wallet address. Only when status = "completed".
fee_amount	Fee deducted (USD). Only when status = "completed".
callback_status	Webhook delivery status: success | failed | null. Only when status = "completed".

Errors (4xx / 5xx)

HTTP	error_code	Description
400	MISSING_TRANS_ID	Missing trans_id in URL path.
400	INVALID_TRANS_ID_FORMAT	Invalid trans_id format. Expected: TID-XXXXXXXXXXXXXXXX (16 uppercase alphanumeric characters). details has trans_id and expected_format.
401	MISSING_API_KEY	No x-api-key header provided.
401	INVALID_API_KEY	The API key is invalid or does not exist.
403	ACCOUNT_INACTIVE	The account associated with this API key is disabled.
403	STORE_INACTIVE	The store associated with this API key is disabled.
404	INVOICE_NOT_FOUND	Invoice not found or doesn't belong to this Store's API Key. details.trans_id contains the sent value.
429	RATE_LIMIT_EXCEEDED	Exceeded rate limit.
500	INTERNAL_ERROR	Server error.

Error body format:

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

Rate Limit

• Burst: 20 requests/second (per API Key or IP).
• Sustained: 200 requests/minute (per API Key or IP).

Use Cases

• Polling: Periodically call GET https://api.payerscan.com/invoice/:trans_id to update the UI status (when not using webhook as the primary source).
• Reconciliation: Look up invoices by trans_id from emails, tickets, etc.
• Status display page: After customer payment, display information from this API.