POST - Créer une facture

Créer une facture de paiement crypto. Le marchand envoie le montant (USD), les informations de commande et l'URL de callback ; le système retourne trans_id et url_payment pour rediriger le client vers la page de paiement.

Endpoint

POST https://api.payerscan.com/payment/crypto

En-têtes

En-tête	Requis	Description
Content-Type	Oui	application/json
x-api-key	Oui	Clé API de la boutique

Corps de la requête (JSON)

Champ	Type	Requis	Contraintes	Description
merchant_id	string	Oui	Non vide	Code marchand de la boutique (doit correspondre à la clé API).
amount	number | string	Oui	> 0 et ≤ 1 000 000	Montant du paiement (USD). Exemple : 100, "100".
callback_url	string	Recommandé	Max 500 caractères, URL valide	URL pour recevoir le webhook à l'état completed ou expired.
completed_url	string	Non	Max 500 caractères, URL valide	URL de redirection après paiement réussi.
expired_url	string	Non	Max 500 caractères, URL valide	URL de redirection quand la facture expire.
name	string	Non	Max 255 caractères	Nom/titre de la facture.
description	string	Non	Max 1000 caractères	Description de la facture.
request_id	string	Non	Max 255 caractères	ID de commande du marchand pour référence croisée (retourné dans la réponse et le webhook). Aussi utilisé pour l'idempotence — voir notes ci-dessous.

Exemple de requête

{
  "merchant_id": "MID-XXXXXXXXXX",
  "amount": 100,
  "name": "Top-up balance",
  "description": "Top-up the balance for username: [USERNAME]",
  "callback_url": "https://your-server.com/webhook/payment",
  "completed_url": "https://your-website.com/thank-you",
  "expired_url": "https://your-website.com/",
  "request_id": "ORDER_123456"
}

Réponse

Succès (HTTP 200)

{
  "status": "success",
  "data": {
    "request_id": "ORDER_123456",
    "trans_id": "TID-ABC123DEF4567890",
    "status": "waiting",
    "amount": "100",
    "url_payment": "https://app.payerscan.com/bill/TID-ABC123DEF4567890",
    "expires_in_minutes": 15
  }
}

Champ	Description
request_id	La valeur que vous avez envoyée dans la requête.
trans_id	Code unique de la facture, utilisé pour la consultation et la référence croisée webhook.
status	Toujours "waiting" à la création.
amount	Montant USD (chaîne).
url_payment	URL de la page de paiement — redirigez le client ici.
expires_in_minutes	Délai d'expiration de la facture (minutes).

Erreurs (4xx / 5xx)

Toutes les erreurs suivent ce format :

{
  "status": "error",
  "message": "Description de l'erreur",
  "error_code": "ERROR_CODE",
  "request_id": "ORDER_123456",
  "details": { }
}

HTTP	error_code	Description
400	VALIDATION_ERROR	Corps invalide (champs requis manquants, mauvais type, contraintes dépassées). details.errors contient les détails.
400	INVALID_MERCHANT_ID	merchant_id ne correspond pas à la clé API de la boutique.
400	NO_PAYMENT_METHOD	Aucune méthode de paiement configurée. Ajoutez au moins un portefeuille ou configurez une plateforme d'échange avant de créer des factures.
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.
402	INSUFFICIENT_BALANCE	Solde de la boutique insuffisant pour les frais. details contient current_balance, required_fee, shortage, fee_rate_percent, discount_percent, invoice_amount.
429	RATE_LIMIT_EXCEEDED	Limite de débit dépassée (burst ou soutenu). Contient limit_type, retry_after_seconds.
500	INTERNAL_ERROR	Erreur serveur.

Détails des codes d'erreur : Codes d'erreur API.

Limite de débit

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

Dépassement → HTTP 429, corps contient error_code: "RATE_LIMIT_EXCEEDED", retry_after_seconds.

Notes

• Méthode de paiement : La boutique doit configurer au moins une adresse de portefeuille ou une plateforme d'échange (Binance Pay, OKX, Bybit, MEXC, Gate.io, Bitget, etc.) avant de créer des factures. Si non configurée, l'API retourne l'erreur NO_PAYMENT_METHOD.
• Idempotence : Si vous envoyez un request_id qui existe déjà pour la même boutique, l'API retourne la facture existante au lieu d'en créer une nouvelle. La réponse inclura idempotent: true pour l'indiquer. Cela empêche la création de factures en double lors de la relance de requêtes échouées.
• Frais : Les frais sont calculés sur le amount (USD) et déduits du solde de la boutique. Assurez un solde suffisant avant de créer des factures. Pendant la période d'essai gratuit, les frais sont supprimés.
• Callback : Envoyez toujours callback_url pour recevoir les webhooks completed/expired ; sinon, vous ne pouvez vérifier que via GET https://api.payerscan.com/invoice/:trans_id.
• request_id : Recommandé pour faciliter la correspondance webhook-commande et le support de l'idempotence.