Documentation API

Toutes les routes /api/v1/* sauf /status, /estimate et /min-amount exigent la clé secrète (Configuration → Clés API). En-tête recommandé : x-api-key. Alternatives toujours acceptées : x-syli-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_… ou syli_test_…. Une régénération invalide seulement la clé du même mode. Compte désactivé : 403 (account_disabled). Par défaut, clé absente ou invalide → HTTP 503 (inchangé). Opt-in : envoyez x-syli-api-version: 2026-10 pour recevoir HTTP 401 et le code invalid_api_key. La dépréciation du 503 d’auth prend effet le 2027-04-02.

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).

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.

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. actually_paid_usd est le montant réellement reçu en dollars (1:1 pour USDT/USDC, sinon prorata price_amount × actually_paid / pay_amount). 0 tant qu’aucun payin n’est vu.

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 et que GET /invoice/:id.

Champs à suivre : payment_status (payin — livrer sur confirmed), actually_paid (crypto), actually_paid_usd (dollars), payin_hash, puis payout_status / payout_hash pour le virement vers votre wallet. L’id peut être celui du paiement ou de la facture checkout : même objet.

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 le même objet que GET /payment/:id (statut, actually_paid, actually_paid_usd). Tant que le client n’a pas choisi la crypto, payment_id est null et le statut reste waiting. POST /invoice reste la création du checkout (plugins, lien de paiement).

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

Statut du payin, identique à GET /payment/:id (payment_status, actually_paid, actually_paid_usd, invoice_url). Ce n’est pas le JSON de POST /invoice (id + invoice_url). Vous pouvez aussi passer l’id facture à GET /payment/:id.

Tant que le client n’a pas choisi la crypto, payment_id est null et le statut reste waiting. Après le choix, l’objet est celui du paiement (adresse, montants, hashes).

POST JSON à chaque changement de statut utile (payin ou payout). En-têtes x-syli-sig-v2, x-syli-timestamp, x-syli-event-id (stable entre retries de la même livraison) et x-syli-sig (v1, conservé). Secret IPN : Dashboard → Configuration → Clés API. 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). Le timestamp v2 est recalculé à chaque tentative pour rester dans la fenêtre de 5 minutes.

Livrez si payment_status vaut confirmed. Ne livrez pas sur payout_status : le client a déjà payé, le virement wallet peut arriver après. Voir Cycle de vie pour le détail du mapping des statuts.

Payload plat : payment_id, invoice_id, payment_status, pay_address, price_amount, price_currency, pay_amount, actually_paid, actually_paid_usd, pay_currency, order_id, order_description, outcome_amount, received_amount (alias additif de outcome_amount : reçu on-chain, pas le net), 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 = max(1 USDT, 4 × frais réseau estimés) pour toutes les cryptos, y compris USDT TRC-20. rule est vide (plancher marchand) ou processor. 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.