Developers

Orders en idempotentie

Het aanmaken van een order legt de koers vast en kent een stortingsadres toe. Het is de enige plek waar een integratiefout geld verplaatst: idempotentie is daar geen gemak.

Gepubliceerd contract, nog niet open

Deze endpoints worden vandaag niet blootgesteld. Ze zijn gedocumenteerd zodat u uw integratie vooraf kunt bouwen; hun vorm is vastgesteld, en elke brekende wijziging zal via een nieuwe versie en een changelog-entry gaan.

POST/api/v1/ordersPublished contract, not open

Een order aanmaken

Vergrendelt de koers en retourneert een specifiek stortingsadres. De order draagt de uitsplitsing als vergrendeld: deze is herspeelbaar, waardoor u de exacte toegepaste prijs zelfs maanden later kunt reconstrueren. De Idempotency-Key-header is vereist.

Authenticatie: Authorization: Bearer … Zie authenticatie

Parameters

Parameters
Veld	Type	Beschrijving
`quoteId`vereist	string	Identificatie van de geaccepteerde offerte.
`beneficiary`vereist	object	Velden opgelegd door het schema van de route. De naam moet overeenkomen met de geverifieerde identiteit: geen uitbetalingen aan derden.
`networkId`vereist	string	Netwerk waarop de storting zal worden verzonden. Het bepaalt het geretourneerde adres en, op sommige netwerken, de verplichte memo.

Verzoekbash

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"
    }
  }'

Antwoord — gepubliceerd contractjson

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

De memo is null op de meeste netwerken en verplicht op XRP, Stellar en TON. Het weglaten ervan daar verliest de fondsen: behandel het veld als verplicht zodra het niet-null is.

Mogelijke fouten: unauthorized, invalid_request, quote_expired, idempotency_conflict, beneficiary_rejected, country_not_served. Volledige catalogus

GET/api/v1/orders/{reference}Published contract, not open

Een order lezen

Huidige status en getimede overgangsgeschiedenis. De geschiedenis is de bron van waarheid: deze is alleen-toevoegen, nooit herschreven, en het is wat antwoordt op “waarom is mijn order naar die status verplaatst op dat tijdstip”.

Authenticatie: Authorization: Bearer … Zie authenticatie

Verzoekbash

curl -sS https://fiatside.com/api/v1/orders/K7Q4-M2XB \
  -H 'Authorization: Bearer sk_live_...'

Antwoord — gepubliceerd contractjson

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

Mogelijke fouten: unauthorized, not_found. Volledige catalogus

Idempotentie

Een aanmaakverzoek dat op het netwerk een time-out geeft, vertelt u niet of de order is aangemaakt. Zonder een idempotentiesleutel heeft u slechts twee slechte opties: opnieuw proberen en het risico van twee orders, of niet opnieuw proberen en het risico van geen enkele.

Headerhttp

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

Eén sleutel per intentie

De sleutel identificeert de intentie “die order aanmaken”, niet het HTTP-verzoek. Een uniek id aan uw kant: een winkelwagen-id, een UUID gegenereerd vóór de aanroep, nooit een teller.

Een replay retourneert de oorspronkelijke respons

Het opnieuw afspelen van dezelfde sleutel met dezelfde body retourneert de respons van het eerste verzoek, met dezelfde HTTP-status. Dat maakt een herpoging veilig, ook na een time-out.

Zelfde sleutel, andere body: conflict

De respons is een expliciet conflict. Als de inhoud verandert, moet de sleutel veranderen: anders kan niemand zien welke van de twee orders moet worden afgespeeld.

24-uursbewaring

Daarna wordt de sleutel vergeten en zou een replay een nieuwe order aanmaken. Probeer opnieuw binnen het venster, of controleer de status met het lees-endpoint.

De memo, op netwerken die er een vereisen

Op XRP, Stellar en TON is het stortingsadres niet voldoende: een extra identificatie duidt de uiteindelijke begunstigde aan. Het is de duurste oorzaak van incidenten in een off-ramp-integratie.

Een storting zonder memo is een verloren storting

Het memo-veld is null op de meeste netwerken en niet-null op netwerken die er een vereisen. Behandel het als verplicht zodra het niet-null is, en toon het met hetzelfde gewicht als het adres. Een storting die zonder memo op een gedeeld adres aankomt, vereist handmatig herstel, wat niet altijd lukt.

Orderstatussen

De onderstaande statussen zijn de statussen die uw integratie kan waarnemen. Overgangen worden voorzien van een tijdstempel en toegevoegd, nooit herschreven: de geschiedenis beantwoordt de vraag “waarom is mijn order op dat tijdstip naar die status gegaan”.

Orderstatussen
Status	Wat het betekent
`QUOTE_LOCKED`	De koers is bevroren. De order wacht op begunstigdegegevens of identiteitsverificatie.
`AWAITING_DEPOSIT`	Het stortingsadres is toegewezen en het stortingsvenster loopt. Dat is het enige moment om geld te sturen.
`DEPOSIT_DETECTED`	Er wordt een inkomende transactie op het netwerk gezien, nog niet bevestigd. Stel de gebruiker gerust, lever niets.
`CONFIRMING`	Bevestigingen stapelen zich op. Het vereiste aantal hangt af van het netwerk, niet van het bedrag.
`DEPOSIT_CONFIRMED`	De storting is beveiligd. Compliance- en herprijzingsregels worden vanaf hier geëvalueerd.
`UNDERPAID`	Het ontvangen bedrag ligt onder het verwachte bedrag buiten de tolerantie. Drie uitkomsten: bijstorten, doorgaan met het ontvangen bedrag, of terugbetaling.
`OVERPAID`	Het ontvangen bedrag overschrijdt de verwachting. Het oorspronkelijke bedrag blijft tegen de vastgelegde koers, het overschot wordt apart behandeld.
`PAYOUT_QUEUED`	De overboeking staat in de wachtrij. De wachtrij garandeert dat een uitbetaling precies één keer wordt verzonden, zelfs als meerdere workers tegelijkertijd actief zijn.
`PAYOUT_SENT`	De overboeking is verzonden via het netwerk. Verzonden is niet ontvangen: de uiteindelijke vertraging hangt af van de bank van de begunstigde.
`COMPLETED`	De afwikkeling is bevestigd door het netwerk. Eindtoestand.
`PAYOUT_FAILED`	Het netwerk heeft de overboeking afgewezen of teruggestuurd. Geen automatische herhaling: de oorzaak ligt bijna altijd in de details.
`REFUNDED`	Geld terug op het oorspronkelijke adres, na aftrek van netwerkkosten. Eindtoestand.