Foire aux questions
Intégration & API
De quoi ai-je besoin pour commencer ?
Vous avez besoin d'une API Key (depuis la page de gestion, sous Store) et d'une URL de callback (un endpoint POST public) pour recevoir les webhooks. Ensuite, appelez POST https://api.payerscan.com/payment/crypto pour créer une facture et redirigez le client vers url_payment. Voir Démarrage rapide.
Quel est le Base URL de l'API ?
Le Base URL officiel de l'API est https://api.payerscan.com. Toutes les requêtes API doivent utiliser HTTPS.
Puis-je créer une facture sans envoyer callback_url ?
Oui. Mais vous ne recevrez pas les webhooks completed/expired. Vous ne pouvez vérifier le statut que via GET https://api.payerscan.com/invoice/:trans_id (polling).
Quelle est la limite de débit ?
- POST /payment/crypto : 5 requêtes/seconde, max 60 requêtes/minute (par API Key, repli sur IP).
- GET /invoice/:trans_id : 20 requêtes/seconde, max 200 requêtes/minute.
Dépassement → HTTP 429, avec retry_after_seconds dans le corps. Voir Limites de débit.
Qu'est-ce que request_id et comment fonctionne l'idempotence ?
request_id est un champ optionnel que vous incluez lors de la création d'une facture — généralement votre ID de commande interne (par ex. : "ORDER-12345") ou une chaîne aléatoire unique connue uniquement de votre backend et de PayerScan.
Pourquoi l'utiliser ? Si votre serveur plante ou timeout en cours de requête, vous pouvez réessayer en toute sécurité avec le même request_id. L'API garantit qu'aucune facture en double ne sera créée — elle retourne la facture existante avec "idempotent": true dans la réponse.
Associer les webhooks aux commandes : Le request_id est également inclus dans les callbacks webhook (completed / expired), permettant à votre backend d'identifier à quelle facture (transaction, commande) le paiement correspond.
Sans request_id : Chaque POST crée une nouvelle facture, même si le body est identique. Vous risquez de créer des factures en double pour la même commande en cas de retentative.
Dans quelle devise est le amount ?
Le champ amount est toujours en USD (dollars américains). Le système le convertit automatiquement en montant de cryptomonnaie correspondant selon le taux de change en temps réel au moment du paiement.
Note : Le taux de change provient de l'une des quatre sources — Binance, Coinbase, CoinGecko ou CoinMarketCap — choisie par le client sur la page de paiement.
Quelles sont les limites de montant ?
Le amount de la facture (en USD) doit être un nombre positif et ne peut pas dépasser 1 000 000. Les valeurs peuvent être envoyées sous forme de chaîne ou de nombre.
Que sont completed_url et expired_url ?
Ce sont des URLs de redirection optionnelles pour le navigateur du client :
completed_url— le client est redirigé ici après un paiement réussi.expired_url— le client est redirigé ici si la facture expire.
Elles servent uniquement à la redirection frontend et ne remplacent pas le webhook callback_url.
Paiements & Confirmation
Que se passe-t-il si le client envoie un mauvais montant ?
Le système ne confirme que lorsque la transaction blockchain correspond exactement au montant (token_amount), à la bonne adresse et dans la fenêtre de temps. Envoyer trop peu ou trop ne sera pas considéré comme un paiement réussi ; la facture peut expirer ou le client doit en créer une nouvelle.
Combien de temps dure la confirmation ?
Généralement quelques secondes à quelques minutes, selon le réseau et la méthode :
- EVM (BSC, ETH, Polygon, ...) : 3-15 secondes
- Tron (TRC20) : 3-5 secondes
- Dépôts via exchange (Binance, OKX, Bybit, ...) : Quasi instantané
- Binance Pay : Quasi instantané
Dès qu'une transaction correspondante est trouvée, le système met à jour la facture et envoie le webhook immédiatement.
Quand une facture expire-t-elle ?
Par défaut selon la configuration du Store (ex. : 15 minutes). Lors de la création, la réponse inclut expires_in_minutes. Après ce délai, la facture passe à expired et (si un callback_url est fourni) vous recevez un webhook avec status: "expired".
Quels sont les statuts possibles d'une facture ?
| Statut | Description |
|---|---|
waiting | Facture créée, en attente de paiement. |
completed | Paiement confirmé sur la blockchain. |
expired | Facture expirée sans paiement reçu. |
Puis-je annuler une facture ?
Non. Les factures ne peuvent pas être annulées via l'API. Elles expirent automatiquement après le temps configuré (expires_in_minutes). Si le client ne paie pas, laissez-la expirer.
Webhook
Quels événements déclenchent un webhook ?
Le système envoie des webhooks pour deux événements :
- completed — lorsqu'un paiement correspondant est confirmé sur la blockchain.
- expired — lorsque la facture expire sans paiement.
Quel est le timeout du webhook ?
10 secondes. Si le serveur du marchand ne retourne pas un HTTP 2xx dans ce délai, la requête est considérée comme échouée et sera retentée.
Dois-je retourner un body spécifique ?
Non. Retournez simplement un statut HTTP 2xx (ex. : 200 OK). Le body est libre (vide ou "OK").
Les webhooks sont-ils retentés en cas d'échec ?
Oui. En cas d'erreur ou de timeout, le système retente selon ce calendrier : 10s → 30s → 30s → 60s → 60s (max 5 tentatives). Assurez-vous que votre endpoint traite de manière idempotente (appeler avec le même trans_id plusieurs fois est sûr).
Erreurs & Dépannage
Que signifie NO_PAYMENT_METHOD ?
Votre Store n'a pas de méthode de paiement configurée. Allez dans la gestion du Store → ajoutez au moins une adresse de portefeuille ou connectez une plateforme d'échange avant de créer des factures.
Que signifie INSUFFICIENT_BALANCE ?
Le solde de votre compte est insuffisant pour couvrir les frais de service de cette facture. Les frais sont calculés sur le amount (USD) de la facture avec le taux applicable à votre compte (des remises peuvent réduire le taux). Rechargez sur le Dashboard et réessayez. Consultez le champ details dans la réponse d'erreur pour le montant exact manquant.
Note : Pendant la période d'essai gratuite (7 premiers jours),
INSUFFICIENT_BALANCEn'apparaîtra pas — tous les frais de service sont exonérés.
Qu'est-ce que INVALID_MERCHANT_ID ?
Le merchant_id dans le body ne correspond pas au Store de l'API Key utilisée. Vérifiez le merchant_id dans la gestion du Store et envoyez le bon dans la requête.
La recherche de facture retourne 404 ?
Causes possibles : (1) trans_id incorrect, (2) la facture appartient à un autre Store (API Key différente), ou (3) n'existe pas. Vérifiez le trans_id et l'API Key.
Méthodes de paiement
Quelles méthodes de paiement le système supporte-t-il ?
PayerScan supporte plusieurs méthodes de paiement :
- Portefeuilles on-chain : EVM (BSC, Ethereum, Polygon, Base, Arbitrum), Tron (TRC20), Solana
- Plateformes d'échange : Binance Pay, Binance Deposit, OKX, Bybit, MEXC, Gate.io, Bitget, Upbit, Bitkub
Voir Réseaux & Tokens pour la liste complète.
Comment fonctionne Binance Pay ?
Binance Pay permet aux clients de payer via Binance — sans frais de gas, confirmation instantanée. Les marchands doivent configurer la Binance API Key et la Secret Key dans la page de gestion.
Que faut-il configurer pour les plateformes d'échange ?
- Créez une API Key sur l'exchange (activez les permissions requises)
- Dans la page de gestion → configurez API Key, Secret Key et ID de plateforme pour le Store
Détails : Configuration Binance Pay.
Sécurité
L'API Key doit-elle être envoyée depuis le frontend ?
Non. L'API Key ne doit être utilisée que sur le serveur (backend du marchand). Appelez POST /payment/crypto et GET /invoice depuis le serveur ; le frontend ne reçoit que url_payment pour la redirection et n'a pas besoin de l'API Key.
L'URL de callback nécessite-t-elle une authentification ?
Recommandé : vérifiez le merchant_id ou le trans_id avec vos données internes pour garantir la légitimité de la requête. Utilisez HTTPS pour éviter l'écoute.
Puis-je avoir plusieurs Stores ?
Oui. Chaque Store possède sa propre API Key, merchant_id, méthodes de paiement et paramètres. Vous pouvez créer plusieurs Stores pour séparer différentes activités ou environnements (ex. : production vs. test).