Order status and callback

Recommendation

We highly recommend using callbacks instead of long-polling to get the status.

Request

To identify the order's status, you can make the following API call:

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

One of the following parameters is expected:

• order_id – Unique payment identifier in the merchant system
• order_uuid – Order ID in the FlyPay system

Response

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

Description of parameters in the response:

• order_uuid – Order ID in the FlyPay system
• order_type – Order type
• user_order_id – Unique payment identifier in the merchant system
• description – Order description
• expected_amount_from – Expected deposit amount
• amount_from – Actual deposit amount
• currency_from – Deposit currency
• network_from – Deposit network
• deposit_from_user – null
• wallet_from – Wallet from which the deposit was made (card number or blockchain address)
• wallet_memo_from – tag/memo of the address in the blockchain from which the deposit was made
• expected_amount_to – Expected amount to be credited to wallet (card or blockchain address)
• amount_to – Actual amount credited to wallet (card or blockchain address)
• strict_withdrawal_amount – true if amount_to was specified when creating the order
• currency_to – Withdrawal currency
• network_to – Withdrawal network
• withdraw_to_user – null
• wallet_to – Wallet to which the payment is made (card number or blockchain address)
• wallet_memo_to – tag/memo of the address in the blockchain to which the payment is made
• wallet_to_details – Contains the payment details specified during the request in the wallet_details parameter
• wallet_to_transactions – Contains withdrawal data for multiple cards, otherwise null
• amount_from_fee – Commission amount in deposit currency
• amount_to_fee – Commission amount in the withdrawal currency
• deposit_url – The URL to which the client should be redirected to make a deposit
• deposit_address – The address on the blockchain to which the deposit should be sent
• deposit_memo – tag/memo of the address in the blockchain to which the deposit should be sent
• deposit_address_title – The name of the deposit address, if it is a permanent deposit address, a name has been created for it
• deposit_address_initial_order_uuid – order_uuid of the first order in the system where this deposit address was used, if any
• blockchain_deposit_hash – Blockchain transaction hash for a completed cryptocurrency deposit
• blockchain_withdrawal_hash – Blockchain transaction hash for a completed cryptocurrency withdrawal
• exchange_rate_initial – Expected exchange rate when creating an order
• exchange_rate_actual – Actual exchange rate
• status – Order status (new)
• error_code – Error code
• error_message – Error message text
• created_at – Date and time of order creation in the format "Y-m-d H:i:s"
• updated_at – Date and time of order update in the format "Y-m-d H:i:s"
• finalized_at – Date and time of order finalization in the format "Y-m-d H:i:s"
• start_order_at – null
• currency_from_precision – Deposit or exchange currency precision, number of decimal places
• currency_to_precision – Withdrawal currency precision, number of decimal places

Unexpected errors during order creation

During the order creation phase, you may encounter errors and might be uncertain if the order was created. In this case you need to check that order was actually created or not.

Callback

You can also rely on the callback, which will be sent to the callback_url you specified during order creation, once the order receives its final status.

The structure of callback request is the same as data object from response of status call.

warning

There is no guarantee that the callback will only be delivered once.

Relies on the so-called at-least-once delivery.

We'll try to deliver callback until you respond with 200 OK or 201 OK http status code.

In case of any not expected response or network malfunction, will retry a delivery attempt no more than 20 times. Every next callback retry will be sent with double delay.

Order status list

Name	is final status?	Description
new	no	New, transactions are expected
processing	no	In processing, transactions are being executed
completed	yes	Successfully completed
completed_partially	yes	Partially executed, part of the amount remained on the merchant's balance unexchanged or unpaid (for orders with exchange or withdrawal)
canceled	yes	Cancelled. Used if the deposit was not received within the specified time
error	yes	Error. The order was not executed.