Fiatside
en

Developpeurs

Commandes et idempotence

Creer une commande verrouille le taux et attribue une adresse de depot. C’est le seul endroit ou une erreur d’integration deplace de l’argent : l’idempotence n’y est pas une option de confort.

Contrat publie, pas encore ouvert

Ces endpoints ne sont pas exposes aujourd’hui. Ils sont documentes pour que vous puissiez construire votre integration en amont ; leur forme est arretee, et toute modification cassante passera par une nouvelle version et une entree au journal des versions.

POST/api/v1/ordersContrat publie, non ouvert

Creer une commande

Fige le taux et rend une adresse de depot dediee. La commande porte la decomposition telle qu’elle a ete verrouillee : elle est rejouable, ce qui permet de reconstituer exactement le prix applique meme des mois plus tard. L’en-tete Idempotency-Key est obligatoire.

Authentification : Authorization: Bearer … Voir l’authentification

Parametres

Parametres
ChampTypeDescription
quoteIdrequisstringIdentifiant de la cotation acceptee.
beneficiaryrequisobjectChamps imposes par le schema du rail. Le nom doit correspondre a l’identite verifiee : aucun payout vers un tiers.
networkIdrequisstringReseau sur lequel le depot sera envoye. Il determine l’adresse rendue et, sur certains reseaux, le memo obligatoire.
Requetebash
curl -sS -X POST https://fiatside.com/api/v1/orders \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33' \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteId": "qt_01J9Z...",
    "networkId": "tron",
    "beneficiary": {
      "railId": "sepa_instant",
      "beneficiaryName": "Camille Dupont",
      "iban": "FR7630001007941234567890185"
    }
  }'
Reponse — contrat publiejson
{
  "reference": "K7Q4-M2XB",
  "state": "AWAITING_DEPOSIT",
  "deposit": {
    "asset": "USDT",
    "network": "tron",
    "address": "T...",
    "memo": null,
    "amountBase": "1000000000",
    "expiresAt": "2026-09-02T12:41:00Z"
  },
  "payout": { "railId": "sepa_instant", "netMinor": 91228, "currency": "EUR" },
  "rateLock": { "midRate": "0.92168430", "lockedUntil": "2026-09-02T12:41:00Z" }
}
  • Le memo est nul sur la plupart des reseaux, et obligatoire sur XRP, Stellar et TON. L’omettre y fait perdre les fonds : traitez le champ comme obligatoire des qu’il est non nul.

Erreurs possibles : unauthorized, invalid_request, quote_expired, idempotency_conflict, beneficiary_rejected, country_not_served. Catalogue complet

GET/api/v1/orders/{reference}Contrat publie, non ouvert

Lire une commande

Etat courant et historique horodate des transitions. L’historique est la source de verite : il est ajoute en append-only, jamais reecrit, et c’est lui qui permet de repondre a « pourquoi ma commande est-elle passee dans cet etat a telle heure ».

Authentification : Authorization: Bearer … Voir l’authentification

Requetebash
curl -sS https://fiatside.com/api/v1/orders/K7Q4-M2XB \
  -H 'Authorization: Bearer sk_live_...'
Reponse — contrat publiejson
{
  "reference": "K7Q4-M2XB",
  "state": "COMPLETED",
  "transitions": [
    { "at": "2026-09-02T12:11:04Z", "from": "QUOTE_LOCKED",     "to": "AWAITING_DEPOSIT" },
    { "at": "2026-09-02T12:19:52Z", "from": "AWAITING_DEPOSIT", "to": "DEPOSIT_DETECTED" },
    { "at": "2026-09-02T12:21:10Z", "from": "CONFIRMING",       "to": "DEPOSIT_CONFIRMED" },
    { "at": "2026-09-02T12:21:44Z", "from": "PAYOUT_QUEUED",    "to": "PAYOUT_SENT" },
    { "at": "2026-09-02T12:22:03Z", "from": "PAYOUT_SENT",      "to": "COMPLETED" }
  ]
}

Erreurs possibles : unauthorized, not_found. Catalogue complet

01

Idempotence

Une requete de creation qui expire cote reseau ne vous dit pas si la commande a ete creee. Sans cle d’idempotence, vous n’avez le choix qu’entre deux mauvaises options : reessayer et risquer de creer deux commandes, ou ne pas reessayer et risquer de n’en avoir aucune.

En-tetehttp
Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33

Une cle par intention

La cle identifie l’intention « creer cette commande-la », pas la requete HTTP. Un identifiant unique cote vous : identifiant de panier, UUID genere avant l’appel, jamais un compteur.

Le rejeu rend la reponse d’origine

Rejouer la meme cle avec le meme corps rend la reponse de la premiere requete, avec le meme code HTTP. C’est ce qui rend un reessai sur, y compris apres un delai d’attente.

Meme cle, corps different : conflit

La reponse est un conflit explicite. Si le contenu change, la cle doit changer : sinon, personne ne peut savoir laquelle des deux commandes rejouer.

Retention 24 heures

Passe ce delai, la cle est oubliee et un rejeu creerait une nouvelle commande. Reessayez a l’interieur de la fenetre, ou verifiez l’etat avec l’endpoint de lecture.

02

Le memo, sur les reseaux qui l’exigent

Sur XRP, Stellar et TON, l’adresse de depot ne suffit pas : un identifiant complementaire designe le destinataire final. C’est la cause d’incident la plus couteuse d’une integration off-ramp.

Un depot sans memo est un depot perdu

Le champ memo est nul sur la plupart des reseaux, et non nul sur ceux qui l’exigent. Traitez-le comme obligatoire des qu’il est non nul, et affichez-le avec la meme importance que l’adresse. Un depot arrive sans memo sur une adresse partagee demande une recuperation manuelle, qui n’aboutit pas toujours.

03

Etats d’une commande

Les etats ci-dessous sont ceux que votre integration peut observer. Les transitions sont horodatees et ajoutees sans jamais etre reecrites : l’historique repond a la question « pourquoi ma commande est-elle passee dans cet etat a cette heure ».

Etats d’une commande
EtatCe qu’il signifie
QUOTE_LOCKEDLe taux est fige. La commande attend les coordonnees du beneficiaire ou la verification d’identite.
AWAITING_DEPOSITL’adresse de depot est attribuee et la fenetre de depot court. C’est le seul moment ou il faut envoyer les fonds.
DEPOSIT_DETECTEDUne transaction entrante est vue sur le reseau, pas encore confirmee. Rassurez l’utilisateur, ne livrez rien.
CONFIRMINGLes confirmations s’accumulent. Le nombre requis depend du reseau, pas du montant.
DEPOSIT_CONFIRMEDLe depot est acquis. Les regles de conformite et de reprix sont evaluees a partir d’ici.
UNDERPAIDLe montant recu est inferieur a l’attendu au-dela de la tolerance. Trois issues : completer, poursuivre au montant recu, ou etre rembourse.
OVERPAIDLe montant recu depasse l’attendu. Le montant initial reste au taux verrouille, l’excedent est traite separement.
PAYOUT_QUEUEDLe virement est en file. La file garantit qu’un payout n’est envoye qu’une fois, meme si plusieurs traitements se declenchent en parallele.
PAYOUT_SENTLe virement est parti sur le rail. Parti n’est pas recu : le dernier delai depend de la banque du beneficiaire.
COMPLETEDLe reglement est confirme par le rail. Etat terminal.
PAYOUT_FAILEDLe rail a rejete ou retourne le virement. Aucun reessai automatique : la cause est presque toujours dans les coordonnees.
REFUNDEDLes fonds sont retournes a l’adresse d’origine, frais de reseau deduits. Etat terminal.