API de paiement

L'API de paiement vous permet de créer des sessions de paiement, de rediriger les clients vers une page de paiement hébergée et de suivre le statut des paiements.

Créer un paiement

{
  "state": 0,
  "result": {
    "uuid": "abc123-def456-...",
    "order_id": "ORDER-12345",
    "amount": "100.00",
    "currency": "USD",
    "amount_usd": "100.00",
    "exchange_rate": null,
    "url": "https://2328.io/pay/abc123-def456-...",
    "tg_deeplink": "https://t.me/my2328bot?start=pay_abc123-def456-...",
    "expires_at": "2026-01-11T21:00:00Z",
    "created_at": "2026-01-11T20:00:00Z",
    "payer_currency": "USDT",
    "payer_amount": "100.50",
    "network": "TRX-TRC20",
    "address": "TXYZabc123...",
    "payment_status": "check",
    "txid": null,
    "payment_amount": null,
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

curl -X POST https://api.2328.io/api/v1/payment \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Caisse hébergée, H2H, et montants exacts en crypto

Le même point de terminaison supporte trois formes distinctes de facture. Choisissez-en une délibérément ; ne mélangez pas leur sémantique de montant.

Caisse hébergée avec choix du payeur

Envoyez amount, currency, order_id, et url_callback, mais omettez to_currency et network. La réponse contient result.url ; address, qr, et parfois les champs du payeur restent null jusqu'à ce que le payeur sélectionne une direction sur la page hébergée.

{
  "amount": "125.00",
  "currency": "EUR",
  "order_id": "ORDER-2026-1042",
  "url_callback": "https://merchant.example/webhooks/2328",
  "url_return": "https://merchant.example/orders/ORDER-2026-1042"
}

Facture H2H à adresse directe

Envoyez à la fois to_currency et network. 2328.io crée la facture blockchain lors de l'appel API, donc une réponse réussie peut être affichée directement dans votre processus de paiement sans rediriger le client.

{
  "amount": "100.00",
  "currency": "USD",
  "to_currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1043",
  "url_callback": "https://merchant.example/webhooks/2328"
}

Rendez ces valeurs exactement telles que retournées :

• payer_amount et payer_currency — l'instruction de paiement ;
• network et address — la seule destination pour cette facture ;
• qr — un URI de données pour la même adresse ;
• expires_at — la date limite de la facture ;
• url — un fallback hébergé utile lorsque le processus de paiement personnalisé ne peut pas être complété.

Facture pour un montant exact de crypto

Placez la crypto-monnaie dans currency lorsque la facture elle-même est libellée en crypto :

{
  "amount": "25.000000",
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1044",
  "url_callback": "https://merchant.example/webhooks/2328"
}

La valeur crypto demandée est conservée dans payer_currency / payer_amount. Le service peut également maintenir une valorisation en USD en interne pour la comptabilité et les champs de taux ; ne remplacez pas l'instruction exacte en crypto par cette valorisation. Conservez les chaînes décimales retournées, y compris la précision finale.

Pour une cryptomonnaie ne disposant que d'un seul réseau pris en charge, le réseau peut être sélectionné automatiquement. Il est néanmoins recommandé de fournir network explicitement pour une intégration déterministe. Pour les actifs multi-réseaux tels que les stablecoins, envoyez-le toujours.

Idempotence et réessais

order_id est limité au projet marchand authentifié et agit comme la clé d'idempotence de création. Si un paiement existe déjà, l'API renvoie cette session avec state: 0.

Algorithme de création recommandé :

1. Insérez votre tentative de paiement locale et le order_id unique dans une seule transaction de base de données.
2. Envoyez la requête API signée.
3. Persistez le uuid retourné et la réponse complète.
4. Si le résultat HTTP est perdu, réessayez la même requête ou interrogez /v1/payment/info via order_id.
5. Ne créez jamais une deuxième commande locale simplement parce que la requête en amont a expiré.

Cas limites de paiement

L'URL de retour du navigateur est uniquement de navigation. Un client peut l'ouvrir sans payer, la fermer après avoir payé, ou la rejouer plus tard. Seul un état vérifié de l'API/webhook peut régler la commande du commerçant.

Informations sur le paiement

curl -X POST https://api.2328.io/api/v1/payment/info \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Liste des paiements

curl -X POST https://api.2328.io/api/v1/payment/list \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"