GET - Obtenir une facture

Récupérer le statut actuel et les détails d'une facture par trans_id. Retourne le statut de paiement, le montant, les informations token/réseau (si sélectionnés), et les détails de transaction (si complétée). Retourne uniquement les factures appartenant à la boutique associée à la clé API.

Endpoint

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

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

En-têtes

En-tête	Requis	Description
x-api-key	Oui	Clé API de la boutique

Réponse

Succès (HTTP 200)

Réponse de base (toujours incluse) :

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

Lorsque le client sélectionne un token/réseau sur la page de paiement, data inclut des champs supplémentaires :

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

Lorsque status = "completed", data inclut des champs supplémentaires :

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

Description des champs

Champ	Description
trans_id	Code unique de la facture.
request_id	Votre ID de commande (si fourni lors de la création).
status	waiting | processing | completed | expired.
amount	Montant USD (chaîne).
name	Nom/titre de la facture (si fourni lors de la création).
description	Description de la facture (si fournie lors de la création).
created_at	Heure de création (timestamp Unix, secondes).
expires_at	Heure d'expiration (timestamp Unix, secondes).
token_symbol	Token sélectionné (ex : USDT, BNB). Uniquement après sélection du client.
network_symbol	Réseau (ex : BSC, TRC20, ETH, BINANCE_PAY). Uniquement après sélection du client.
token_amount	Montant de crypto à transférer. Uniquement après sélection du client.
token_price	Taux de change au moment de la sélection. Uniquement après sélection du client.
to_address	Adresse du portefeuille de réception. Uniquement après sélection du client.
transaction_hash	Hash de transaction blockchain. Uniquement quand status = "completed".
from_address	Adresse du portefeuille de l'expéditeur. Uniquement quand status = "completed".
fee_amount	Frais déduits (USD). Uniquement quand status = "completed".
callback_status	Statut de livraison du webhook : success | failed | null. Uniquement quand status = "completed".

Erreurs (4xx / 5xx)

HTTP	error_code	Description
400	MISSING_TRANS_ID	trans_id manquant dans l'URL.
400	INVALID_TRANS_ID_FORMAT	Format de trans_id invalide. Attendu : TID-XXXXXXXXXXXXXXXX (16 caractères alphanumériques majuscules). details contient trans_id et expected_format.
401	MISSING_API_KEY	Aucun en-tête x-api-key fourni.
401	INVALID_API_KEY	La clé API est invalide ou n'existe pas.
403	ACCOUNT_INACTIVE	Le compte associé à cette clé API est désactivé.
403	STORE_INACTIVE	La boutique associée à cette clé API est désactivée.
404	INVOICE_NOT_FOUND	Facture non trouvée ou n'appartient pas à la clé API de cette boutique. details.trans_id contient la valeur envoyée.
429	RATE_LIMIT_EXCEEDED	Limite de débit dépassée.
500	INTERNAL_ERROR	Erreur serveur.

Format du body d'erreur :

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

Limite de débit

• Burst : 20 requêtes/seconde (par clé API ou IP).
• Soutenu : 200 requêtes/minute (par clé API ou IP).

Cas d'utilisation

• Polling : Appelez périodiquement GET https://api.payerscan.com/invoice/:trans_id pour mettre à jour le statut de l'UI (lorsque vous n'utilisez pas le webhook comme source principale).
• Réconciliation : Recherchez des factures par trans_id depuis des e-mails, tickets, etc.
• Page d'affichage du statut : Après le paiement du client, affichez les informations de cette API.