crypto-withdraws

Криптовалютные выплаты

Для подключения на магазин криптовалютного баланса и криптовалютных направлений необходимо обратиться к курирующему менеджеру или на support@qostiq.com.

Убедитесь, что Ваш магазин активирован и настроен для работы по API: получен ID магазина, указан URL взаимодействия, сгенерирован секретный ключ и указаны IP адреса ваших сервисов. Лимиты платежных направлений и название payway указаны в личном кабинете - настройки магазина - методы оплаты/направления вывода.

Схема работы с криптовалютными выплатами

Магазин делает запрос предварительного расчета выплаты и возможности создания выплаты по указанным данным. При получении result == true переходим к шагу 2. При получении result==error, необходимо анализировать сообщение об ошибке в message.
Магазин отправляет запрос на создание выплаты. При получении result == true выплата создана и магазин ожидает уведомление с финальным статусом (шаг 3) или совершает запрос статуса выплаты (шаг 4). При получении result==error, необходимо анализировать сообщение об ошибке в message.
Система Qostiq отправляет магазину уведомления на URL для криптовалютных взаимодействий со статусом выплаты.
Магазин по необходимости может делать запрос актуального статуса выплаты .

Выплата: предрасчет [/crypto/withdraw/try]

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

Метод: POST

Обязательные параметры: amount, amount_type, now, payway, shop_currency, shop_id

Данный запрос не является обязательным для создания выплаты. Запрос уточняет возможность создания выплаты с указанными параметрами, возвращает суммы списания с магазина и получения клиентом после расчета комиссии.

Пример Запроса:

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

Где,

Параметр	Описание	Формат	Пример
`amount`	сумма опеарации в криптовалюте	String или number, количество знаков после запятой смотрите детальней в пункте "Указание суммы операции"	"1.00000001" или 1.00000001
`amount_type`	указывает на тип суммы, возможны значения: ps_amount – сумма к получению в платежной системе, shop_amount – сумма к списанию с баланса магазина	String	"shop_amount" или "ps_amount"
`now`	время запроса, в формате unixtimestamp	Integer	1655738319
`payway`	Платежное направление	String	"usdt_bep20"
`shop_currency`	валюта баланса магазина с которого будут сняты средства	String	"USDT"
`shop_id`	идентификатор магазина в системе Qostiq	Integer	6
`sign`	подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign)	String	"806b007c4cd5d855013237f250d0f91fe1569f9ee6e6125332714ee11d2eb2d8"

Пример ответа:

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

Где,

data.payee_currency - валюта получения выплаты клиентом;

data.payee_receive - сумма к получению клиентом, в валюте платежного направления - payway,

data.shop_currency - валюта списания суммы выплаты с магазина;

data.shop_write_off - сумма списания с баланса магазина в валюте shop_currency.

Предрасчет выплаты [POST]

Request

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

Response 200 ()

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

Выплата: создание [/crypto/withdraw/create]

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

Метод: POST

Обязательные параметры: account, amount, amount_type, now, payway, shop_currency, shop_id, shop_payment_id

Также в запросе могут быть передан account_details – дополнительный параметр, для детализации информации по аккаунту получателя средств (зависит от выбранного направления для выплат). Например comment это TON Comment/Tag/Memo для выводов в блокчейне Ton. Список полей можно посмотреть в личном кабинете по каждому направлению.

Пример отправки дополнительных параметров:
```
  "account_details": {
      "comment": "12345678"
  },
```

Пример запроса на создание выплаты:

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

Где,

Параметр	Описание	Формат	Обязательный параметр?	Пример
`account`	адрес получателя средств	String	да	"EQC67_9GtyJveay9fYwjuOUg2VvokASM3xI7MQ7R84UzC2Qx"
`amount`	сумма операции в криптовалюте	String или number, количество знаков после запятой смотрите детальней в пункте "Указание суммы операции"	да	"1" или 1.00
`amount_type`	указывает на тип суммы, возможны значения: ps_amount – сумма к получению в платежной системе, shop_amount – сумма к списанию с баланса магазина	String	да	"shop_amount" или "ps_amount"
`now`	время запроса, в формате unixtimestamp	Integer	да	1655802380
`payway`	Платежное направление	String	да	"ton_ton"
`shop_currency`	валюта баланса магазина с которого будут сняты средства	String	да	"TON"
`shop_id`	идентификатор магазина в системе Qostiq	Integer	да	6
`shop_payment_id`	уникальный номер операции на стороне магазина	String	да	"test_withdraw_id_4"
`sign`	подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign)	String	да	"bc21703c682f0b9f53d4 b554cfd55d8a25fc75c0e386f e589033aa0f49f35d07"
`account_details.comment`	детализация информации по аккаунту получателя средств, например Comment/Tag/Memo для сети TON	String до 255 знаков	нет	"12345678"
`description`	описание операции	String до 255 знаков	нет	"test description"
`crypto_callback_url`	URL для приема коллбэка по выплате	String	нет	"https://shop.com/callback/crypto"

Пример ответа:

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

Где,

data.balance - доступный баланс магазина в валюте shop_currency после создания операции;

data.id - номер операции в системе Qostiq;

data.payee_address - адрес на который создана выплата;

data.payee_currency - валюта получения выплаты;

data.payee_receive - сумма к получению клиентом, в валюте платежного направления - payway;

data.shop_currency - валюта списания с магазина по выплате;

data.shop_payment_id - номер выплаты на стороне магазина;

data.shop_write_off - сумма списания с баланса магазина в валюте shop_currency;

data.status - текущий статус операции.

При получении сетевой ошибка на запрос создания выплаты необходимо сделать запрос статуса выплаты по идентификатору магазина shop_payment_id.

Создание выплаты [POST]

Request

  ```json
  {
  "account": "0xf8227AA7aF9B5166AF69581C703A4398387B2B07",
  "amount": "0.0001",
  "amount_type": "ps_amount",
  "payway": "bnb_bep20",
  "shop_currency": "BNB",
  "shop_id": 6,
  "now": 1655802380,
  "shop_payment_id": "test_withdraw_id_4",
  "sign": "bc21703c682f0b9f53d4b554cfd55d8a25fc75c0e386fe589033aa0f49f35d07"
  }
  ```

Response 200 ()

  ```json
  {
  "data": {
  {
  "balance": "0.96",
  "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
  }
      

Выплата: уведомление о финальном статусе выплаты [/crypto_withdraw/callback]

После получения финального статуса криптовалютной выплаты, система Qostiq производит отправку уведомления магазину на указанный в настройках URL crypto взаимодействия.

Уведомления отправляются с IP-адресов:

34.90.243.164
34.147.48.238
34.90.176.128
34.90.34.134
35.242.192.50

При получении уведомления обязательно необходимо проверять подпись - sign, тип операции - callback_type, статус операции - status в уведомлении.

Метод: POST, Content-Type=application/json

Пример уведомления:

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

Где,

address – адрес на которых создана выплаты;

callback_type – тип операции по которой пришло уведомление, "crypto_withdraw" по выплате;

created – дата и время создания счета;

description – описание счета;

payee_receive - сумма отправленная клиенту на адрес;

payment_id – уникальный идентификатор выставленного счета в системе Qostiq;

payway – платежное направление в системе Qostiq, через которое оплатил пользователь;

processed – дата и время изменения статуса счета (оплата или отклонение);

ps_currency – валюта платежного направления, через которое оплатил пользователь;

ps_data.transaction_hash - хэш платежа в блокчейне;

shop_amount – сумма выставленного счета, в валюте счета;

shop_currency – валюта списания с магазина;

shop_id – уникальный идентификатор магазина, который создал выплату;

shop_order_id – номер операции на строне магазина;

shop_write_off – сумма зачисления списаная с магазина, в валюте счета shop_currency;

status – статус счета,

sign – подпись;

test_add_on – любой пользовательский параметр, переданный магазином при создании выплаты.

Подпись формируется по алгоритму, что и по всем операциям, но в формировании подписи участвуют все параметры, значение которых не null и пустая строка.

При корректном получении и обработке уведомления, необходимо вернуть в ответ http статус 200 и тело сообщения OK. В ином случае уведомления будут высылаться повторно, с увеличивающемся интервалом, всего 25 попыток, последнее по истечении суток.

Пример строки, по которой необходимо сгенерировать подпись

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

Уведомление о финальном статусе выплаты [POST]

Request

{
        "account": "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_payment_id": "test_withdraw_id_5",
        "shop_write_off": "0.000103000000000000",
        "sign": "834d007ca3d1552b3630cb47318a828508311461eb406826943471a44301dd7b",
        "status": "success"
}

Response 200 ()

{
    OK
}

Выплата: запрос статуса по withdraw_id [/crypto/withdraw/status]

URL:

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

Метод: POST

Обязательные параметры: now, shop_id, withdraw_id

Пример Запроса:

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

Где,

Параметр	Описание	Формат	Пример
`now`	время запроса, в формате unixtimestamp	Integer	1655815845
`shop_id`	идентификатор магазина в системе Qostiq	Integer	6
`withdraw_id`	Номер операции на стороне Qostiq (возвращается в ответе на запрос создания выплаты в параметре `data.id`)	Integer	15
`sign`	подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign)	String	"175365f50e85fa717be6cb5dc3e456b09c5d3e2e6ee7046286ef31019f87ff59"

Пример ответа:

{
    "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 - номер операции в системе Qostiq;

data.payee_address - адрес на который создана выплата;

data.payee_currency - валюта получения выплаты;

data.payee_receive - сумма к получению клиентом, в валюте платежного направления - payway;

data.shop_currency - валюта списания с магазина по выплате;

data.shop_payment_id - номер выплаты на стороне магазина;

data.shop_write_off - сумма списания с баланса магазина в валюте shop_currency;

data.status - текущий статус операции.

Внимание! Запрос статуса выплаты необходимо совершать не чаще чем раз в минуту.

Запрос статуса выплаты [POST]

Request

{
        "shop_id": 6,
        "now": 1655815845,
        "withdraw_id": 15,
        "sign": "175365f50e85fa717be6cb5dc3e456b09c5d3e2e6ee7046286ef31019f87ff59"
}

Response 200 ()

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

Выплата: запрос статуса по shop_payment_id [/crypto/withdraw/shop_payment_status]

URL:

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

Метод: POST

Обязательные параметры: now, shop_id, shop_payment_id

Запрос возвращает актуальный статус выплаты по идентификатору операции на стороне магазина - shop_payment_id. Например, при получении сетевой ошибки на запрос создания выплаты, можно получить информацию была ли создана выплата в системе Qostiq и ее актуальный статус.

Пример Запроса:

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

Где,

Параметр	Описание	Формат	Пример
`now`	время запроса, в формате unixtimestamp	Integer	1655815845
`shop_id`	идентификатор магазина в системе Qostiq	Integer	6
`shop_payment_id`	Номер операции на стороне Qostiq (возвращается в ответе на запрос создания выплаты в параметре `data.id`)	String	"test_withdraw_id_4"
`sign`	подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign)	String	"175365f50e85fa717be6cb5dc3e456b09c5d3e2e6ee7046286ef31019f87ff59"

Пример ответа:

{
    "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 - номер операции в системе Qostiq;

data.payee_address - адрес на который создана выплата;

data.payee_currency - валюта получения выплаты;

data.payee_receive - сумма к получению клиентом, в валюте платежного направления - payway;

data.shop_currency - валюта списания с магазина по выплате;

data.shop_payment_id - номер выплаты на стороне магазина;

data.shop_write_off - сумма списания с баланса магазина в валюте shop_currency;

data.status - текущий статус операции.

Пример ответа на запрос статуса выплаты, если выплата не была создана на стороне Qostiq:

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

Внимание! Запрос статуса выплаты необходимо совершать не чаще чем раз в минуту.

Запрос статуса выплаты [POST]

Request

{
        "shop_id": 6,
        "now": 1655815845,
        "shop_payment_id": "test_withdraw_id_5",
        "sign": "175365f50e85fa717be6cb5dc3e456b09c5d3e2e6ee7046286ef31019f87ff59"
}

Response 200 ()

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

Статусы выплат [/status/crypto_withdraw]

Status	Значение	Описание	Финальный?
1	`New`	Выплата создана, ожидает обработки	Нет, делать запрос статуса
2	`Waiting`	Выплата создана, ожидает обработки	Нет, делать запрос статуса
3	`Success`	Выплата успешно выполнена	Да, средства списаны с магазина
4	`Rejected`	Выплата отклонена	Да, средства не списаны с магазина
5	`ProcessingError`	Ошибка при выплате	Нет, делать запрос статуса

Запрос статуса выплаты [POST]

Request

{
        "shop_id": 6,
        "now": 1655815845,
        "withdraw_id": 15,
        "sign": "175365f50e85fa717be6cb5dc3e456b09c5d3e2e6ee7046286ef31019f87ff59"
}

Response 200 ()

{
        "data": {
        "currency": "BNB", 
        "id": 15, 
        "payee_address": "0xf8227AA7aF9B5166AF69581C703A4398387B2B07", 
        "payee_receive": "0.0001", 
        "shop_payment_id": "test_withdraw_id_4", 
        "status": 2
},
        "error_code": 0,
        "message": "Ok",
        "result": true
        }

Криптовалютный баланс магазина

Запрос криптовалютного баланса магазина [/crypto/shop_balance]

URL:

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

Метод: POST

Обязательные параметры: now, shop_id

Пример Запроса:

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

Где,

Параметр	Описание	Формат	Пример
`now`	время запроса, в формате unixtimestamp	Integer	1655821138
`shop_id`	идентификатор магазина в системе Qostiq	Integer	6
`sign`	подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign)	String	"f2c67bc4f3cf7afdf9b08573de36d42b1fc1984d48187ef560d6163beeb907e7"

Пример ответа:

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

Где,

data.balances - массив данных по валютам на магазине в котором:

data.balances.available - доступный для выплат баланс;

data.balances.currency - валюта баланса;

data.balances.frozen - замороженные средства на балансе, например, под созданную выплату, которая находится в обработке;

data.balances.hold - временно удержанные средства.

Запрос баланса магазина [POST]

Request

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

Response 200 ()

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

Криптовалютные выплаты​

Схема работы с криптовалютными выплатами​

Выплата: предрасчет [/crypto/withdraw/try]​

Предрасчет выплаты [POST]​

Выплата: создание [/crypto/withdraw/create]​

Создание выплаты [POST]​

Выплата: уведомление о финальном статусе выплаты [/crypto_withdraw/callback]​

Уведомление о финальном статусе выплаты [POST]​

Выплата: запрос статуса по withdraw_id [/crypto/withdraw/status]​

Запрос статуса выплаты [POST]​

Выплата: запрос статуса по shop_payment_id [/crypto/withdraw/shop_payment_status]​

Запрос статуса выплаты [POST]​

Статусы выплат [/status/crypto_withdraw]​

Запрос статуса выплаты [POST]​

Криптовалютный баланс магазина​

Запрос криптовалютного баланса магазина [/crypto/shop_balance]​

Запрос баланса магазина [POST]​

Криптовалютные выплаты

Схема работы с криптовалютными выплатами

Выплата: предрасчет [/crypto/withdraw/try]

Предрасчет выплаты [POST]

Выплата: создание [/crypto/withdraw/create]

Создание выплаты [POST]

Выплата: уведомление о финальном статусе выплаты [/crypto_withdraw/callback]

Уведомление о финальном статусе выплаты [POST]

Выплата: запрос статуса по withdraw_id [/crypto/withdraw/status]

Запрос статуса выплаты [POST]

Выплата: запрос статуса по shop_payment_id [/crypto/withdraw/shop_payment_status]

Запрос статуса выплаты [POST]

Статусы выплат [/status/crypto_withdraw]

Запрос статуса выплаты [POST]

Криптовалютный баланс магазина

Запрос криптовалютного баланса магазина [/crypto/shop_balance]

Запрос баланса магазина [POST]