crypto-invoices

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

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

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

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

Магазин делает запрос на создание и получение актуального криптовалютного адреса с указанием сети и валюты платежа (параметр payway) для перевода средств клиентом, который получает в ответе в параметре data.address.
Магазин отображает клиенту адрес с ответа полученному data.address.
Клиент совершает перевод криптовалюты в сети и валюте с параметра payway на указанный адрес data.address.
Система Qostiq отправляет мерчанту уведомления на URL для криптовалютных взаимодействий со статусом платежа. Cредства переведенные пользователем и полученные на адрес (в валюте и сети адреса), за вычетом комиссии сервиса Qostiq, зачисляются на баланс магазина.
Магазин обрабатывает уведомление и предоставляет клиенту услугу.

Внимание! Рекомендуем получать актуальный адрес перед каждым пополнением, так как ранее сформированный адрес может быть заблокирован. Платежи, которые будут совершены на заблокированный адрес не будут зачислены на баланс магазина.

Внимание! Платежи, которые не подходят под минимальную или максимальную сумму указанную в настройках платежных направлений - не будут зачислены на магазин.

Платеж: запрос создания адреса [/crypto/shop_address/create]

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

Метод: POST

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

Описание запроса

Данный запрос возвращает криптовалютный адрес (data.address) на который клиент (client) совершает перевод средств.

В параметре ответа data.cross_chains указаны все доступные блокчейны и валюты для данного адреса, в которых можно совершить платеж.

Внимание! Перевод на адрес обязательно должен быть и в валюте, и в сети указанной в параметре ответа data.cross_chains. Например, "cross_chains": {"BSC":["BNB","USDT"], "Ethereum":["USDT","ETH"]} означает что на адрес можно прислать токен USDT или валюту ETH в сети Ethereum, а также USDT или валюту BNB в сети Binance Smart Chain. Оплаты, которые были в другой валюте, или в другом блокчейне не будут зачислены на магазин.

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

{
    "client": "client@example.com",
    "now": 1655730715,
    "payway": "usdt_bep20",
    "shop_id": 6,
    "sign": "8bcbc318875fed556e78072a12b516dba00f6c5014ae13ed6c6163764c22f8cb"
}

Где,

Параметр	Описание	Формат	Пример
`client`	Клиент для которого генерируется адрес (рекомендуется использовать почту клиента)	String	"client@example.com"
`now`	время запроса, в формате unixtimestamp	Integer	1655730715
`payway`	Платежное направление	String	"usdt_bep20"
`shop_id`	идентификатор магазина в системе Qostiq	Integer	6
`sign`	подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign)	String	"214984e6277a5a2f95d9eed15d7722f427c40559b02fdb3f6399e2f845683d11"

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

{
    "data": {
        "address": "0x685f0875ea0a55fd3c355f1f9a850a644a71d626",
        "blockchain": "BSC",
        "cross_chains": {
            "BSC": ["BNB", "USDT"],
            "Ethereum": ["USDT", "ETH"],
            "Polygon": ["MATIC"]
        },
        "currency": "BNB"
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Где,

data.address – сгенерированый указанному клиенту адрес на который клиент будет провадить оплату;

data.blockchain - блокчейн в котором был создан адрес в соответсвии с "payway";

data.cross_chains - масив блокчейнов и валют для данного адреса, в которых можно совершить платеж;

data.currency - валюта в которой был создан адрес в соответсвии с "payway".

Запрос создания адреса [POST]

Request

  ```json
  {
  "client": "client@example.com",
  "shop_id": 6,
  "now": 1655730715,
  "payway": "usdt_bep20",
  "sign": "214984e6277a5a2f95d9eed15d7722f427c40559b02fdb3f6399e2f845683d11"
  }
  ```

Response 200 ()

  ```json
  {
  "data": {
      "address": "0x685f0875ea0a55fd3c355f1f9a850a644a71d626",
  "blockchain": "BSC",
  "cross_chains": {
        "BSC": [
          "BNB",
          "USDT"
        ],
        "Ethereum": [
          "USDT",
          "ETH"
        ],
        "Polygon": [
          "MATIC"
        ]
      },
  "currency": "BNB"
      },
  "error_code": 0,
  "message": "Ok",
  "result": true
  }
  ```

Платеж: уведомление после оплаты [/crypto_invoice/callback]

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

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

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

34.90.243.164
34.147.48.238
34.90.176.128
34.90.34.134
35.242.192.50

Внимание! При получении уведомления необходимо обязательно проверять: номер операции на строне Qostiq - payment_id, во избежание дублирования платежей уникальность полученного (т.к по одному платежу может быть отправлено несколько уведомлений); подпись - sign; тип операции - callback_type; статус операции - status; клиента которому принадлежит адрес оплаты - client.

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

                {
    "additional_info": {},
    "address": "0x81ededbaf330af77567d7ae71a52c8eb602140b0",
    "callback_type": "crypto_invoice",
    "client": "client@example.com",
    "client_price": "0.000200000000000000",
    "created": "2022-06-22 09:19:06",
    "description": null,
    "payment_id": 34,
    "payway": "bnb_bep20",
    "processed": "2022-06-22 09:19:16",
    "ps_currency": "BNB",
    "ps_data": {
        "ps_payer_account": "0xf8227aa7af9b5166af69581c703a4398387b2b07",
        "transaction_hash": "0x8cec449fd6ebbe34c78987a903a92a8a2e07d499d8851c22cc197d141e41c96c"
    },
    "shop_amount": "0.000200000000000000",
    "shop_currency": "BNB",
    "shop_id": 6,
    "shop_order_id": null,
    "shop_refund": "0.000194000000000000",
    "sign": "f8ec782aa4d1332532cc7ac5364ef979f593079505529d895e1f2c4a7cd0e024",
    "status": "success"
}

Где,

additional_info – дополнительные поля необходимые для создания операции по направлению;

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

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

client – клиент по которому прошла оплата. Был указан в запросе создания адреса;

client_price – сумма, которую оплатил клиент, в валюте платежной системы;

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

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

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

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

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

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

ps_data.ps_payer_account - адрес с которого была проведена оплата;

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

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

shop_currency – валюта счета;

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

shop_order_id – не используется на push платежах;

shop_refund – сумма зачисления на баланс магазина, в валюте счета;

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

sign – подпись.

Во избежание дублирования платежей, при получении коллбэка, необходимо обязательно проверять уникальность полученного payment_id, т.к по одному платежу может быть отправлено несколько уведомлений.

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

{}:0x81ededbaf330af77567d7ae71a52c8eb602140b0:crypto_invoice:client@example.com:0.000200000000000000:2022-06-22 09:19:0:34:bnb_bep20:2022-06-22 09:19:16:BNB:{}:0.000200000000000000:BNB:6:0.000194000000000000:successTestkey1

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

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

Пример уведомления после оплаты [POST]

Request

  ```json
  {
  "additional_info": "{}",
  "address": "0x81ededbaf330af77567d7ae71a52c8eb602140b0",
  "callback_type": "crypto_invoice",
  "client": "client@example.com",
  "client_price": "0.000200000000000000",
  "created": "2022-06-22 09:19:06",
  "description": null,
  "payment_id": 34,
  "payway": "bnb_bep20",
  "processed": null,
  "ps_currency": "BNB",
  "ps_data": "{"ps_payer_account": "0xf8227aa7af9b5166af69581c703a4398387b2b07", "transaction_hash": "0x8cec449fd6ebbe34c78987a903a92a8a2e07d499d8851c22cc197d141e41c96c"}",        "shop_amount": "0.000200000000000000",
  "shop_currency": "BNB",
  "shop_id": 6,
  "shop_order_id": null,
  "shop_refund": "0.000194000000000000",
  "sign": "859bccda6c4e7ed9ceebb78b40dae7d317741165aabede01d1d0e01930500ce0",
  "status": "waiting"
  }
  ```

Response 200 ()
```
  ```json
  {
  OK
  }
  ```
```

Платеж: запрос статуса [/crypto/invoice/status]

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

Метод: POST

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

Запрос позволяет узнать текущий статус платежа используя номер операции который приходит в уведомлении как параметр payment_id.

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

{
    "invoice_id": 183,
    "now": 1655802380,
    "shop_id": 6,
    "sign": "bc21703c682f0b9f53d4b554cfd55d8a25fc75c0e386fe589033aa0f49f35d07"
}

Где,

Параметр	Описание	Формат	Пример
`now`	время запроса, в формате unixtimestamp	Integer	1655802380
`invoice_id`	уникальный номер платежа в системе Qostiq, указан в коллбеке в параметре `payment_id`	Integer	183
`shop_id`	идентификатор магазина в системе Qostiq	Integer	6
`sign`	подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign)	String	"bc21703c682f0b9f53d4b554cfd55d8a25fc75c0e386fe589033aa0f49f35d07"

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

{
    "data": {
        "additional_info": {},
        "address": "0xc8717eea12a90853c854f1df77d36180ce7f99e3",
        "client": "TestClient_denisov",
        "client_price": "2.0",
        "created": "2022-07-18 07:13:06",
        "description": null,
        "payment_id": 183,
        "payway": "usdt_bep20",
        "processed": "2022-07-18 07:13:26",
        "ps_currency": "USDT",
        "ps_data": {
            "ps_payer_account": "0xf8227aa7af9b5166af69581c703a4398387b2b07",
            "refunded_address": "0xf8227AA7aF9B5166AF69581C703A4398387B2B07",
            "transaction_hash": "0x764274c5548d0ace9eaeed1a0209307a147a78f399a36deacc2857538c95be15"
        },
        "shop_amount": "2.0",
        "shop_currency": "USDT",
        "shop_id": 6,
        "shop_order_id": null,
        "shop_refund": "1.96",
        "status": 7
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Где,

additional_info – дополнительные поля необходимые для создания операции по направлению;

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

client – клиент по которому прошла оплата. Был указан в запросе создания адреса;

client_price – сумма, которую оплатил клиент, в валюте платежной системы;

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

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

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

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

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

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

ps_data.ps_payer_account - адрес с которого была проведена оплата;

ps_data.refunded_address - адрес на который выполнен возврат(в случае если платеж был возвращен);

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

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

shop_currency – валюта счета;

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

shop_order_id – не используется на push платежах;

shop_refund – сумма зачисления на баланс магазина, в валюте счета;

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

sign – подпись.

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

Пример запроса статуса [POST]

Request

      ```json
      {
      "shop_id": 6,
      "now": 1658151993,
      "invoice_id": 183,
      "sign": "bbfa4389648ee94e1e20948f73df42e25c3c657ee1b01c55fbac84fd6cb57b5d"
      }
      ```

Response 200 ()

  ```json
  {
  "data": {
  "additional_info": {},
  "address": "0xc8717eea12a90853c854f1df77d36180ce7f99e3",
  "client": "TestClient_denisov",
  "client_price": "2.0",
  "created": "2022-07-18 07:13:06",
  "description": null,
  "payment_id": 183,
    "payway": "usdt_bep20",
  "processed": "2022-07-18 07:13:26",
  "ps_currency": "USDT",
  "ps_data": {"ps_payer_account": "0xf8227aa7af9b5166af69581c703a4398387b2b07","refunded_address": "0xf8227AA7aF9B5166AF69581C703A4398387B2B07", "transaction_hash": "0x764274c5548d0ace9eaeed1a0209307a147a78f399a36deacc2857538c95be15"},
  "shop_amount": "2.0",
  "shop_currency": "USDT",
  "shop_id": 6,
  "shop_order_id": null,
  "shop_refund": "1.96",
  "status": 7
  },
  "error_code": 0,
  "message": "Ok",
  "result": true
  }
  ```

Статусы платежей [/invoice/status]

Status	Значение	Описание	Финальный?	Действие
`waiting`	1	ожидаем финальный коллбэк	Нет, нельзя предоставлять услугу	Операция создана в Qostiq, ожидайте финального статуса
`success`	2	финальный успешный статус	Да, можно предоставлять услугу	Предоставлять услугу
`rejected`	3	финальный неуспешный статус	Да, нельзя предоставлять услугу	Отменить платеж (если ранее он был создан)
`captured`	4	средства захолдированы	Нет, нельзя предоставлять услугу	Не предоставлять услугу, средства не могут быть зачислены на баланс магазина, обратитесь в службу поддержку
`risky`	5	рисковая операция, полученная оплата не прошла проверку уровня риска.	Нет, нельзя предоставлять услугу	Платеж не соответствует настройкам безопасности, необходимо выполнить возврат платежа с помощью API запроса `/crypto/invoice/refund/create`, из личного кабинета или обратиться в поддержку
`refunding`	6	платеж в процессе возврата	Нет, нельзя предоставлять услугу	Возврат в процессе выполнения
`refunded`	7	возвращён плательщику.	Да, нельзя предоставлять услугу	Платеж возвращен плательщику

Пример запроса статуса [POST]

Request

      ```json
      {
      "shop_id": 6,
      "now": 1658152321,
      "invoice_id": 201,
      "sign": "7f211766b6b0b876cc14ae40d9c29dbc70dab267c751324d3b9b9d2df379c172"
      }
      ```

Response 200 ()

  ```json
  {
   "data": {
  "additional_info": {},
  "address": "0x0f38ea28466be2a809785265a90b24bd2348b4c6",
  "client": "TestClient_denisov",
  "client_price": "2.0",
  "created": "2022-07-18 13:51:40",
  "description": null,
  "payment_id": 201,
  "payway": "usdt_bep20",
  "processed": "2022-07-18 13:51:59",
  "ps_currency": "USDT",
  "ps_data": {
      "ps_payer_account": "0xf8227aa7af9b5166af69581c703a4398387b2b07",
      "refunded_address": null,
      "transaction_hash": "0xc6d44421e029e11c8a1b7c781d050dc51b0c930df3812f56924331b6f2d4e3a2"
   },
  "shop_amount": "2.0",
  "shop_currency": "USDT",
  "shop_id": 6,
  "shop_order_id": null,
  "shop_refund": "1.96",
  "status": 2
      },
  "error_code": 0,
  "message": "Ok",
  "result": true
  }
  ```
  

Платеж: предрасчет возврата [/crypto/invoice/refund/try]

URL: https://core.qostiq.com/crypto/invoice/refund/try

Метод: POST

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

Данный запрос уточняет возможность возврата рискованного платежа и показывает сумму информацию о суммах и валюте возврата.

Возвраты выполняются на сумму полученного перевода client_price, за вычетом комиссии блокчейна за перевод.

**Внимание!

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

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

{
    "address": "0xf8227AA7aF9B5166AF69581C703A4398387B2B07",
    "invoice_id": 134,
    "now": "1657543247",
    "shop_id": 6,
    "sign": "b13a78dd63hdjdg8jn92ndndksvjhpxnwidu9293bnc729djucbe93ncb6900an"
}

Где,

Параметр	Описание	Формат	Пример
`address`	Адрес на который будет выполнятся возврат (необходимо уточнить у клиента)	String	"0xf8227AA7aF9B5166AF69581C703A4398387B2B07"
`now`	время запроса, в формате unixtimestamp	Integer	1655730715
`invoice_id`	уникальный номер платежа в системе Qostiq, указан в коллбеке в параметре `payment_id`	Integer	134
`shop_id`	идентификатор магазина в системе Qostiq	Integer	6
`sign`	подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign)	String	"b13a78dd63hdjdg8jn92ndndksvjhpxnwidu9293bnc729djucbe93ncb6900an"

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

{
    "data": {
        "blockchain": "BSC",
        "shop_currency": "BNB",
        "shop_write_off": 0.00198,
        "ps_currency": "BNB",
        "ps_refund": "0.002"
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Где,

data.blockchain – сеть в которой будет выполнен возврат;

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

data.shop_write_off - сумма списания с магазина по возврату;

data.ps_currency - валюта получения возврата;

data.ps_refund - сумма отправленная на возврат.

Предрасчет возврата [POST]

Request

  ```json
  {
      "address": "0xf8227AA7aF9B5166AF69581C703A4398387B2B07",
      "invoice_id": 134,
      "now": 1657543247,
      "shop_id": 6,
      "sign": "b13a78dd63hdjdg8jn92ndndksvjhpxnwidu9293bnc729djucbe93ncb6900an"
  }
  ```

Response 200 ()

  ```json
  {
    "data": {
      "blockchain": "BSC",
      "ps_currency": "BNB",
      "ps_refund": "0.002",
      "shop_currency": "BNB",
      "shop_write_off": "0.00198"
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
  }
  ```

Платеж: создание возврата [/crypto/invoice/refund/create]

URL: https://core.qostiq.com/crypto/invoice/refund/create

Метод: POST

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

Возвраты выполняются на сумму полученного перевода client_price, за вычетом комиссии блокчейна за перевод.

**Внимание!

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

{
    "address": "0xf8227AA7aF9B5166AF69581C703A4398387B2B07",
    "invoice_id": 134,
    "now": "1657543247",
    "shop_id": 6,
    "sign": "b13a78dd63hdjdg8jn92ndndksvjhpxnwidu9293bnc729djucbe93ncb6900an"
}

Где,

Параметр	Описание	Формат	Пример
`address`	Адрес на который будет выполнятся возврат (необходимо уточнить у клиента)	String	"0xf8227AA7aF9B5166AF69581C703A4398387B2B07"
`now`	время запроса, в формате unixtimestamp	Integer	1655730715
`invoice_id`	уникальный номер платежа в системе Qostiq, указан в коллбеке в параметре `payment_id`	Integer	134
`shop_id`	идентификатор магазина в системе Qostiq	Integer	6
`sign`	подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign)	String	"b13a78dd63hdjdg8jn92ndndksvjhpxnwidu9293bnc729djucbe93ncb6900an"

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

{
    "data": {
        "Id": "41",
        "blockchain": "BSC",
        "shop_currency": "BNB",
        "shop_write_off": 0.00198,
        "ps_currency": "BNB",
        "ps_refund": "0.002"
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Возврат считается созданым если в ответ на запрос создания возврата был получен уникальный номер возврата data.id.

Где,

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

data.blockchain – сеть в которой будет выполнен возврат;

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

data.shop_write_off - сумма списания с магазина по возврату;

data.ps_currency - валюта получения возврата;

data.ps_refund - сумма отправленная на возврат.

Создание возврата [POST]

Request

  ```json
  {
      "address": "0xf8227AA7aF9B5166AF69581C703A4398387B2B07",
      "invoice_id": 134,
      "now": 1657543247,
      "shop_id": 6,
      "sign": "b13a78dd63hdjdg8jn92ndndksvjhpxnwidu9293bnc729djucbe93ncb6900an"
  }
  ```

Response 200 ()

  ```json
  {
    "data": {
      "blockchain": "BSC",           
      "id": "41",
      "ps_currency": "BNB",
      "ps_refund": "0.002",
      "shop_currency": "BNB",
      "shop_write_off": "0.00198"
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
  }
  ```

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

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

Платеж: запрос создания адреса [/crypto/shop_address/create]​

Описание запроса​

Запрос создания адреса [POST]​

Платеж: уведомление после оплаты [/crypto_invoice/callback]​

Пример уведомления после оплаты [POST]​

Платеж: запрос статуса [/crypto/invoice/status]​

Пример запроса статуса [POST]​

Статусы платежей [/invoice/status]​

Пример запроса статуса [POST]​

Платеж: предрасчет возврата [/crypto/invoice/refund/try]​

Предрасчет возврата [POST]​

Платеж: создание возврата [/crypto/invoice/refund/create]​

Создание возврата [POST]​

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

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

Платеж: запрос создания адреса [/crypto/shop_address/create]

Описание запроса

Запрос создания адреса [POST]

Платеж: уведомление после оплаты [/crypto_invoice/callback]

Пример уведомления после оплаты [POST]

Платеж: запрос статуса [/crypto/invoice/status]

Пример запроса статуса [POST]

Статусы платежей [/invoice/status]

Пример запроса статуса [POST]

Платеж: предрасчет возврата [/crypto/invoice/refund/try]

Предрасчет возврата [POST]

Платеж: создание возврата [/crypto/invoice/refund/create]

Создание возврата [POST]