Envoyer de la crypto à un client

Un payout transfère de la crypto de votre solde IzichangePay vers une adresse externe. Cas d’usage : rembourser un client, payer un prestataire, reverser des gains. Scope requis : payouts:write · Endpoint : POST /v1/payouts

1. Créer le retrait

curl -X POST https://api.izichangepay.com/v1/payouts \
  -H "Authorization: Bearer $IZIPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assetCode": "USDT.TRC20",
    "amount": "120.00",
    "destinationAddress": "TQ5n8Xk...",
    "merchantReference": "payout_2291",
    "idempotencyKey": "payout_2291"
  }'

Champ	Requis	Sens
`assetCode`	✅	Crypto et réseau, ex. `USDT.TRC20`. Le réseau doit correspondre à l’adresse.
`amount`	✅	Montant en chaîne.
`destinationAddress`	✅	Adresse du bénéficiaire. Validée selon le réseau de `assetCode`.
`destinationMemo`		Memo / tag, obligatoire sur certains réseaux (XRP, XLM, EOS…). Sans lui, les fonds peuvent être perdus.
`feeBearer`		`merchant` (défaut) ou `customer` — voir §2.
`merchantReference`		Votre référence, reprise dans les réponses et webhooks.
`idempotencyKey`		Rejouer la même clé retourne le payout déjà créé.
`note`		Note libre, usage interne.
`totpCode`		Code 2FA à 6 chiffres. Requis pour les appels par session dashboard, pas par clé API.

La réponse contient le id du payout et son statut initial. Ce n’est pas une confirmation : la transaction n’est pas encore diffusée.

2. Qui paie les frais

feeBearer décide de qui supporte les frais de service :

merchant (défaut) — le bénéficiaire reçoit exactement amount, les frais sont débités de votre solde en plus.
customer — les frais sont prélevés sur amount : le bénéficiaire reçoit moins que le montant demandé.

En customer, ne diffusez jamais amount comme « montant reçu » à votre utilisateur. Le montant réellement envoyé est plus faible. Lisez amount et feeAmount dans le webhook payout.confirmed pour communiquer le bon chiffre.

3. Suivre l’issue

Un payout traverse plusieurs états. Abonnez-vous à ces événements :

Événement	Sens
`payout.created`	Enregistré, avant diffusion.
`payout.approved`	Débloqué après validation (seuil ou conformité). N’apparaît que si une validation était requise.
`payout.confirmed`	Confirmé on-chain. C’est le seul état qui vaut règlement.
`payout.failed`	Échec définitif. Les fonds gelés sont libérés, votre solde est restauré.

{
  "event": "payout.confirmed",
  "timestamp": 1731843299,
  "data": {
    "payoutId": "b81d…",
    "merchantId": "9a20…",
    "object": {
      "id": "b81d…",
      "amount": "120.00",
      "feeAmount": "1.20",
      "feeBearer": "merchant",
      "assetCode": "USDT.TRC20",
      "destinationAddress": "TQ5n…",
      "networkFeeAmount": "0",
      "networkFeeAssetCode": "TRX",
      "status": "confirmed",
      "merchantReference": "payout_2291"
    }
  }
}

Rappel : les champs de la ressource sont dans data.object, pas dans data.

Vous pouvez aussi interroger l’état à tout moment : GET /v1/payouts/{id}.

4. Frais réseau

networkFeeAmount mérite une lecture attentive :

Avant payout.confirmed, c’est une estimation figée à la création.
Après, c’est le coût réel constaté on-chain.
Sur Tron, il peut valoir 0 alors que la transaction a bien coûté quelque chose : nous utilisons de l’énergie déléguée, qui ne se paie pas en TRX. Un 0 n’est donc pas une anomalie.

networkFeeAssetCode est la monnaie native du réseau (TRX, BNB, ETH…), différente de assetCode.

Erreurs courantes

Cas	Réponse
Solde insuffisant	`400` — vérifiez `GET /v1/accounts/balances` avant.
Adresse invalide pour le réseau	`400` — l’adresse ne correspond pas au réseau de `assetCode`.
Crypto désactivée	`400` `ASSET_DISABLED_PLATFORM` ou `ASSET_DISABLED_MERCHANT`.
Memo manquant sur un réseau qui l’exige	`400` — fournissez `destinationMemo`.

Catalogue complet : Codes d’erreur.

Voir aussi

Se faire reverser en fiat

Convertir la crypto en mobile money plutôt que l’envoyer on-chain.

Événements webhook

Le format exact de payout.*.

Démarrage

Guides d'intégration

Intégration API

Webhooks

Wallet-as-a-Service

SDKs

Cas d'usage

Envoyer de la crypto à un client

1. Créer le retrait

2. Qui paie les frais

3. Suivre l’issue

4. Frais réseau

Erreurs courantes

Voir aussi

Se faire reverser en fiat

Événements webhook

​1. Créer le retrait

​2. Qui paie les frais

​3. Suivre l’issue

​4. Frais réseau

​Erreurs courantes

​Voir aussi

Se faire reverser en fiat

Événements webhook

1. Créer le retrait

2. Qui paie les frais

3. Suivre l’issue

4. Frais réseau

Erreurs courantes

Voir aussi