GET - Obter Fatura

Recupere o status atual e os detalhes de uma fatura pelo trans_id. Retorna status do pagamento, valor, informações de token/rede (se selecionados) e detalhes da transação (se concluída). Retorna apenas faturas pertencentes à loja associada à API Key.

Endpoint

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

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

Headers

Header	Obrigatório	Descrição
x-api-key	Sim	API Key da loja

Response

Sucesso (HTTP 200)

Resposta base (sempre incluída):

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

Quando o cliente seleciona um token/rede na página de checkout, data inclui campos adicionais:

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

Quando status = "completed", data inclui campos adicionais:

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

Descrição dos Campos

Campo	Descrição
trans_id	Código único da fatura.
request_id	Seu ID de pedido (se fornecido ao criar).
status	waiting | processing | completed | expired.
amount	Valor em USD (string).
name	Nome/título da fatura (se fornecido ao criar).
description	Descrição da fatura (se fornecida ao criar).
created_at	Hora de criação (timestamp Unix, segundos).
expires_at	Hora de expiração (timestamp Unix, segundos).
token_symbol	Token selecionado (ex: USDT, BNB). Apenas após seleção do cliente.
network_symbol	Rede (ex: BSC, TRC20, ETH, BINANCE_PAY). Apenas após seleção do cliente.
token_amount	Quantidade de crypto a transferir. Apenas após seleção do cliente.
token_price	Taxa de câmbio no momento da seleção. Apenas após seleção do cliente.
to_address	Endereço da carteira de recebimento. Apenas após seleção do cliente.
transaction_hash	Hash da transação blockchain. Apenas quando status = "completed".
from_address	Endereço da carteira do remetente. Apenas quando status = "completed".
fee_amount	Taxa deduzida (USD). Apenas quando status = "completed".
callback_status	Status de entrega do webhook: success | failed | null. Apenas quando status = "completed".

Erros (4xx / 5xx)

HTTP	error_code	Descrição
400	MISSING_TRANS_ID	trans_id ausente na URL.
400	INVALID_TRANS_ID_FORMAT	Formato de trans_id inválido. Esperado: TID-XXXXXXXXXXXXXXXX (16 caracteres alfanuméricos maiúsculos). details tem trans_id e expected_format.
401	MISSING_API_KEY	Nenhum header x-api-key fornecido.
401	INVALID_API_KEY	A API key é inválida ou não existe.
403	ACCOUNT_INACTIVE	A conta associada a esta API key está desativada.
403	STORE_INACTIVE	A loja associada a esta API key está desativada.
404	INVOICE_NOT_FOUND	Fatura não encontrada ou não pertence à API Key desta loja. details.trans_id contém o valor enviado.
429	RATE_LIMIT_EXCEEDED	Limite de requisições excedido.
500	INTERNAL_ERROR	Erro do servidor.

Formato do body de erro:

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

Rate Limit

• Burst: 20 requisições/segundo (por API Key ou IP).
• Sustained: 200 requisições/minuto (por API Key ou IP).

Casos de Uso

• Polling: Chame periodicamente GET https://api.payerscan.com/invoice/:trans_id para atualizar o status da UI (quando não estiver usando webhook como fonte principal).
• Reconciliação: Consulte faturas por trans_id de e-mails, tickets, etc.
• Página de exibição de status: Após o pagamento do cliente, exiba informações desta API.