Documentation API

Toutes les routes /api/v1/* sauf /status, /estimate et /min-amount exigent la clé secrète (Configuration → API paiement). Un de ces en-têtes suffit, dans cet ordre de lecture : x-syli-api-key, x-api-key, Authorization: Bearer.

GET /currencies est authentifié volontairement : la liste n’est pas le catalogue public SYLI Payments, c’est votre sélecteur (wallets validés dans Réception). Afficher une autre crypto ferait échouer POST /payment.

Format : syli_live_…. Une régénération invalide la clé précédente. Clé absente ou invalide : HTTP 503 et message générique — pas de 401, pour ne pas confirmer qu’une clé existe. Compte désactivé ou KYC manquant : 403.

Avec la clé, la liste n’est pas le catalogue mondial : uniquement les cryptos du compte qui ont une adresse validée dans Dashboard → Réception. C’est le contrat du sélecteur pour une UI maison. Une crypto hors liste est refusée au POST /payment.

currencies = codes. accepted et available sont la même liste enrichie (label, ticker, réseau) — available existe pour la rétrocompatibilité.

Le prix facturé est en USDT (price_currency: "usdt"). usd est accepté et stocké / renvoyé comme usdt. Alias : usdtbep20 → usdtbsc, usdc → usdcerc20, bnb → bnbbsc.

Génère une adresse unique pour cette commande. Affichez pay_address, le QR, le montant pay_amount (dans la crypto choisie), et payin_extra_id dès qu’il est non null — destination tag XRP, payment ID Monero. Sans extra ID, le payin peut être irrécupérable.

pay_currency doit figurer dans GET /currencies. Stables (USDT / USDC) : montant 1:1, pas de gel de taux. BTC, ETH, SOL, BNB, XRP, XMR : taux gelé jusqu’à expiration_estimate_date.

Idempotence : si vous renvoyez le même order_id alors qu’un paiement de ce compte est encore actif (waiting, confirming, confirmed, sending, partially_paid), l’API renvoie l’existant au lieu d’en créer un second. Utile en cas de retry réseau. Un nouvel essai après expired / failed / refunded crée un nouveau paiement.

ipn_callback_url surcharge l’URL webhook du dashboard si elle est fournie. Sinon SYLI Payments utilise celle enregistrée sur le compte. outcome_amount vaut le reçu on-chain (actually_paid), pas le net payout.

Resynchronise le payin avec la chaîne avant de répondre. Si le processeur est injoignable, le dernier snapshot local est renvoyé plutôt qu’une erreur. Même objet que POST /payment.

Champs à suivre : payment_status (payin — livrer sur confirmed), actually_paid, payin_hash, puis payout_status / payout_hash pour le virement vers votre wallet. Un GET facture ne remplace pas cet appel : l’invoice n’a pas de statut de paiement.

Crée une session checkout, pas encore un paiement. Le client ouvre invoice_url (https://sylipayments.com/pay/…). L’adresse on-chain n’existe qu’après choix de la crypto sur la page SYLI Payments (ou si vous figez pay_currency).

Si pay_currency est omis, le client choisit parmi vos wallets validés. Au moins une crypto configurée est requise. success_url / cancel_url doivent être des URL HTTPS valides. GET /invoice/:id renvoie la facture, pas le payin — pour le statut, webhook ou GET /payment/:id.

Recréer un paiement sur un checkout déjà clos (expired, failed, refunded) : HTTP 410.

Renvoie la facture, y compris invoice_url. Pas de payment_status : la facture n’est pas le payin.

POST JSON à chaque changement de statut utile (payin ou payout). En-tête x-syli-sig : HMAC-SHA512 hex du JSON canonique — parsez le body, triez les clés de premier niveau, JSON.stringify(obj, Object.keys(obj).sort()), puis HMAC. Ne signez pas le body HTTP brut : l’ordre des clés du transport n’est pas celui de la signature. Répondez 2xx sinon relance automatique (jusqu’à 8 tentatives : 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h, 24 h).

Livrez si payment_status === "confirmed". Ne livrez pas sur payout_status : le client a déjà payé, le virement wallet peut arriver après. En API, sending / finished internes au payin sont déjà mappés en confirmed. Le versement = payout_status (sending ou finished) et payout_hash.

Payload plat : payment_id, invoice_id, payment_status, pay_address, price_amount, price_currency, pay_amount, actually_paid, pay_currency, order_id, order_description, outcome_amount, outcome_currency, payout_amount, payout_hash, payin_hash, payout_status. Pas de payin_extra_id dans le webhook.

GET /api/v1/status — santé du service, sans auth. Pinge aussi le processeur de paiement : s’il est down, attendez-vous à un 503.

GET /api/v1/estimate donne un montant crypto indicatif (pas le taux gelé du paiement). Le gel n’existe que sur un POST /payment en crypto volatile, jusqu’à expiration_estimate_date.

GET /min-amount : minimum marchand SYLI Payments = max(1 USDT, 4 × frais réseau estimés) pour toutes les cryptos, y compris USDT TRC-20. rule vaut syli. processor_min_amount est informatif : le processeur peut créer une charge plus haute en interne, le checkout affiche toujours le montant marchand. Un payin à ≥ 99,5 % du pay_amount est traité comme couvert (confirmed), pas comme un partiel.