Paiements et retraits/Payment API

API de paiement

Créez et gérez des sessions de paiement en cryptomonnaie avec l'API de paiement 2328.io.

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

Crée une session de paiement et renvoie une URL pour que le client puisse payer.

Paramètres de la requête

Champ	Type	Requis	Description
`amount`	decimal	oui	Montant du paiement dans la devise, par ex. `100.00`
`currency`	string	oui	Devise fiat (USD, EUR, RUB, …) ou cryptomonnaie (USDT, TRX, BTC, …)
`order_id`	string	oui	Votre ID de commande, par ex. `ORDER-12345` (jusqu'à 128 caractères)
`to_currency`	string	non	Cryptomonnaie présélectionnée
`network`	string	non*	Code de réseau (requis si `to_currency` est défini ou si `currency` est une cryptomonnaie)
`url_return`	string	non	URL de redirection après le paiement, par ex. `https://your-site.com/return`
`url_success`	string	non	Alternative à `url_return`
`url_callback`	string	non	URL pour les notifications webhook, par ex. `https://your-site.com/webhook`
`invite_code`	string	non	Code parrain
`fee_split`	decimal	non	Part des frais marchands à la charge du payeur, 0–100 (%). 0 = le marchand paie l'intégralité, 100 = le payeur paie l'intégralité. Surcharge le paramètre du projet. Exemple : `30` (le payeur prend en charge 30 % des frais).
`price_markup`	decimal	non	Majoration ou remise sur le montant de la facture, −99 à 100 (%). Surcharge le paramètre du projet. Exemple : `5` (+5 %) ou `-10` (10 % de remise).
`description`	string	non	Description optionnelle de la facture (max. 200 caractères). Affichée au payeur sur la page de paiement. Exemple : `Premium plan — Order #12345`.
`ttl_seconds`	int	non	Durée de vie de la facture en secondes, de `300` (5 minutes) à `86400` (24 heures). Au-delà, la facture expire et ne peut plus être payée. Valeur par défaut : `3600` (1 heure). Exemple : `3600`.

Réponse

JSON

{
  "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..."
  }
}

Redirigez le client vers result.url pour finaliser le paiement.
tg_deeplink — deeplink du bot Telegram pour le paiement via Telegram MiniApp.
qr — QR code encodé en Base64 (data URI) de l'adresse de dépôt. Présent lorsqu'une adresse est déjà attribuée (lorsque network est défini avec to_currency, ou lorsque currency est une cryptomonnaie) ; sinon null.
txid, payment_amount — null jusqu'au paiement du client. Renseignés une fois la transaction détectée on-chain. Écoutez le webhook payment_status: paid pour savoir quand.
exchange_rate — null si la conversion n'est pas encore applicable (par ex. le taux fiat → crypto n'a pas été verrouillé). Renseigné une fois qu'une devise de paiement est choisie.

Credentials

Project UUIDAPI key

RequestPOST/v1/payment

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"

Response

Click Try it to see the response here.

Informations sur le paiement

Récupérez le statut actuel du paiement par uuid ou order_id.

Paramètres de la requête

Champ	Type	Requis	Description	Valeurs
`uuid`	string	oui*	UUID du paiement (depuis `result.uuid` à la création)
`order_id`	string	oui*	Votre ID de commande

Au moins l'un des champs uuid ou order_id est requis.

RequestPOST/v1/payment/info

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"

Response

Click Try it to see the response here.

Liste des paiements

Récupérez une liste de tous les paiements avec filtrage et pagination.

Paramètres de la requête

Champ	Type	Requis	Description
`status`	string	non	Filtrer par statut de paiement (voir References)
`date_from`	date	non	Date de début (YYYY-MM-DD), par ex. `2026-01-01`
`date_to`	date	non	Date de fin (YYYY-MM-DD), par ex. `2026-01-31`
`page`	int	non	Numéro de page, par défaut `1`
`per_page`	int	non	Éléments par page, par défaut `15`, max. `5000`

RequestPOST/v1/payment/list

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"

Response

Click Try it to see the response here.