Informations générales

Bienvenue dans la documentation de l'API 2328.io. Cette référence décrit comment intégrer le traitement des paiements en cryptomonnaie et les retraits dans votre application.

Démarrage

Pour commencer l'intégration :

1. Créez un compte marchand et un projet sur 2328.io
2. Obtenez votre project UUID et votre API key depuis les paramètres du projet
3. Générez une Payout API key distincte si vous prévoyez d'utiliser les retraits
4. Lisez la section Authentication pour apprendre à signer les requêtes
5. Effectuez votre premier appel Create Payment

URL de base

Toutes les requêtes API en production utilisent l'URL de base suivante :

https://api.2328.io/api

Ce que vous pouvez faire

Avec l'API 2328.io, vous pouvez :

• Accepter des paiements en crypto — créer des sessions de paiement et rediriger les clients vers une page de paiement hébergée ou un Telegram MiniApp
• Effectuer des retraits — envoyer par programmation des retraits depuis votre solde marchand vers n'importe quelle adresse blockchain
• Vérifier les soldes — consultez les soldes des comptes du marchand par devise, leur équivalent en USD et les montants verrouillés par AML
• Utiliser des portefeuilles statiques — générer des adresses de dépôt permanentes liées à un utilisateur ou à une commande
• Récupérer les taux de change — obtenir des taux en temps réel pour les paires fiat et crypto
• Recevoir des webhooks — être notifié instantanément lorsqu'un statut de paiement change

Limites de débit

L'API autorise jusqu'à 10 requêtes par seconde par projet. Les requêtes au-delà de cette limite reçoivent une réponse HTTP 429 Too Many Requests — patientez puis réessayez.

Choisissez le bon modèle d'intégration

Invariants d'intégration

Ces règles s'appliquent à chaque intégration en production :

• Backend only — ne pas garder les clés API dans les navigateurs, applications mobiles, journaux, analyses, et captures d'écran de support.
• Decimal strings — envoyer et stocker de l'argent sous forme de chaînes. Ne jamais arrondir la cryptomonnaie ou les taux de change avec une arithmétique flottante binaire.
• Immutable idempotency keys — générer order_id avant la première requête et conserver la requête complète avec celui-ci. Une nouvelle tentative avec le même order_id peut renvoyer l'objet original plutôt que d'appliquer des champs modifiés.
• Webhook-first settlement — les redirections, le sondage client, les hachages de transaction fournis par les utilisateurs et les délais d'attente HTTP ne constituent pas une preuve de paiement.
• Verify, deduplicate, then mutate — vérifier le HMAC, réclamer un enregistrement d'idempotence de manière atomique, mettre à jour la commande/le solde une seule fois et renvoyer rapidement un HTTP 200.
• Reconciliation — interroger périodiquement l'état des paiements, des portefeuilles statiques et des paiements afin qu'un webhook perdu ne puisse pas laisser de désaccord permanent.
• Dynamic availability — validez les paires de devises/réseaux avec /v1/directions ; un actif pris en charge peut toujours avoir une direction de dépôt ou de retrait temporairement désactivée.
• Explicit status policy — décidez comment votre produit gère le paiement partiel, le surpaiement, l'expiration, le verrouillage AML, le repli de conversion et les délais d'attente ambigus en amont avant la mise en service.

Données recommandées à conserver

Pour les paiements, stockez au minimum uuid, order_id, le corps original de la requête, amount, currency, payer_currency, payer_amount, network, address, expires_at, les dernières payment_status, txid, payment_amount, merchant_amount, le bloc optionnel convert, et le payload brut de webhook vérifié.

Pour les portefeuilles statiques, gardez le portefeuille uuid, l'adresse, la devise, le réseau, la référence client/compte, le statut et l'URL de rappel séparément des enregistrements de dépôt. Chaque dépôt nécessite sa propre transaction uuid, txid, statut, montant reçu, montant commerçant et résultat de conversion.