crypto-withdraws

Cryptocurrency withdraw

To connect to the cryptocurrency balance shop and cryptocurrency payway, you need to contact the supervising manager or support@qostiq.com.

Make sure that your shop is activated and configured to work via the API: shop ID is received, interaction URL is specified, secret key is generated and IP addresses of your services are specified. Limits of payway and the name are specified in the personal account — shop settings — payment methods / withdrawal directions.

Scheme of work with cryptocurrency withdraws

The shop makes a request to preliminary withdraw calculation and the possibility of creating a withdraw on these data. If you get result == true go to step 2. If you get result == error, you must analyze the error message in message.
The shop sends a request to create a withdraw. If result == true is received, the withdraw is created and the shop waits for a notification with the final status (step 3) or requests the withdraw status (step 4). If result == error is received, you must analyze the error message in message.
Qostiq system sends notifications to the URL for cryptocurrency interactions with the withdraw status.
The shop can request the current withdraw status as needed.

Withdraw: pre-calculation [/crypto/withdraw/try]

URL: https://core.qostiq.com/crypto/withdraw/try

Method: POST

Mandatory parameters: amount, amount_type, now, payway, shop_currency, shop_id

This request is not binding to create a withdraw. The request specifies the possibility of creating a withdraw with the specified parameters, returns the amounts debited from the shop and received by the client after fee calculation.

Example request:

{
    "amount": "1.00000001",
    "amount_type": "ps_amount",
    "now": 1655738319,
    "payway": "usdt_bep20",
    "shop_currency": "USDT",
    "shop_id": 6,
    "sign": "806b007c4cd5d855013237f250d0f91fe1569f9ee6e6125332714ee11d2eb2d8"
}

Where,

Parameter	Description	Format	Example
`amount`	transaction amount in cryptocurrency	String or number, see "Specifying the operation amount" for details	"1.00000001" or 1.00000001
`amount_type`	indicates the type of amount, possible values: `ps_amount` — amount to be received in the payment system, `shop_amount` — amount to be written off from the shop balance	String	"shop_amount" or "ps_amount"
`now`	request time, in the format unixtimestamp	Integer	1655738319
`payway`	Payment direction (blockchain and currency)	String	"usdt_bep20"
`shop_currency`	currency of the shop balance from which funds will be withdrawn	String	"USDT"
`shop_id`	shop identifier in the Qostiq system	Integer	6
`sign`	signature, see Signature formation rules for crypto operations (sign)	String	"806b007c4cd5d855013237f250d0f91fe1569f9ee6e6125332714ee11d2eb2d8"

Example response:

{
    "data": {
        "payee_currency": "USDT",
        "payee_receive": "1.000000001",
        "shop_currency": "USDT",
        "shop_write_off": "1.03000000103"
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Where,

data.payee_currency — currency of receipt by the client;

data.payee_receive — amount receivable by the client, in the currency of payway;

data.shop_currency — shop write-off currency;

data.shop_write_off — the amount written off the balance of the store in shop_currency.

Withdraw: create [/crypto/withdraw/create]

URL: https://core.qostiq.com/crypto/withdraw/create

Method: POST

Mandatory parameters: account, amount, amount_type, now, payway, shop_currency, shop_id, shop_payment_id

The request may also include the account_details parameter — an additional parameter for detailing information about the recipient's account (depends on the chosen payment direction). For example, comment refers to a TON Comment/Tag/Memo for withdrawals in the TON blockchain. A list of fields can be viewed in the personal account for each direction.

Example of sending additional parameters:

"account_details": {
    "comment": "12345678"
}

Example request:

{
    "account": "EQC67_9GtyJveay9fYwjuOUg2VvokASM3xI7MQ7R84UzC2Qx",
    "account_details": {
        "comment": "12345678"
    },
    "amount": "1",
    "amount_type": "ps_amount",
    "now": 1655802380,
    "payway": "ton_ton",
    "shop_currency": "TON",
    "shop_id": 6,
    "shop_payment_id": "test_withdraw_id_4",
    "sign": "bc21703c682f0b9f53d4b554cfd55d8a25fc75c0e386fe589033aa0f49f35d07"
}

Where,

Parameter	Description	Format	Required?	Example
`account`	payee address	String	yes	"EQC67_9GtyJveay9fYwjuOUg2VvokASM3xI7MQ7R84UzC2Qx"
`amount`	transaction amount in cryptocurrency	String or number, see "Specifying the operation amount" for details	yes	"1" or 1.00
`amount_type`	indicates the type of amount, possible values: `ps_amount` — amount to be received in the payment system, `shop_amount` — amount to be written off from the shop balance	String	yes	"shop_amount" or "ps_amount"
`now`	request time, in the format unixtimestamp	Integer	yes	1655802380
`payway`	Payment direction (blockchain and currency)	String	yes	"ton_ton"
`shop_currency`	currency of the shop balance from which funds will be withdrawn	String	yes	"TON"
`shop_id`	shop identifier in the Qostiq system	Integer	yes	6
`shop_payment_id`	unique transaction number on the shop side	String	yes	"test_withdraw_id_4"
`sign`	signature, see Signature formation rules for crypto operations (sign)	String	yes	"bc21703c682f0b9f53d4b554cfd55d8a25fc75c0e386fe589033aa0f49f35d07"
`account_details.comment`	detailed info about the recipient's account, for example Comment/Tag/Memo for TON network	String up to 255 characters	no	"12345678"
`description`	operation description	String up to 255 characters	no	"test description"
`crypto_callback_url`	URL for accepting a payout callback	String	no	"https://shop.com/callback/crypto"

Example response:

{
    "data": {
        "balance": "2.96",
        "id": 15,
        "payee_address": "EQC67_9GtyJveay9fYwjuOUg2VvokASM3xI7MQ7R84UzC2Qx",
        "payee_currency": "TON",
        "payee_receive": "1",
        "shop_currency": "TON",
        "shop_payment_id": "test_withdraw_id_4",
        "shop_write_off": "1.005",
        "status": 2
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Where,

data.balance — the available balance of the shop in the currency shop_currency after creating the withdraw;

data.id — transaction number in the Qostiq system;

data.payee_address — address to which the withdraw was created;

data.payee_currency — currency of receipt;

data.payee_receive — amount receivable by the client, in the currency of payway;

data.shop_currency — shop write-off currency;

data.shop_payment_id — withdraw number on the side of the shop;

data.shop_write_off — amount written off the balance of the store in shop_currency;

data.status — current operation status.

When you receive a network error on the request to create a withdraw, you must make a request for the withdraw status by shop_payment_id.

Withdraw: callback with final withdraw status [/crypto_withdraw/callback]

After receiving the final status of the crypto withdraw, the Qostiq system sends a callback to the shop at the crypto interaction URL specified in the settings.

Notifications are sent from IP addresses:

34.90.243.164
34.147.48.238
34.90.176.128
34.90.34.134
35.242.192.50

When you receive a notification, be sure to check the signature — sign, type of operation — callback_type, the status of the operation — status in the notification.

Method: POST, Content-Type=application/json

Example notification:

{
    "address": "0xf8227AA7aF9B5166AF69581C703A4398387B2B07",
    "callback_type": "crypto_withdraw",
    "created": "2022-06-29 10:29:47",
    "description": null,
    "payee_receive": "0.000100000000000000",
    "payment_id": 58,
    "payway": "bnb_bep20",
    "processed": "2022-06-29 10:30:33",
    "ps_currency": "BNB",
    "ps_data": {
        "transaction_hash": "0x8d3d3f6851a16c4f5d957124fa8444f4be9add351aa9c4e301e2eeff13a910df"
    },
    "shop_currency": "BNB",
    "shop_id": 6,
    "shop_order_id": "test_withdraw_id_5",
    "shop_write_off": "0.000103000000000000",
    "sign": "f8ec782aa4d1332532cc7ac5364ef979f593079505529d895e1f2c4a7cd0e024",
    "status": "success"
}

Where,

address — address on which the withdraw was created;

callback_type — type of transaction for which the notification came, "crypto_withdraw" for a withdraw;

created — date and time of withdraw creation;

description — withdraw description;

payee_receive — the amount sent to the customer to the address;

payment_id — unique identifier of the issued withdraw in the Qostiq system;

payway — payment direction in the Qostiq system through which the withdraw was created;

processed — date and time when the withdraw status changed (success or reject);

ps_currency — currency of the payment direction;

ps_data.transaction_hash — withdraw hash in the blockchain;

shop_currency — shop write-off currency;

shop_id — shop ID that created the withdraw;

shop_order_id — shop's transaction number;

shop_write_off — amount written off from the shop in shop_currency;

status — withdraw status;

sign — signature.

The signature is formed using the same algorithm as all operations, but all parameters whose value is not null and not an empty string are involved in forming the signature.

If the notification is received and processed correctly, it is necessary to return http status 200 and the message body OK. Otherwise notifications will be sent repeatedly, at increasing intervals, a total of 25 attempts, the last at the end of the day.

Example of a string to generate a signature:

0xf8227AA7aF9B5166AF69581C703A4398387B2B07:crypto_withdraw:2022-06-29 10:29:47:0.000100000000000000:58:bnb_bep20:2022-06-29 10:30:33:BNB:{"transaction_hash": "0x8d3d3f6851a16c4f5d957124fa8444f4be9add351aa9c4e301e2eeff13a910df"}:BNB:6:test_withdraw_id_5:0.000103000000000000:successTestkey1

Withdraw: status request by withdraw_id [/crypto/withdraw/status]

URL: https://core.qostiq.com/crypto/withdraw/status

Method: POST

Mandatory parameters: now, shop_id, withdraw_id

Example request:

{
    "now": 1655802380,
    "shop_id": 6,
    "withdraw_id": 15,
    "sign": "bc21703c682f0b9f53d4b554cfd55d8a25fc75c0e386fe589033aa0f49f35d07"
}

Where,

Parameter	Description	Format	Example
`now`	request time, in the format unixtimestamp	Integer	1655815845
`shop_id`	shop identifier in the Qostiq system	Integer	6
`withdraw_id`	transaction number on the Qostiq system (returned in response to `/crypto/withdraw/create` in parameter `data.id`)	Integer	15
`sign`	signature, see Signature formation rules for crypto operations (sign)	String	"175365f50e85fa717be6cb5dc3e456b09c5d3e2e6ee7046286ef31019f87ff59"

Example response:

{
    "data": {
        "id": 15,
        "payee_address": "0xf8227AA7aF9B5166AF69581C703A4398387B2B07",
        "payee_currency": "USDT",
        "payee_receive": "0.0001",
        "shop_currency": "USDT",
        "shop_payment_id": "test_withdraw_id_4",
        "shop_write_off": "0.000103",
        "status": 2
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Where,

data.id — transaction number in the Qostiq system;

data.payee_address — client's address to which the withdraw was created;

data.payee_currency — currency of receipt;

data.payee_receive — amount receivable by the client, in the currency of payway;

data.shop_currency — shop write-off currency;

data.shop_payment_id — transaction number on the shop;

data.shop_write_off — amount written off the balance of the shop in shop_currency;

data.status — current operation status.

Attention! The request for withdraw status should be made no more than once a minute.

If the payment is created, a unique payment identifier and its status will be returned in the response. Status can be final and non-final; with non-final status it is necessary to make a status request before receiving the final status, or wait to receive a callback after receiving the final withdraw status.

Withdraw: status request by shop_payment_id [/crypto/withdraw/shop_payment_status]

URL: https://core.qostiq.com/crypto/withdraw/shop_payment_status

Method: POST

Mandatory parameters: now, shop_id, shop_payment_id

Request returns the current withdraw status by the transaction ID on the store side — shop_payment_id. For example, if you receive a network error on the request to create a withdraw, you can get information about whether the withdraw was created in the Qostiq system and its current status.

Example request:

{
    "now": 1655802380,
    "shop_id": 6,
    "shop_payment_id": "test_withdraw_id_4",
    "sign": "bc21703c682f0b9f53d4b554cfd55d8a25fc75c0e386fe589033aa0f49f35d07"
}

Where,

Parameter	Description	Format	Example
`now`	request time, in the format unixtimestamp	Integer	1655815845
`shop_id`	shop identifier in the Qostiq system	Integer	6
`shop_payment_id`	transaction number on the shop side	String	"test_withdraw_id_4"
`sign`	signature, see Signature formation rules for crypto operations (sign)	String	"175365f50e85fa717be6cb5dc3e456b09c5d3e2e6ee7046286ef31019f87ff59"

Example response when a withdraw was created:

{
    "data": {
        "id": 15,
        "payee_address": "0xf8227AA7aF9B5166AF69581C703A4398387B2B07",
        "payee_currency": "USDT",
        "payee_receive": "0.0001",
        "shop_currency": "USDT",
        "shop_payment_id": "test_withdraw_id_4",
        "shop_write_off": "0.000103",
        "status": 2
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

data.id — transaction number on the Qostiq system;

data.payee_address — address to which the withdraw was created;

data.payee_currency — currency of receipt;

data.payee_receive — amount receivable by the client, in the currency of payway;

data.shop_currency — store write-off currency;

data.shop_payment_id — withdraw number on the side of the shop;

data.shop_write_off — the amount written off the balance of the store in shop_currency;

data.status — current withdraw status.

Example response if the withdraw was not created on the Qostiq system:

{
    "data": null,
    "error_code": 7,
    "message": "Withdraw (shop_payment_id='test_withdraw_id_5') is not found",
    "result": false
}

Attention! The request for withdraw status should be made no more than once a minute.

Withdraw: operation statuses [/status/crypto_withdraw]

Status	Value	Description	Final?
1	`New`	Withdraw created, waiting for processing	No, request the status
2	`Waiting`	Withdraw created, waiting for processing	No, request the status
3	`Success`	Withdraw successfully completed	Yes, funds written off from the store
4	`Rejected`	Withdraw rejected	Yes, funds are not debited from the store
5	`ProcessingError`	Processing error	No, request the status

Cryptocurrency shop balance

Requesting the cryptocurrency balance of the shop [/crypto/shop_balance]

URL: https://core.qostiq.com/crypto/shop_balance

Method: POST

Mandatory parameters: now, shop_id

Example request:

{
    "now": 1655821138,
    "shop_id": 6,
    "sign": "f2c67bc4f3cf7afdf9b08573de36d42b1fc1984d48187ef560d6163beeb907e7"
}

Where,

Parameter	Description	Format	Example
`now`	request time, in the format unixtimestamp	Integer	1655821138
`shop_id`	shop identifier in the Qostiq system	Integer	6
`sign`	signature, see Signature formation rules for crypto operations (sign)	String	"f2c67bc4f3cf7afdf9b08573de36d42b1fc1984d48187ef560d6163beeb907e7"

Example response:

{
    "data": {
        "balances": [
            {
                "available": "9.8",
                "currency": "USDT",
                "frozen": "0.0",
                "hold": "0.0"
            },
            {
                "available": "0.0000134",
                "currency": "BNB",
                "frozen": "0.000103",
                "hold": "0.0010475903"
            }
        ],
        "shop_id": 6
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Where,

data.balances — an array of data on currencies on the shop in which:

data.balances.available — balance available for withdraw;

data.balances.currency — balance cryptocurrency;

data.balances.frozen — frozen funds on the balance (for example, under the created withdraw, which is being processed);

data.balances.hold — temporarily withheld funds (for example: risky invoice).

Cryptocurrency withdraw​

Scheme of work with cryptocurrency withdraws​

Withdraw: pre-calculation [/crypto/withdraw/try]​

Withdraw: create [/crypto/withdraw/create]​

Withdraw: callback with final withdraw status [/crypto_withdraw/callback]​

Withdraw: status request by withdraw_id [/crypto/withdraw/status]​

Withdraw: status request by shop_payment_id [/crypto/withdraw/shop_payment_status]​

Withdraw: operation statuses [/status/crypto_withdraw]​

Cryptocurrency shop balance​

Requesting the cryptocurrency balance of the shop [/crypto/shop_balance]​

Cryptocurrency withdraw

Scheme of work with cryptocurrency withdraws

Withdraw: pre-calculation [/crypto/withdraw/try]

Withdraw: create [/crypto/withdraw/create]

Withdraw: callback with final withdraw status [/crypto_withdraw/callback]

Withdraw: status request by withdraw_id [/crypto/withdraw/status]

Withdraw: status request by shop_payment_id [/crypto/withdraw/shop_payment_status]

Withdraw: operation statuses [/status/crypto_withdraw]

Cryptocurrency shop balance

Requesting the cryptocurrency balance of the shop [/crypto/shop_balance]