Developers

Замовлення та ідемпотентність

Створення ордера фіксує курс і призначає адресу депозиту. Це єдине місце, де помилка інтеграції переміщує гроші: ідемпотентність там не є зручністю.

Опублікований контракт, ще не відкритий

Ці кінцеві точки зараз не доступні. Вони задокументовані, щоб ви могли заздалегідь побудувати інтеграцію; їхня форма узгоджена, і будь-яка зміна, що порушує сумісність, пройде через нову версію та запис у журналі змін.

POST/api/v1/ordersPublished contract, not open

Створити замовлення

Фіксує курс і повертає спеціальну адресу для внесення. Замовлення несе деталізацію як зафіксовану: воно відтворюване, що дозволяє реконструювати точну застосовану ціну навіть через місяці. Заголовок Idempotency-Key є обов'язковим.

Автентифікація: Authorization: Bearer … Див. автентифікацію

Параметри

Параметри
Поле	Тип	Опис
`quoteId`обов'язковий	string	Ідентифікатор прийнятої цитати.
`beneficiary`обов'язковий	object	Поля, накладені схемою каналу. Ім'я має збігатися з підтвердженою особою: виплати третім особам заборонені.
`networkId`обов'язковий	string	Мережа, через яку буде здійснено внесення. Вона визначає повернуту адресу та, у деяких мережах, обов'язковий мемо.

Запитbash

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

Відповідь — опублікований контрактjson

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

Мемо є null у більшості мереж і обов'язковим у XRP, Stellar та TON. Його пропуск там призводить до втрати коштів: ставтеся до поля як до обов'язкового, щойно воно не null.

Можливі помилки: unauthorized, invalid_request, quote_expired, idempotency_conflict, beneficiary_rejected, country_not_served. Повний каталог

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

Читати замовлення

Поточний стан та історія переходів з часовими мітками. Історія є джерелом істини: вона лише додається, ніколи не переписується, і саме вона відповідає на питання «чому моє замовлення перейшло в цей стан у цей час».

Автентифікація: Authorization: Bearer … Див. автентифікацію

Запитbash

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

Відповідь — опублікований контрактjson

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

Можливі помилки: unauthorized, not_found. Повний каталог

Ідемпотентність

Запит на створення, який завершився тайм-аутом у мережі, не повідомляє, чи було створено ордер. Без ключа ідемпотентності у вас лише два погані варіанти: повторити та ризикувати двома ордерами, або не повторювати та ризикувати жодним.

Заголовокhttp

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

Один ключ на один намір

Ключ ідентифікує намір «створити цей ордер», а не HTTP-запит. Унікальний ідентифікатор на вашому боці: ідентифікатор кошика, UUID, згенерований перед викликом, ніколи не лічильник.

Повторення повертає оригінальну відповідь

Повторення того самого ключа з тим самим тілом повертає відповідь першого запиту з тим самим HTTP-статусом. Саме це робить повторення безпечним, зокрема після тайм-ауту.

Той самий ключ, інше тіло: конфлікт

Відповідь — явний конфлікт. Якщо вміст змінюється, ключ має змінюватися: інакше неможливо визначити, який із двох ордерів повторювати.

Зберігання протягом 24 годин

Після цього ключ забувається, і повторення створить новий ордер. Повторюйте в межах вікна або перевіряйте стан за допомогою кінцевої точки читання.

Мемо, на мережах, які його вимагають

На XRP, Stellar та TON адреси депозиту недостатньо: додатковий ідентифікатор визначає кінцевого отримувача. Це найчастіша причина інцидентів в інтеграції off-ramp.

Депозит без мемо — втрачений депозит

Поле memo має значення null на більшості мереж і не null на тих, що його вимагають. Ставтеся до нього як до обов'язкового, щойно воно не null, і відображайте його з тією ж вагою, що й адресу. Депозит, що надходить без мемо на спільну адресу, потребує ручного відновлення, яке не завжди успішне.

Стани ордера

Нижче наведено стани, які може спостерігати ваша інтеграція. Переходи фіксуються з часовими мітками та додаються, ніколи не перезаписуються: історія відповідає на питання «чому мій ордер перейшов у цей стан у цей час».

Стани ордера
Стан	Що це означає
`QUOTE_LOCKED`	Курс зафіксовано. Ордер очікує на деталі бенефіціара або верифікацію особи.
`AWAITING_DEPOSIT`	Адресу депозиту призначено, і вікно депозиту відкрите. Це єдиний момент для надсилання коштів.
`DEPOSIT_DETECTED`	Вхідну транзакцію видно в мережі, але ще не підтверджено. Заспокойте користувача, нічого не видавайте.
`CONFIRMING`	Підтвердження накопичуються. Необхідна кількість залежить від мережі, а не від суми.
`DEPOSIT_CONFIRMED`	Депозит захищено. Правила комплаєнсу та переоцінювання оцінюються з цього моменту.
`UNDERPAID`	Отримана сума нижча за очікувану понад допустиму межу. Три варіанти: поповнити, продовжити з отриманою сумою або отримати відшкодування.
`OVERPAID`	Отримана сума перевищує очікувану. Початкова сума залишається за зафіксованим курсом, надлишок обробляється окремо.
`PAYOUT_QUEUED`	Переказ у черзі. Черга гарантує, що виплата буде надіслана один раз, навіть якщо кілька воркерів спрацюють паралельно.
`PAYOUT_SENT`	Переказ відправлено через платіжну систему. Відправлено не означає отримано: остаточна затримка залежить від банку отримувача.
`COMPLETED`	Розрахунок підтверджено платіжною системою. Кінцевий стан.
`PAYOUT_FAILED`	Платіжна система відхилила або повернула переказ. Автоматичних повторних спроб немає: причина майже завжди в деталях.
`REFUNDED`	Кошти повернуто на адресу відправника, за вирахуванням мережевих комісій. Кінцевий стан.