Documentation / Intégration

Remboursements

Un remboursement est un virement de retour vers le client : en cas d'annulation de commande, de surpaiement ou de sous-paiement après expiration. Il se crée par une demande via l'API ou depuis le tableau de bord.

Qui envoie les fonds

Cela dépend du champ executor de la demande :

merchant : le paiement est arrivé sur votre portefeuille (cas habituel). Coinetic ne détient pas vos fonds : c'est vous qui envoyez le virement au client, puis enregistrez le hash de la transaction.
platform : le paiement est arrivé sur le portefeuille de la plateforme. Vous vous contentez de demander le remboursement ; un opérateur Coinetic vérifie l'adresse, approuve et envoie les fonds.

Règles

Uniquement dans l'actif du paiement. Le client a payé en USDT sur TRON ? Il est remboursé en USDT sur TRON. Aucune conversion.
Jamais plus que le montant payé : consultez le refundable_amount de la facture. Les remboursements partiels sont possibles, jusqu'à 20 demandes ouvertes par facture.
L'adresse doit être sur le réseau du paiement. Elle est contrôlée selon le format du réseau (EVM : somme de contrôle EIP-55). Les adresses appartenant à Coinetic sont refusées.
Une facture payée reste payée. Le montant remboursé figure dans refunded_amount.
Sur une facture non payée, un remboursement la clôture définitivement, même s'il est partiel : la facture passe en cancelled et les paiements complémentaires ne régleront plus la commande. Vérifiez le statut de la facture avant de créer la demande.

Créer une demande

POST/v1/refunds

HTTP

POST /v1/refunds
Idempotency-Key: refund-ORDER-1001-1
Content-Type: application/json

{"invoice_id":"inv_x7k2…","amount_minor":"10500000","address":"TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE","reason":"Annulation de la commande ORDER-1001"}

Champ	Obligatoire	Valeur
`invoice_id`	oui	Une facture de votre boutique
`amount_minor`	oui	Unités minimales sous forme de chaîne (`"10500000"` = 10,5 USDT avec 6 décimales) ou `"full"` pour la totalité du montant disponible
`address`	oui	Adresse du client sur le réseau du paiement
`reason`	non	Motif, 500 caractères maximum

Remboursement depuis votre portefeuille

Envoyez au client le amount de la demande, dans l'actif et sur le réseau du paiement, depuis votre portefeuille (les frais de réseau sont à votre charge).
Enregistrez le hash de la transaction :

HTTP

POST /v1/refunds/{id}/executed
Idempotency-Key: refund-exec-ORDER-1001-1
Content-Type: application/json

{"tx_hash":"0x5c50…","ack_status_change":false}

La demande passe en reported. Sur les réseaux EVM (Ethereum, BSC, Polygon, Base, Arbitrum), Coinetic retrouve lui-même la transaction confirmée dans la blockchain et fait passer la demande en sent, avec le webhook refund.sent. Sur Bitcoin, Litecoin, TRON et Solana, cette vérification automatique n'existe pas encore : la demande reste en reported.

Vous changez d'avis ? POST /v1/refunds/{id}/cancel avec un motif : le montant redevient remboursable.

Statuts

Statut	Signification
`requested`	Demande enregistrée
`approved`	Approuvée par un opérateur (uniquement `executor: platform`)
`reported`	Vous avez communiqué le hash, confirmation sur le réseau en attente
`sent`	Fonds envoyés ; `tx_hash` est la transaction sur le réseau
`rejected`	Refusée ou annulée, motif dans `reject_reason`

Un refus n'est pas notifié par webhook : vérifiez périodiquement les demandes ouvertes avec GET /v1/refunds?status=requested.

En sandbox

POST /v1/refunds/{id}/simulate déroule tout le parcours d'un coup : la demande passe en sent avec un tx_hash de test, et refund.sent est envoyé. Cette route n'existe pas en production.