Статус ордера і колбек

Рекомендація

Ми рекомендуємо використовувати колбеки замість постійних запитів на отримання статусу ордера.

Запит

Щоб отримати статус ордера, ви можете використовувати наступний запит до API:

POST /v2/order/status

POST /v2/order/status HTTP/1.1
Content-Type: application/json
Accept: application/json; charset=utf-8
Api-key: {publicApiKey}
Signature: {signature}
{
    /* One of the following: */
    "order_id": "merchant_unique_order_id"
    /* or */
    "order_uuid": "3e7d0f84-d655-4069-991c-ad4739874ca5"
}

Очікується один із наступних параметрів:

• order_id – Унікальний ідентифікатор платежу у системі мерчанта
• order_uuid – ID ордера в системі FlyPay

Відповідь

RESPONSE

HTTP/1.1 200 OK
Content-Type: application/json

{
    /* The overall status of the request, not the order status */
    "status": "success",
    "data": {
        "order_uuid":"3e7d0f84-d655-4069-991c-ad4739874ca5",
        "order_type":"deposit_exchange_withdraw",
        "user_order_id":"merchant_unique_order_id",
        "description": null,
        "expected_amount_from":"29",
        "amount_from":null,
        "currency_from":"usdt",
        "network_from":"trc20",
        "deposit_from_user": null,
        "wallet_from":null,
        "wallet_memo_from":null,
        "expected_amount_to":"0.00103988",
        "amount_to":null,
        "strict_withdrawal_amount": false | true,
        "currency_to":"btc",
        "network_to":"btc",
        "withdraw_to_user": null,
        "wallet_to":"2N9MQVd2rQZF9TEE3SXHzjvBUNgFWr2qf6V",
        "wallet_memo_to":null,
        "wallet_to_details": null | {},
        "wallet_to_transactions": [],
        "amount_from_fee":null,
        "amount_to_fee":"0",
        "deposit_url":null,
        "deposit_address":"TVb4KtWABb9vyzMhiLm3cgFaE11MCZfvQu",
        "deposit_memo":null,
        "blockchain_deposit_hash": null,
        "blockchain_withdrawal_hash": null,
        "exchange_rate_initial":"0.000035858",
        "exchange_rate_actual":null,
        "client_info": {
           "client_id": "id1234",
           "client_ip": "127.0.0.1",
           "client_email": "[email protected]"
        },
        /* Order status */
        "status":"new",
        "error_code":0,
        "error_message":"",
        "created_at":"1970-01-01 19:17:37",
        "updated_at":"1970-01-01 19:17:38",
        "finalized_at":null,
        "start_order_at": null,
        "currency_from_precision": 2,
        "currency_to_precision": 8
    }
}

Опис параметрів у відповіді:

• order_uuid – ID ордера в системі FlyPay
• order_type – Тип ордера
• user_order_id – Унікальний ідентифікатор платежу у системі мерчанта
• description – Опис ордера
• expected_amount_from – Очікувана сума депозиту
• amount_from – Фактична сума депозиту
• currency_from – Валюта поповнення
• network_from – Мережа депозиту
• deposit_from_user – null
• wallet_from – Гаманець, з якого виконано депозит (номер картки або адреса в блокчейні)
• wallet_memo_from – tag/memo адреси в блокчейні, з якої виконано депозит
• expected_amount_to – Очікувана сума зарахування на гаманець (карту або адресу в блокчейні)
• amount_to – Фактична сума зарахування на гаманець (карту або адресу в блокчейні)
• strict_withdrawal_amount – true якщо amount_to була вказана під час створення ордера
• currency_to – Валюта виплати
• network_to – Мережа виплати
• withdraw_to_user – null
• wallet_to – Гаманець, на який відбувається виплата (номер картки або адреса блокчейну)
• wallet_memo_to – tag/memo адреси в блокчейні, на яку відбувається виплата
• wallet_to_details – Містить дані виплати, які вказувалися при запиті у параметрі wallet_details
• wallet_to_transactions – Містить дані виплати на кілька карток, інакше null
• amount_from_fee – Сума комісії у валюті депозиту
• amount_to_fee – Сума комісії у валюті виплати
• deposit_url – URL на який потрібно перенаправити клієнта для здійснення платежу
• deposit_address – Адреса в блокчейні, на яку потрібно надіслати депозит
• deposit_memo – tag/memo адреси в блокчейні, на яку потрібно надіслати депозит
• deposit_address_title – Назва депозит адреси, якщо це постійна депозит адреса, і для неї було створено назву
• deposit_address_initial_order_uuid – order_uuid першого ордера в системі, де була використана дана депозит адреса, якщо є
• blockchain_deposit_hash – Хеш транзакції в блокчейні для завершеного депозиту в валюті крипто
• blockchain_withdrawal_hash – Хеш транзакції у блокчейні для завершеної виплати у крипто валюті
• exchange_rate_initial – Очікуваний курс обміну під час створення ордера
• exchange_rate_actual – Фактичний курс обміну
• status – Статус ордера (new)
• error_code – Код помилки
• error_message – Текст повідомлення про помилку
• created_at – Дата та час створення ордера у форматі "Y-m-d H:i:s"
• updated_at – Дата та час оновлення ордера у форматі "Y-m-d H:i:s"
• finalized_at – Дата та час фіналізації ордера у форматі "Y-m-d H:i:s"
• start_order_at – null
• currency_from_precision – Точність валюти депозиту чи обміну, кількість знаків після коми
• currency_to_precision – Точність валюти виплати, кількість знаків після коми

Несподівані помилки у процесі створення ордера

На етапі створення ордера ви можете зіткнутися з помилками і не бути впевненим, чи був створений ордер. У цьому випадку вам необхідно перевірити, чи справді був ордер створений чи ні.

Колбек

Ви також можете покладатися на колбек, який буде надіслано на callback_url, який ви вказали при створенні ордера, як тільки ордер отримає свій остаточний статус.

Структура повідомлення колбека така сама, як і об'єкта у відповіді на запит статусу ордера.

важливо

Немає гарантії, що колбек буде доставлений лише один раз.

Працює так званий принцип хоча б однієї доставки.

Ми намагаємося доставити колбек доти, доки ви не відповісте кодом статусу http 200 OK або 201 OK.

У разі непередбаченої відповіді або збою мережі система повторить спробу доставки не більше 20 разів. Кожну подальшу спробу доставити колбек буде зроблено з подвійною затримкою.

Список статусів ордера

Назва	чи це фінальний статус?	Опис
new	ні	Новий, очікується проведення транзакцій
processing	ні	У процесі транзакції обробляються
completed	так	Успішно виконано
completed_partially	так	Виконано частково, частина суми залишилася на балансі мерчанта необміненою або невиплаченою (для ордерів з обміном чи виплатою)
canceled	так	Скасовано (використовується якщо депозит не було отримано у встановлений час)
error	так	Помилка. Ордер не був виконаний.