# 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

<TwoCol>

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 | Valeurs |
|-------|------|--------|-------------|---------|
| `amount` | decimal | oui | Montant du paiement dans la devise, par ex. `100.00` | <InputValue name="amount" type="decimal" example="100.00" /> |
| `currency` | string | oui | Devise fiat (USD, EUR, RUB, …) ou cryptomonnaie (USDT, TRX, BTC, …) | <EnumValues name="currency" values="USD,EUR,RUB,KZT,UAH,UZS,USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" /> |
| `order_id` | string | oui | Votre ID de commande, par ex. `ORDER-12345` (jusqu'à 128 caractères) | <InputValue name="order_id" example="ORDER-12345" /> |
| `to_currency` | string | non | Cryptomonnaie présélectionnée | <EnumValues name="to_currency" values="USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" optional /> |
| `network` | string | non\* | Code de réseau (requis si `to_currency` est défini ou si `currency` est une cryptomonnaie) | <EnumValues name="network" values="TRX-TRC20,ETH-ERC20,BSC-BEP20,TON,SOL,BTC,MATIC,XMR" optional /> |
| `url_return` | string | non | URL de redirection après le paiement, par ex. `https://your-site.com/return` | <InputValue name="url_return" placeholder="https://your-site.com/return" /> |
| `url_success` | string | non | Alternative à `url_return` | <InputValue name="url_success" placeholder="https://your-site.com/success" /> |
| `url_callback` | string | non | URL pour les notifications webhook, par ex. `https://your-site.com/webhook` | <InputValue name="url_callback" example="https://your-site.com/webhook" /> |
| `invite_code` | string | non | Code parrain | <InputValue name="invite_code" placeholder="ref_xyz" /> |
| `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). | <InputValue name="fee_split" type="decimal" placeholder="30" /> |
| `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). | <InputValue name="price_markup" type="decimal" placeholder="5" /> |
| `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`**. | <InputValue name="description" placeholder="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`**. | <InputValue name="ttl_seconds" type="integer" placeholder="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.

<TwoColAside>

<Credentials />

<TryIt endpoint="POST /v1/payment">
  <Param name="amount" type="decimal" required />
  <Param name="currency" type="enum" required values="USD,EUR,RUB,KZT,UAH,UZS,USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" />
  <Param name="order_id" type="string" required />
  <Param name="to_currency" type="enum" values="USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" />
  <Param name="network" type="enum" values="TRX-TRC20,ETH-ERC20,BSC-BEP20,TON,SOL,BTC,MATIC,XMR" />
  <Param name="url_return" type="string" />
  <Param name="url_success" type="string" />
  <Param name="url_callback" type="string" />
  <Param name="invite_code" type="string" />
  <Param name="fee_split" type="decimal" />
  <Param name="price_markup" type="decimal" />
  <Param name="description" type="string" />
  <Param name="ttl_seconds" type="integer" />
</TryIt>

</TwoColAside>

</TwoCol>

## Informations sur le paiement

<TwoCol>

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) | <InputValue name="uuid" example="abc123-def456-..." /> |
| `order_id` | string | oui\* | Votre ID de commande | <InputValue name="order_id" placeholder="ORDER-12345" /> |

> **INFO:** Au moins l'un des champs `uuid` ou `order_id` est requis.

<TwoColAside>

<TryIt endpoint="POST /v1/payment/info">
  <Param name="uuid" type="string" />
  <Param name="order_id" type="string" />
</TryIt>

</TwoColAside>

</TwoCol>

## Liste des paiements

<TwoCol>

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

### Paramètres de la requête

| Champ | Type | Requis | Description | Valeurs |
|-------|------|--------|-------------|---------|
| `status` | string | non | Filtrer par statut de paiement (voir [References](/docs/references)) | <EnumValues name="status" values="pending,check,paid,underpaid_check,underpaid,overpaid,cancel,aml_lock" optional /> |
| `date_from` | date | non | Date de début (YYYY-MM-DD), par ex. `2026-01-01` | <InputValue name="date_from" example="2026-01-01" /> |
| `date_to` | date | non | Date de fin (YYYY-MM-DD), par ex. `2026-01-31` | <InputValue name="date_to" example="2026-01-31" /> |
| `page` | int | non | Numéro de page, par défaut `1` | <InputValue name="page" type="integer" example="1" /> |
| `per_page` | int | non | Éléments par page, par défaut `15`, max. `5000` | <InputValue name="per_page" type="integer" example="15" /> |

<TwoColAside>

<TryIt endpoint="POST /v1/payment/list">
  <Param name="status" type="enum" values="pending,check,paid,underpaid_check,underpaid,overpaid,cancel,aml_lock" />
  <Param name="date_from" type="string" />
  <Param name="date_to" type="string" />
  <Param name="page" type="integer" />
  <Param name="per_page" type="integer" />
</TryIt>

</TwoColAside>

</TwoCol>