FORMAT: 1A HOST: https://core.qostiq.com/

API Qostiq (RU)

История изменений API:

Версия	Дата	Тип изменения	Описание	Автор
`1.0.0`	2025-06-26	Added	Добавлена обработка динамического изменения сумм через параметры `overwrite_amount` и `is_overwritten`	@dev_team
`1.0.1`	2025-07-07	Fixed	Исправлена ссылка для высставления счетов для оплаты через Pay	@tech_writter
`1.0.2`	2025-07-22	Added	Добавлено пояснение о необходимости формирования HTML-страницы на стороне мерчанта для корректного перехода	@tech_writter
`1.0.3`	2025-12-18	Fixed	Исправлено описание, которое закрывает проблему неправильной интерпретации redirect_url	@tech_writter

Условные обозначения:

Added - Новый функционал

Changed - Изменения в существующем API

Fixed - Исправления ошибок ##Начало работы с API Взаимодействие по API осуществляется с помощью POST запросов в кодировке

UTF-8 на URL https://core.qostiq.com/&lt;метод API>

Сервис принимает json запросы, при отправке указывать заголовок "Content-Type: application/json". Все запросы к Qostiq подписываются секретным ключом из настроек магазина.

Для каждого метода свой набор обязательных параметров, также могут передаваться дополнительные параметры, но в формировании подписи они не участвуют. р Все ответы сервиса Qostiq содержат атрибуты result, message, data, error.

Если result == true и error_code == 0, то поле data содержит специфичные для каждого запроса данные. Если result == false, то error != 0 - запрос был обработан с ошибкой, data = None, поле message содержит описание ошибки, так же по коду ошибки (error) можно узнать детальную информацию.

Для начала работы с сервисом Qostiq по API, необходимо зарегистрировать аккаунт

https://business.qostiq.com/auth/register

и создать магазин

https://business.qostiq.com/shops/create

, от имени которого будут отправляться запросы.

Внимание! Каждый магазин имеет свой собственный баланс в каждой валюте и никак не связан с балансом персонального кошелька.

Создание магазина

При создании магазина укажите

Название магазина – название будет отображаться пользователям при оплате

URL магазина – реальный, рабочий сайт магазина для пользователей

URL уведомлений – адрес на который будет отправляться уведомление об успешной оплате

URL rejected уведомлений – адрес на который будет отправляться уведомление об отклоненной оплате

Success URL – адрес на который будет перенаправлен пользователь после успешной оплаты

Fail URL – адрес на который будет перенаправлен пользователь после не успешной оплаты

URL уведомлений по крипто платежам – адрес на который будет отправляться уведомление о cмене статуса криптовалютного платежа.

URL уведомлений по крипто выплатам – адрес на который будет отправляться уведомление о cмене статуса криптовалютного платежа.

Проверка уникальности платежей – если флаг установлен, то все номера платежей магазина должны быть уникальными (проверка от дублирования)

Подтверждение домена

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

В личном кабинете, в разделе "Магазины" будет отображено "Статус: Новый Подтвердите магазин, чтобы подключить методы оплаты". Необходимо перейти по ссылке "Подтвердите магазин" и выполнить следующие действия

1. Скачать файл. Формат файла qostiq_0123.txt где 0123 - номер магазина в нашей системе.

2. Разместить этот файл в корне сайта (на сервере или хостинге). Пример:

http://mywebsite.com/qostiq_0123.txt

3. Нажмите "Подтвердить"

Если все прошло успешно - сайт отправлен на проверку. Для уточнения деталей можно обращаться в нашу службу поддержки.

Если файл был добавлен не корректно, или настройки среды (хостинг\сервер) не позволяют прочитать файл - будет отображено сообщение "К сожалению, мы не смогли подтвердить Ваш магазин" В данном случае необходимо выполнить рекомендации в сообщении, или связаться со службой поддержки.

Настройка безопасности

Раздел безопасность в личном кабинете содержит настройки вашего секретного ключа и список разрешенных IP адресов.

Secret Key:

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

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

IP White List:

Вы можете указать IP адреса Ваших сервисов, с которых будут отправляться запросы по API. IP адреса указываются в формате вида 192.168.0.1

Внимание! Вы не сможете отправлять запросы с других IP адресов

Правила формирования подписи

Sign: Строка формируется следующим образом: все обязательные параметры запроса упорядочиваются в алфавитном порядке ключей, значения конкатенируются через знак двоеточие (“:”), в конце добавляется секретный ключ (без знака ":"), от полученной строки генерируется sha256 хеш и его HEX-представление передается в параметре запроса sign.

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

Пример формирования подписи для запроса invoice.

Обязательные параметры запроса:

"currency": "980",

"payway": "card_uah",

"amount": "12.34",

"shop_id": 5,

"shop_order_id": 4126

Секретный ключ магазина (из настроек магазина):

secret = “SecretKey01”

Упорядоченные ключи:

'amount', 'currency', 'payway', 'shop_id', 'shop_order_id'

Строка для генерации sha256 хеша имеет вид:

12.34:980:card_uah:5:4126SecretKey01

HEX-представление хеша:

4c2608a8638c0650d54dd4809bd69ab50d1a1cd55f2e13366b68d43caee34104

Пример формирования подписи для запроса invoice

{
:
:
:
:
:
:
:

Для онлайн проверки можно использовать онлайн сервис

http://www.xorbin.com/tools/sha256-hash-calculator

Работа через страницу оплаты PAY

Общая информация по PAY

PAY - страница с интерфейсом для приема платежей через Интернет. Данный ресурс позволяет, независимо от способа оплаты, единообразно взаимодействовать с клиентом. Предоставляет выбор удобных клиенту методов и валюты для оплаты, и, при необходимости, дает возможность указать дополнительную информацию о плательщике (например, номер телефона, при оплате через мобильную коммерцию).

Выбор валюты и указание дополнительной информации для оплаты.

Если валюта выставленного счета не совпадает с валютой платежного направления, то PAY автоматически производит конвертацию суммы. Таким образом, магазин получит средства по выставленному счету в валюты счета, а клиент оплатит той валютой, которая для него удобна в настоящий момент.

Выставление счета для оплаты через PAY

Для перенаправления плательщика на страницу оплаты, необходимо сформировать и подтвердить HTML-форму.

URL:

https://pay1.qostiq.com/ru/pay

Метод: POST, GET

Обязательные параметры: amount, currency, shop_id, shop_order_id, sign

Пример формирования подписи для запроса:

keys_sorted = ['amount', 'currency', 'shop_id', 'shop_order_id']

Строка для генерации sha256 хеша имеет вид:

10.00:980:1:101SecretKey01

HEX-представление хеша:

sign = 7354edb970dae3b496572252d7d7578fc8e0f1061b2e69a9eda1b39f3cdadc69

Пример HTML-формы:

form name="Pay" method="post" action=" https://pay.qostiq.com/ru/pay" accept-charset="UTF-8 input type="hidden" name="amount" value="10.00" input type="hidden" name="currency" value="980" input type="hidden" name="shop_id" value="1" input type="hidden" name="sign" value="7354edb970dae3b496572252d7d7578fc8e0f1061b2e69a9eda1b39f3cdadc69" input type="hidden" name="shop_order_id" value="101" input type="submit" input type="hidden" name="description" value="Test invoice" /form

Где,

Параметр	Описание	Формат	Пример
`shop_id`	идентификатор магазина в системе Qostiq	Integer	5
`amount`	сумма выставленного счета	Number (Не больше 2х знаков после точки)	1, 1.0, 1.00 или "1.00"
`currency`	валюта выставленного счета	Integer	840 - Доллар США, 980 - Украинская гривна, 978 - Евро
`description`	описание к выставленному счету	String	"test payment"
`shop_order_id`	номер счета на стороне магазина. В зависимости от настроек магазина, может проверяться на уникальность	String	"h8fj38dkh-hf8k-4f8d-9c8c-jd8dh38dksn92"
`sign`	подпись, см. п. Правила формирования подписи (sign)	String	"a7f5bcbb774cea9d9886cbb3ce2f8731359e356a7d759437b4e9e31da1152109"

Так же, платежная форма может содержать дополнительные параметры, которые не участвуют в формировании подписи, но влияют на вид страницы для оплаты PAY.

Параметр	Описание	Формат	Пример
`payway`	платежное направление, через которое необходимо оплатить выставленный счет,	String	"card_uah" (указан в личном кабинете)
`payer_account`	email или номер кошелька аккаунта плательщика в системе Qostiq, если передается в запросе, то счет может оплатить только данный аккаунт. Только для оплаты с кошелька Qostiq.	String	"support@qostiq.com" или "201494711279"
`failed_url`	URL, на который будет перенаправлен плательщик, после не успешной оплаты счета,	String	"https://qostiq.com/failed"
`success_url`	URL, на который будет перенаправлен плательщик, после успешной оплаты счета	String	"https://qostiq.com/success"

Важно! Success URL, Fail URL, указанные в настройках магазина, имееют приоритет выше переданных в запросе, поэтому необходимо удалить их из настроек магазина.

Общая информация по странице PAY (Crypto)

PAY - страница с интерфейсом для приема криптовалютных платежей которая предоставляет выбор удобного клиенту блокчейна оплаты и отображение клиенту адреса на который клиент может совершить платеж.

Выставление счета для оплаты через PAY страницу (Crypto)

Для перенаправления плательщика на страницу оплаты, необходимо сформировать и подтвердить HTML-форму.

URL (en):

https://pay.qostiq.com/en/crypto/pay

URL (pl):

https://pay.qostiq.com/pl/crypto/pay

URL (uk):

https://pay.qostiq.com/uk/crypto/pay

URL (ru):

https://pay.qostiq.com/ru/crypto/pay

Метод: POST, GET

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

Пример формирования подписи для запроса:

keys_sorted = ['client', 'shop_id']

Строка для генерации sha256 хеша имеет вид:

testclient:6SecretKey01

HEX-представление хеша:

sign = 0f5816c558d1150f76cf77694a80b50234b00fd26137dd1a3fbee168bfd9f7dc

Пример URL запроса [GET]:

https://pay.qostiq.com/ru/crypto/pay?client=testclient&paymethod_id=1&shop_id=6&sign=0f5816c558d1150f76cf77694a80b50234b00fd26137dd1a3fbee168bfd9f7dc&email=client@example.com&return_url=https://shop.com/crypto_return_url

Пример HTML-формы [POST]:

Где,

Параметр	Описание	Формат	Обязательный	Пример
`client`	Клиент для которого генерируется адрес	String	Да	"testclient"
`paymethod_id`	Платежный метод (валюта оплаты и зачисления на магазин, при использовании данного параметра клиент самостоятельно выберет блокчейн оплаты)	String	*Опционально	1
`payway`	Платежное направление (включает валюту и блокчейн оплаты)	String	*Опционально	"usdt_bep20"
`shop_id`	идентификатор магазина в системе Qostiq	Integer	Да	6
`sign`	подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign)	String	Да	"0f5816c558d1150f76cf77694a80b50234b00fd26137dd1a3fbee168bfd9f7dc"
`email`	Почта клиента	String	Нет	"client@example.com"
`return_url`	URL на который клиент сможет вернуться со страницы оплаты по нажатию на кнопку "Вернуться в магазин"	String	Нет	"https://shop.com/crypto_return_url"

*Для запроса обязателен один из параметров paymethod_id или payway. При использовании параметра paymethod_id клиенту будет доступен выбор блокчейна (сети) оплаты; при использовании payway у клиента не будет возможности выбора сети, клиент будет направлен на страницу с указанием адреса для оплаты.

Доступные значения paymethod_id:

Значение `paymethod_id`	Валюта
`1`	USDT
`2`	BNB
`3`	ETH
`4`	BTC
`5`	TRX
`6`	BUSD
`7`	LTC
`8`	MATIC

Логотипы Qostiq

В архиве находятся логотипы в форматах .png и .svg

Group Операции с кошельком Qostiq

Выставление счетов Bill [/bill/create]

Bill - Этот метод позволяет выставлять счета для оплаты при помощи кошельков Qostiq wallet.

URL: https://core.qostiq.com/bill/create

Метод: POST

Обязательные параметры: shop_amount, shop_currency, shop_id, shop_order_id, payer_currency

Уникальность shop_order_id проверяется в зависимости от настроек магазина, рекомендуем включить данную функцию и передавать уникальное значение для вашего магазина, для избежание дублированного выставления счетов на оплату.

В запросе могут передаваться дополнительные параметры, например, description – описание счета, или payer_account – email/номер кошелька аккаунта плательщика в системе Qostiq

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

{
:
,
:
,
:
,
:
,
:
,
:
,
:

Параметр	Описание	Формат	Пример
`shop_id`	идентификатор магазина в системе Qostiq	Integer	5
`shop_amount`	сумма выставленного счета	Number (Не больше 2х знаков после точки)	1, 1.0, 1.00 или "1.00"
`shop_currency`	валюта выставленного счета (зачисления на магазин)	Integer	980 - Украинская гривна, 840 - Доллар США, 978 - Евро
`payer_currency`	валюта оплаты плетельщиком (валюта списания с плательщика в системе Qostiq, может отличаться от валюты магазина)	Integer	980 - Украинская гривна, 840 - Доллар США, 978 - Евро
`sign`	подпись	String	"a7f5bcbb774cea9d9886cbb3ce2f8731359e356a7d759437b4e9e31da1152109"
`shop_order_id`	номер счета на стороне магазина, формат	String	"h8fj38dkh-hf8k-4f8d-9c8c-jd8dh38dksn92"
`description`	описание выставленного счета (не обязательный параметр)	String	"test bill"
`payer_account`	email или номер счета плательщика на стороне платежной системы Qostiq (не обязательный параметр),	String или integer	"support@qostiq.com" или 201494711279

Так же, в запросе можно передавать дополнительные параметры, в формировании подписи они не участвуют.

Параметр	Описание	Формат	Пример
`failed_url`	URL, на который будет перенаправлен плательщик, после не успешной оплаты счета,	String	"https://qostiq.com/failed"
`success_url`	URL, на который будет перенаправлен плательщик, после успешной оплаты счета	String	"https://qostiq.com/success"
`callback_url`	URL адрес на который будет отправляться уведомление об успешной оплате	String	"https://qostiq.com/callback_url_kvt"
`callback_rejected_url`	URL адрес на который будет отправляться уведомление о неуспешной оплате	String	"https://qostiq.com/callback_rejected_url_kvt"
`lifetime`	время действия счета для оплаты, в минутах	String	"43200"

Важно! Success URL, Fail URL, URL уведомлений, URL Reject уведомлений указанные в настройках магазина, имееют приоритет выше переданных в запросе, поэтому необходимо удалить их из настроек магазина.

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

{
`"data"`:` {`
:
,
:
,
:
,
:
,
:
,
:
,
:
,
:
,
:
,
:
,
:
,
:
`}`,
:
,
:
,
:

Где,

data – информация по созданному счеты для оплаты

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

lifetime – время действия счета для оплаты, в минутах, по умолчанию: 43200 минут

payer_account – аккаунт плательщика, которому выставлен счет для оплаты (если передавался в запросе)

payer_currency – валюта, в которой должен оплатить счет плательщик

payer_price – сумма, которую должен оплатить плательщик для погашения счета

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

shop_amount – сумма счета, переданная магазином

shop_id – идентификатор магазина

shop_order_id – номер счета на стороне магазина

url – URL на который можно перенаправить пользователя для оплаты счета.

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

Пример ошибки при выставлении счета:

{
:
,
:
,
:
,
:

Где

message – описание ошибки;

error_code

– код ошибки

Выставить счет Qostiq [POST]

Request (application/json)

  ```json
  { 
      "description": "Test Bill", 
      "payer_currency": 980, 
      "shop_amount": "23.15", 
      "shop_currency": 980, 
      "shop_id": "112", 
      "shop_order_id": 4239, 
      "sign": "ad7fbe8df102bc70e28deddba8b45bb3f4e6cafdaa69ad1ecc0e8b1d4e770575" 
  }
  ```

Response 200 ()

  ```json
  { 
      "data":             
      {   
          "created": "Wed, 06 Dec 2017 14:35:43 GMT",
          "id": 26, 
          "lifetime": 43200, 
          "payer_account": null, 
          "payer_currency": 980, 
          "payer_price": 23.15, 
          "shop_amount": 23.15, 
          "shop_currency": 980, 
          "shop_id": 3, 
          "shop_order_id": 4239, 
          "url": https://wallet.qostiq.com/ru/bill/pay/kdrNIrMtuhb 
      } 
          "error_code": 0, 
          "message": "Ok", 
          "result": true 
  }
  ```
  

Выставление счетов Bill v.2 с возможностью оплаты на свободную сумму [/bill/create/v2]

Bill v.2 - новый метод позволяет выставлять счета для оплаты при помощи кошельков Qostiq wallet в 2х вариантах:

на фиксированную сумму - вы определяете сколько клиент должен заплатить за ваши услуги (если передан amount);
на свободную сумму - вы оставляете за клиентом право указывать сумму которая будет зачислена на магазин (если не передан amount).

URL: https://core.qostiq.com/bill/create/v2

Метод: POST

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

В запросе могут передаваться дополнительные параметры, например, description – описание счета, или email – email кошелька плательщика в системе Qostiq

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

{
:
,
:
,
:
,
:
,
:

Параметр	Описание	Формат	Пример
`shop_id`	идентификатор магазина в системе Qostiq	Integer	6
`currency`	валюта выставленного счета (зачисления на магазин)	Integer	980 - Украинская гривна, 840 - Доллар США, 978 - Евро
`now`	время запроса в формате timestamp	Integer	1687520474
`sign`	подпись	String	"771952b72a0869945d62373b46a79feabc5a674b34cf78de5dc7c4c36981cf87"
`shop_order_id`	номер счета на стороне магазина, формат	String	"dc5a286e-6c5e-43e8-8c68-926fa15d09ec"

Так же, в запросе можно передавать дополнительные параметры, в формировании подписи они не участвуют.

Параметр	Описание	Формат	Пример
`amount`	сумма выставленного счета, при использовании данного параметра клиент не будет иметь возможность сменить сумму оплаты	Number (Не больше 2х знаков после точки)	1, 1.0, 1.00 или "1.00"
`email`	email кошелька плательщика в системе Qostiq	String	"example@mail.com"
`failed_url`	URL, на который будет перенаправлен плательщик, после не успешной оплаты счета,	String	"https://qostiq.com/failed"
`success_url`	URL, на который будет перенаправлен плательщик, после успешной оплаты счета	String	"https://qostiq.com/success"
`callback_url`	URL адрес на который будет отправляться уведомление об успешной оплате	String	"https://qostiq.com/callback_url_kvt"
`callback_rejected_url`	URL адрес на который будет отправляться уведомление о неуспешной оплате	String	"https://qostiq.com/callback_rejected_url_kvt"
`lifetime`	время действия счета для оплаты, в минутах (90 по умолчанию)	String	"43200"
`lang`	язык страницы оплаты (доступны английский "en", польский - "pl", русский - "ru", украинский - "uk")	String	"en"

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

{
`"data"`:` {`
:
,
:
,
:
,
:
,
:
,
:
,
:
,
:
,
:
,
:
,
:
,
:
`}`,
:
,
:
,
:

Где,

data – информация по созданному счеты для оплаты

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

lifetime – время действия счета для оплаты, в минутах, по умолчанию: 43200 минут

payer_account – аккаунт плательщика, которому выставлен счет для оплаты (если передавался в запросе)

payer_currency – валюта, в которой должен оплатить счет плательщик

payer_price – сумма, которую должен оплатить плательщик для погашения счета

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

shop_amount – сумма счета, переданная магазином

shop_id – идентификатор магазина

shop_order_id – номер счета на стороне магазина

url – URL на который можно перенаправить пользователя для оплаты счета.

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

Пример ошибки при выставлении счета:

{
:
,
:
,
:
,
:

Где

message – описание ошибки;

error_code

– код ошибки

Выставить счет Qostiq [POST]

Request (application/json)

  ```json
  {
  "currency": 840,
  "shop_id": 6,
  "now": 1687520474,
   "shop_order_id": "dc5a286e-6c5e-43e8-8c68-926fa15d09ec",
  "sign": "771952b72a0869945d62373b46a79feabc5a674b34cf78de5dc7c4c36981cf87"
  }
  ```

Response 200 ()

  ```json
  {
  "data": {
      "created": "Fri, 23 Jun 2023 11:44:50 GMT",
      "id": 1914,
      "lifetime": 90,
      "payer_account": null,
      "payer_currency": 840,
      "payer_price": null,
      "shop_amount": null,
      "shop_currency": 840,
      "shop_id": 6,
      "shop_order_id": "dc5a286e-6c5e-43e8-8c68-926fa15d09ec",
      "shop_refund": null,
      "url": "https://wallet.test-qostiq.com/ru/bill/pay/ba534fbd7bad42e09c47ce70c06b4886"
      },
  "error_code": 0,
  "message": "Ok",
  "result": true
  }
  ```

Запрос статуса Bill [/bill/shop_order_status]

Этот метод позволяет узнать текущий статус платежа совершенного при помощи кошелька Qostiq wallet.

URL:

https://core.qostiq.com/bill/shop_order_status

Метод: POST

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

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

{
:
,
:
,
:
,
:

Параметр	Описание	Формат	Пример
`now`	время запроса	String	"2021-05-01 16:56:25.009469"
`shop_id`	идентификатор магазина в системе Qostiq	Integer	1092
`shop_order_id`	номер счета на стороне Вашего сервиса	String	"234234232323"
`sign`	подпись	String	"b9b838e0b1baedcf7dd60711b1afab246c3496b5cc3433df0c5a2e2d07fea976"

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

  <li>  &#123;
    <li>   ` "data"`:` { ` </li>
    <li>   <ul>     "client_price"</ul>:<ul> 1.16</ul>, </li>
    <li>   <ul>     "created"</ul>: <ul>"2020-10-20 14:01:28"</ul>, </li>
    <li>   <ul>     "description"</ul>:<ul> ""</ul>, </li>
    <li>   <ul>     "is_unique"</ul>:<ul> true</ul>, </li>
    <li>   <ul>     "payment_id"</ul>: <ul>852095</ul>, </li>
    <li>   <ul>     "payway"</ul>: <ul>"qostiq_usd"</ul>, </li>
    <li>   <ul>     "processed"</ul>: <ul>2020-10-20 14:01:33</ul>, </li>
    <li>   <ul>     "ps_currency"</ul>: <ul>980</ul>, </li>
    <li>   `     "ps_data"`: <ul>&#123;
  "ps_payer_account": "201538122124"
&#125;</ul>, </li>
    <li>   <ul>     "shop_amount"</ul>:<ul> 1.1</ul>, </li>
    <li>   <ul>     "shop_currency"</ul>: <ul>980</ul>, </li>
    <li>   <ul>     "shop_id"</ul>:<ul> 1092</ul>, </li>
    <li>   <ul>     "shop_order_id"</ul>:<ul> "234234232323"</ul>, </li>
    <li>   <ul>     "shop_refund"</ul>: <ul>1.1</ul>, </li>
    <li>   <ul>     "status"</ul>:<ul> 2</ul></li>
    <li>   `         },` </li>
    <li>   <ul> "error_code"</ul>:<ul> 0</ul>, </li>
    <li>   <ul> "message"</ul>:<ul> "Ok"</ul>, </li>
    <li>   <ul> "result"</ul>:<ul> true </ul> </li>
    &#125; </li>

Где,

client_price – сумма платежа;

created – дата создания;

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

is_unique – уникальность номера платежа;

payment_id – идентификатор платежа на стороне Qostiq;

payway – платежное направление;

processed – дата проведения платежа;

ps_currency – валюта выставленного счета;

ps_data – дополнительная информация от платежной системы, например аккаунт плательщика;

shop_amount – сумма счета, переданная магазином;

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

shop_id – идентификатор магазина в системе Qostiq;

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

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

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

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

Request (application/json)

  ```json
  { 
      "now": "2021-05-01 16:56:25.009469", 
      "shop_id": "1092", 
      "shop_order_id": "234234232323",
      "sign": "ad7fbe8df102bc70e28deddba8b45bb3f4e6cafdaa69ad1ecc0e8b1d4e770575" 
  } 
  ```

Response 200 ()

  ```json
  {
    "data": {
      "client_price": 1.16, 
      "created": "2020-10-20 14:01:28", 
      "description": "", 
      "is_unique": true, 
      "payment_id": 852095, 
      "payway": "qostiq_usd", 
      "processed": "2020-10-20 14:01:33", 
      "ps_currency": 980, 
      "ps_data": {
        "ps_payer_account": "201538122124"
      }, 
      "shop_amount": 1.1, 
      "shop_currency": 980, 
      "shop_id": 1092, 
      "shop_order_id": "234234232323", 
      "shop_refund": 1.1, 
      "status": 2
    }, 
    "error_code": 0, 
    "message": "Ok", 
    "result": true
  }
  ```
  

Статус операций Bill [/bill/status]

Status	Значение	Описание	Финальный?
1	`Waiting`	Платеж находится в стадии ожидания действий пользователя	Нет
2	`Paid`	Платеж оплачен клиентом	Да
3	`Canceled`	Платеж отменен клиентом	Да
4	`Expired`	Истёк срок жизни счёта	Да

Запрос статуса Bill при неуникальном shop_order_id [POST]

Request (application/json)

  ```json
  { 
      "now": "2021-05-01 16:56:25.009469", 
      "shop_id": "112", 
      "shop_order_id": "123billtest", 
      "sign": "6fb934f7e00d205cb5ebb62117d9b74029d84c2ffc7c87fe5b38ac5196fecf02" 
  } 
  ```

Response 200 ()

  ```json
  {
    "data": {
      "client_price": 1.0, 
      "created": "2021-06-09 13:47:05", 
      "description": "", 
      "is_unique": false, 
      "payment_id": 19732961, 
      "payway": "qostiq_usd", 
      "processed": null, 
      "ps_currency": 980, 
      "ps_data": {
        "ps_payer_account": "201538122124"
      }, 
      "shop_amount": 1.0, 
      "shop_currency": 980, 
      "shop_id": 1092, 
      "shop_order_id": "123billtest", 
      "shop_refund": 0.93, 
      "status": 4
    }, 
    "error_code": 0, 
    "message": "Ok", 
    "result": true
  }
  ```

Предварительный расчет выплаты на кошелек: Transfer [/transfer/try]

Transfer/try. Данный метод не является обязательным для создания выплаты на кошелек. Возвращает дополнительную информацию для создания transfer и предварительный расчет по комиссиям и конвертации.

URL:

https://core.qostiq.com/transfer/try

Метод: POST

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

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

{
:
,
:
,
:
,
:
,
:
,
:

Где,

Параметр	Описание	Формат	Пример
`amount`	сумма получения или списания (зависит от amount_type)	Number (Не больше 2х знаков после точки)	1.00 или 1
`amount_type`	указывает на тип суммы, возможны значения: receive_amount – сумма к получению на аккаунт, writeoff_amount - сумма к списанию с баланса магазина	String	"receive_amount" или "writeoff_amount"
`payee_currency`	валюта получения на аккаунт в Qostiq	Integer	980 - Украинская гривна, 840 - Доллар США, 978 - Евро, 398 - Казахстанский Тенге
`shop_currency`	валюта списания с магазина,	Integer	980 - Украинская гривна, 840 - Доллар США, 978 - Евро, 398 - Казахстанский Тенге
`shop_id`	идентификатор магазина, с которого осуществляется выплата	Integer	5
`sign`	подпись запроса	String	"cea33ec0eeeef9866b01d51c7bbe55b4-d3c3f2e18f681d7629940b816ff35a2b"

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

{
`"data"`:` {`
` "account_info_config"`:` {`
` "info"`: `{}`,
:
,
:
,
:
,
:
`}`,
:
,
:
,
:

Где,

account_info_config.payee_account – информация об аккаунте, в том числе регулярное выражение, которому должен соответствовать аккаунт;

payee_amount – сумма к получению на счет в валюте payee_currency;

payee_currency – валюта получения на счет суммы payee_amount;

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

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

Предварительный расчет выплаты [POST]

для демонстрации запроса в правом окне смените Production на Mock Server

Request (application/json)

  ```json
  {
  "amount": "1.11",
  "amount_type": "receive_amount",
  "payee_currency": "978",
  "shop_currency": "840",
  "shop_id": "6",
  "sign": "cea33ec0eeeef9866b01d51c7bbe55b4d3c3f2e18f681d7629940b816ff35a2b"
  }
  ```
  

Response 200 ()
```
  ```json
  {
```
"data": { "account_info_config": { "payee_account": { "comment": { "en": "Enter Wallet Number or Email", "ru": "Введите номер кошелька или email" }, "example": "31557414711", "label": { "en": "Wallet Number or Email", "ru": "Номер кошелька или email" }, "regex": "^3[\d]{10}$|^([a-zA-Z0-9_-]+\.)[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)\.[a-zA-Z]{2,6}$" } }, "info": {}, "payee_amount": 1.11, "payee_currency": "978", "shop_currency": "840", "write_off_amount": 1.19 }, "error_code": 0, "message": "Ok", "result": true } ```

Вывод средств на кошелек: Transfer [/transfer/create]

Transfer - Операция Transfers используется для вывода средств с магазина на персональный аккаунт пользователя в валюте Qostiq.

URL: https://core.qostiq.com/transfer/create

Метод: POST

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

Shop_payment_id должен быть уникальным для каждого нового перевода.

В запросе могут передаваться дополнительные параметры, например, description – описание выплаты.

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

{
:
,
:
,
:
,
:
,
:
,
:
,
:
,
:

Где,

Параметр	Описание	Формат	Пример
`payee_account`	аккаунт получателя средств в системе Qostiq, может быть передан как номер кошелька, так и email пользователя	String	"201487668051" или "qostiq@qostiq.com";
`amount`	сумма получения или списания (зависит от amount_type)	Number (Не больше 2х знаков после точки)	1.00 или 1
`amount_type`	указывает на тип суммы, возможны значения: receive_amount – сумма к получению на аккаунт, writeoff_amount - сумма к списанию с баланса магазина	String	"receive_amount" или "writeoff_amount"
`payee_currency`	валюта получения на аккаунт в Qostiq	Integer	980 - Украинская гривна, 840 - Доллар США, 978 - Евро, 398 - Казахстанский Тенге
`shop_currency`	валюта списания с магазина,	Integer	840 - Доллар США, 978 - Евро, 980 - Украинская гривна, 398 - Казахстанский Тенге
`shop_id`	идентификатор магазина, с которого осуществляется выплата	Integer	5
`shop_payment_id`	уникальный идентификатор платежа на стороне магазина	String	"h8fj38dkh-hf8k-4f8d-9c8c-jd8dh38dksn92"

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

{
`"data"`:` {`
:
,
:
,
:
,
:
,
:
,
:
,
:
,
:
`}`,
:
,
:
,
:

Где,

balance – баланс магазина, после успешного создания перевода;

id – уникальный идентификатор перевода на стороне Qostiq;

payee_amount – сумма к получению на счет в валюте payee_currency;

payee_currency – валюта получения на счет суммы payee_amount;

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

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

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

Внимание! У перевода отсутствует статус, т.к. если он создался и в ответе вернулся ID перевода, то перевод считается успешно проведенным, дополнительных запросов не требуется.

Перевести средства с баланса магазина [POST]

для демонстрации запроса в правом окне смените Production на Mock Server

Request (application/json)

  ```json
  {
      "amount": 10,
      "amount_type": "receive_amount",
      "payee_account": "201497141132",
      "payee_currency": 980,
      "shop_currency": 980,
      "shop_id": 112,
      "shop_payment_id": "55ac443d-958b-40e3-8956-e04e72561324",
      "sign": "cd30ba2b6e29f508edf40582e17a9a602a43be9b527238b1b0a6777e226381f4"
  }
  ```
  

Response 200 ()

  ```json
  {
      "data": {
          "balance": 88.91,
          "id": 12,
          "payee_account": 201497141132,
          "payee_amount": 10,
          "payee_currency": 980,
          "shop": 112,
          "shop_currency": 980,
          "write_off_amount": 10
      },
      "error_code": 0,
      "message": "Ok",
      "result": true
  }
  ```

Вывод средств на кошелек: Transfer [/transfer/create]

URL: https://core.qostiq.com/transfer/create

Метод: POST

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

Shop_payment_id должен быть уникальным для каждого нового перевода.

В запросе могут передаваться дополнительные параметры, например, description – описание выплаты.

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

{
:
,
:
,
:
,
:
,
:
,
:
,
:
,
:

Где,

Параметр	Описание	Формат	Пример
`payee_account`	аккаунт получателя средств в системе Qostiq, может быть передан как номер кошелька, так и email пользователя	String или integer	201487668051 или "qostiq@qostiq.com";
`amount`	сумма получения или списания (зависит от amount_type)	Number (Не больше 2х знаков после точки)	1, 1.0, 1.00 или "1.00"
`amount_type`	указывает на тип суммы, возможны значения: receive_amount – сумма к получению на аккаунт, writeoff_amount - сумма к списанию с баланса магазина	String	"receive_amount" или "writeoff_amount"
`payee_currency`	валюта получения на аккаунт в Qostiq	Integer	980 - Украинская гривна, 840 - Доллар США, 978 - Евро, 398 - Казахстанский Тенге
`shop_currency`	валюта списания с магазина,	Integer	980 - Украинская гривна, 840 - Доллар США, 978 - Евро
`shop_id`	идентификатор магазина, с которого осуществляется выплата	Integer	5
`shop_payment_id`	уникальный идентификатор платежа на стороне магазина	String	"h8fj38dkh-hf8k-4f8d-9c8c-jd8dh38dksn92"

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

{
`"data"`:` {`
:
,
:
,
:
,
:
,
:
,
:
,
:
,
:
`}`,
:
,
:
,
:

Где,

balance – баланс магазина, после успешного создания перевода;

id – уникальный идентификатор перевода на стороне Qostiq;

payee_amount – сумма к получению на счет в валюте payee_currency;

payee_currency – валюта получения на счет суммы payee_amount;

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

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

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

Перевести средства с баланса магазина [POST]

для демонстрации запроса в правом окне смените Production на Mock Server

Request (application/json)

  ```json
  {
      "amount": 10,
      "amount_type": "receive_amount",
      "payee_account": "201497141132",
      "payee_currency": 980,
      "shop_currency": 980,
      "shop_id": 112,
      "shop_payment_id": "55ac443d-958b-40e3-8956-e04e72561324",
      "sign": "cd30ba2b6e29f508edf40582e17a9a602a43be9b527238b1b0a6777e226381f4"
  }
  ```
  

Response 200 ()

  ```json
  {
      "data": {
          "balance": 88.91,
          "id": 12,
          "payee_account": 201497141132,
          "payee_amount": 10,
          "payee_currency": 980,
          "shop": 112,
          "shop_currency": 980,
          "write_off_amount": 10
      },
      "error_code": 0,
      "message": "Ok",
      "result": true
  }
  ```
  

Запрос статуса Transfer [/transfer/shop_payment_status]

Запрос статуса по переводу transfer выполняется по номеру платежа магазина.

В случае получения time-out или других ошибок на запрос создания transfer, можно сделать запрос статуса перевода с помощью данного метода. Если в ответе вернулся идентификатор и данные по переводу, то значит перевод был успешно создан и проведен. В противном случае вернется ошибка, что перевод не найден и необходимо будет повторить запрос на создание перевода.

URL:

https://core.qostiq.com/transfer/shop_payment_status

Метод: POST

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

Параметр	Описание	Формат	Пример
`now`	время запроса	String	"2018-06-15 09:58:01.01"
`shop_payment_id`	номер счета на стороне Вашего сервиса	String	"h8fj38dkh-hf8k-4f8d-9c8c-jd8dh38dksn92"
`shop_id`	идентификатор магазина в системе Qostiq	Integer	5
`sign`	подпись	String	"a7f5bcbb774cea9d9886cbb3ce2f8731359e356a7d759437b4e9e31da1152109"

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

{
:
,
:
,
:
,
:

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

{
`"data"`: `{`
:
,
:
,
:
,
:
,
:
,
:
` }`,
:
,
:
,
:

Пример ответа, если transfer не был создан (не найден):

{
:
,
:
,
:
,
:

Запросить статус transfer [POST]

Request (application/json)

  ```json
  { 
      "shop_id": 112, 
      "shop_payment_id": "55ac443d-958b-40e3-8956-e04e72561322", 
      "now": "2018-01-23 16:45:14.145107", 
      "sign": "e76c5ed9431d18ad6c01ea123241fe88330714c97bdd184860a80cb675c1e016" 
  } 
  ```

Response 200 ()

  ```json
  { 
  "data": 
      { 
          "id": 3, 
          "payee_currency": 980, 
          "receive_amount": 1, 
          "shop_currency": 980, 
          "shop_payment_id": "55ac443d-958b-40e3-8956-e04e72561322", 
          "write_off_amount": 1 
      }, 
      "error_code": 0, 
      "message": "Ok", 
      "result": true 
  }  
  ```
  

Response 200 (error)

  ```json
  { 
      "data": null, 
      "error_code": 7, 
      "message": "Transfer (shop_payment_id=test) wasn't found", 
      "result": false 
  }
  ```

Group Функционал Qostiq Wallet по подписке

Схема использования функционала Qostiq Wallet по подписке:

Запрос /auth_token/request для создания подписки. В ответе на запрос создания подписки вернется URL адрес на который необходимо выполнить редирект клиента для подтверждения им подписки.
После подтверждения подписки клиентом на указанный в настройках магазина URL будет выслан уникальный token который будет использоваться в дальнейших запросах.
Запрос на выполнения действия разрешенного для указаного token (например запрос списания фиатных средств /bill/recurrent).
При необходимости отключения подписки подписки и деактивации токена - необхдимо выполнить запрос /auth_token/revoke.

На один Qostiq Wallet можно создать несколько подписок использовав разные значения external_id. Значения external_id видны клиентам.

Запрос на создание подписки [/auth_token/request]

URL:

https://core.qostiq.com/auth_token/request

Метод: POST

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

Данный запрос создает сущность подписки которую необходимо подтвердить клиенту.

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

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

Где,

Параметр	Описание	Формат	Пример
`external_id`	номер или название подписки (видны клиенту)	String	"test_external_id"
`now`	время запроса	Integer	1691584193
`scopes`	тип подписки	Array	["bill_recurrent"] - значение для получения токена на платежи по подписке
`shop_id`	идентификатор магазина в системе Qostiq	Integer	6
`sign`	подпись	String	"912b985f18959620bb981485132016b58fc344361a51a24eda27687613141f7f"

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

  ```json
  {
      "data": {
          "redirect_url": "https://wallet.test-qostiq.com/subscription-request/27d5c54568e944abb2b5a64b845d13eb"
      },
      "error_code": 0,
      "message": "Ok",
      "result": true
  }
  ```

Необходимо выполнить браузерный редирект клиента (HTTP GET)на адрес, указанный в параметре redirect_url, для подтверждения подписки пользователем. После подтверждения будет прислано уведомление об активации подписки.

Важно:

redirect_url открывается только методом GET
redirect_url не является API endpoint
Отправка POST-запросов на redirect_url не поддерживается

Пример запроса на создание подписки [POST]

Request (application/json)

  ```json
  {
  "external_id": "external_id",
  "now": 1691584193,
  "scopes": [
      "bill_recurrent"
      ],
  f"shop_id": 6,
  "sign": "912b985f18959620bb981485132016b58fc344361a51a24eda27687613141f7f"
  }
  ```

Response 201 (application/json)

Body

  ```json
  {
      "data": {
          "redirect_url": "https://wallet.test-qostiq.com/subscription-request/27d5c54568e944abb2b5a64b845d13eb"
      },
      "error_code": 0,
      "message": "Ok",
      "result": true
  }
  ```

Уведомление активации и отмене подписки [/auth_token/callback]

После активации подписки клиентом на URL-адрес будет отправлено уведомление с токеном который необходимо будет использовать для дальнейшего совершения платежа.

URL-адрес указывается в личном кабинете в настройках магазина - URL уведомлений по auth токенам.

Также уведомление будет выслано в случаее отмены подписки клиентом.

Пример уведомления об активации подписки:

  ```json
  {
    "callback_type": "auth_token",
    "created": "2023-08-09 15:50:50",
    "external_id": "external_id",
    "scopes": [
        "bill_recurrent"
    ],
    "shop_id": 6,
    "sign": "7dh39fkd7cf1b1db2175606447c60e6d9b5c84219471f7239329a4c9a29",
    "status": 1,
    "token": "44c6703d-9f98-434d-936f-9e6784976c98"
  }
  ```

Где:

callback_type - тип уведомления, значение auth_token при уведомлении о активании подписки;

created - время активации подписки;

external_id - идентификатор подписки;

scopes - тип подписки, значение ["bill_recurrent"] при активании подписки на платежи;

sign - подпись коллбека;

status - статус токена, 1 - токен активный (подписка активирована), 2 - токен неактивный (подписка отменена);

token - токен подписки, используется для совершения последующих запросов, например совершении платежа без подтверждения.

Уведомление об отмене подписки [POST]

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

Request (application/json)

              ```json
              {
          "callback_type": "auth_token",
          "created": "2023-08-09 14:42:46",
          "external_id": "external_id",
          "scopes": [
              "bill_recurrent"
          ],
          "shop_id": 6,
          "sign": "11d94f04959e153cd719ab7029f767d8e6ea853af4f26a4f0f77a7b238c1e78f",
          "status": 2,
          "token": "44c6703d-9f98-434d-936f-9e6784976c98"
      }
              ```

Response 200 (application/json)
- Body
```
  OK
```

Создание фиатного платежа по подписке [/bill/recurrent]

URL:

https://core.qostiq.com/bill/recurrent

Метод: POST

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

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

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

      ```json
      {
          "amount":"10",
          "currency":840,
          "now": 1691658477,
          "shop_id": 6,
          "shop_order_id":"test payment",
          "token": "f1cebac7-e05b-4c94-bb26-a222b976cb2d",
          "sign": "97a4dd349871cc80aef906cee468d8b942c0197848e3ed86a6f9f58a8725e180"
      }
      ```

Где,

Параметр	Описание	Формат	Пример
`amount`	сумма платежа	Number (Не больше 2х знаков после точки)	1, 1.0, 1.00 или "1.00"
`currency`	валюта выставленного счета	Integer	840 - Доллар США, 980 - Украинская гривна, 978 - Евро, 398 - Казахстанский тенге
`shop_id`	идентификатор магазина в системе Qostiq	Integer	6
`now`	время запроса	Integer	1691584193
`token`	токен подписки полученый в ответе на запрос создания подписки.	String	"f1cebac7-e05b-4c94-bb26-a222b976cb2d"
`scopes`	тип подписки	Array	["bill_recurrent"] - значение для получения токена на платежи по подписке
`shop_order_id`	номер счета на стороне Вашего сервиса	String	"123456789"
`sign`	подпись	String	"912b985f18959620bb981485132016b58fc344361a51a24eda27687613141f7f"

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

      ```json
      {
          "data": {
              "id": 2177,
              "status": 2
          },
          "error_code": 0,
          "message": "Ok",
          "result": true
      }
      ```

Где параметры ответа:

id - уникальный id платежа в рамках фиатный платежей с кошелька Qostiq;

status - статус платежа, где значения 2 - платеж успешен. Таблица статусов платежей.

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

Создание фиатного платежа по подписке [POST]

Request (application/json)

```json { "amount":"10", "currency":840, "now": 1691658477, "shop_id": 6, "shop_order_id":"test payment", "token": "f1cebac7-e05b-4c94-bb26-a222b976cb2d", "sign": "97a4dd349871cc80aef906cee468d8b942c0197848e3ed86a6f9f58a8725e180" } ```

Response 200 (application/json)

Body

```json { "data": { "id": 2177, "status": 2 }, "error_code": 0, "message": "Ok", "result": true } ```

Создание криптовалютного платежа по подписке [/crypto/bill/recurrent]

URL:
https://core.qostiq.com/crypto/bill/recurrent

Метод: POST

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

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

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

```json { "amount":"10", "currency":"USDT", "now": 1691669000, "shop_id": 6, "shop_order_id":"test payment", "token": "f1cebac7-e05b-4c94-bb26-a222b976cb2d", "sign": "ac3503d0b2e21c4716c96fbd58f32da678cf0a179a34bdf60ce5f36016efa2a2" } ```

Где,

Параметр Описание Формат Пример

amount сумма платежа String или number, количество знаков после запятой смотрите детальней в пункте "Указание суммы операции" "1.00000001" или 1.00000001, или "10"

currency валюта выставленного счета String "USDT"

shop_id идентификатор магазина в системе Qostiq Integer 6

now время запроса Integer 1691669000

token токен подписки полученый в ответе на запрос создания подписки. String "f1cebac7-e05b-4c94-bb26-a222b976cb2d"

scopes тип подписки Array ["bill_recurrent"] - значение для получения токена на платежи по подписке

shop_order_id номер счета на стороне Вашего сервиса String "test payment"

sign подпись String "ac3503d0b2e21c4716c96fbd58f32da678cf0a179a34bdf60ce5f36016efa2a2"

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

```json { "data": { "id": 1579, "status": 2 }, "error_code": 0, "message": "Ok", "result": true } ```

Где параметры ответа:

id - уникальный id платежа в рамках криптовалютных платежей с кошелька Qostiq;

status - статус платежа, где значения 2 - платеж успешен. Таблица статусов платежей.

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

Запрос на создание криптовалютного платежа по подписке [POST]

Request (application/json)

```json { "amount":"10", "currency":"USDT", "now": 1691669000, "shop_id": 6, "shop_order_id":"test payment", "token": "f1cebac7-e05b-4c94-bb26-a222b976cb2d", "sign": "ac3503d0b2e21c4716c96fbd58f32da678cf0a179a34bdf60ce5f36016efa2a2" } ```

Response 200 (application/json)

Body

```json { "data": { "id": 1579, "status": 2 }, "error_code": 0, "message": "Ok", "result": true } ```

Запрос на отмену подписки [/auth_token/revoke]

URL:
https://core.qostiq.com/auth_token/revoke

Метод: POST

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

Данный запрос позволяет закрыть активную подписку ().

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

```json { "shop_id": 6, "token": "44c6703d-9f98-434d-936f-9e6784976c98", "now": 1691671996, "sign": "8f15f065b07f6a2150277d57e125f3133ae4f9cab31f3529aaa8d6daa97b0c1d" } ```

Где:

Параметр Описание Формат Пример

shop_id идентификатор магазина в системе Qostiq Integer 6

now время запроса Integer 1691671996

token токен подписки полученый в ответе на запрос создания подписки. String "44c6703d-9f98-434d-936f-9e6784976c98"

sign подпись String "ac3503d0b2e21c4716c96fbd58f32da678cf0a179a34bdf60ce5f36016efa2a2"

Пример ответа, при успешном закрытии подписки в ответе вернется токен подписки:

```json { "data": { "token": "44c6703d-9f98-434d-936f-9e6784976c98" }, "error_code": 0, "message": "Ok", "result": true } ```

Если подписка уже отменена будет получена ошибка:

```json { "data": null, "error_code": 10, "message": "Auth token (44c6703d-9f98-434d-936f-9e6784976c98) not found", "result": false } ```

Запрос на отмену подписки [POST]

Request (application/json)

```json { "shop_id": 6, "token": "44c6703d-9f98-434d-936f-9e6784976c98", "now": 1691671996, "sign": "8f15f065b07f6a2150277d57e125f3133ae4f9cab31f3529aaa8d6daa97b0c1d" } ```

Response 200 (application/json)

```json { "data": { "token": "44c6703d-9f98-434d-936f-9e6784976c98" }, "error_code": 0, "message": "Ok", "result": true } ```

Запрос статуса фиатного платежа по подписке [/bill/shop_order_status]

Этот метод позволяет узнать текущий статус фиатного платежа с кошелька Qostiq wallet.

URL:
https://core.qostiq.com/bill/shop_order_status

Метод: POST

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

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

{
"now"
:
"2021-05-01 16:56:25.009469"
,

"shop_id"
:
1092
,

"shop_order_id"
:
"234234232323"
,

"sign"
:
"b9b838e0b1baedcf7dd60711b1afab246c3496b5cc3433df0c5a2e2d07fea976"

}

Параметр Описание Формат Пример

now время запроса String "2021-05-01 16:56:25.009469"

shop_id идентификатор магазина в системе Qostiq Integer 1092

shop_order_id номер счета на стороне Вашего сервиса String "234234232323"

sign подпись String "b9b838e0b1baedcf7dd60711b1afab246c3496b5cc3433df0c5a2e2d07fea976"

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

<li> { <li> ` "data"`:` { ` </li> <li> <ul> "client_price"</ul>:<ul> 1.16</ul>, </li> <li> <ul> "created"</ul>: <ul>"2020-10-20 14:01:28"</ul>, </li> <li> <ul> "description"</ul>:<ul> ""</ul>, </li> <li> <ul> "is_unique"</ul>:<ul> true</ul>, </li> <li> <ul> "payment_id"</ul>: <ul>852095</ul>, </li> <li> <ul> "payway"</ul>: <ul>"qostiq_usd"</ul>, </li> <li> <ul> "processed"</ul>: <ul>2020-10-20 14:01:33</ul>, </li> <li> <ul> "ps_currency"</ul>: <ul>980</ul>, </li> <li> ` "ps_data"`: <ul>{ "ps_payer_account": "201538122124" }</ul>, </li> <li> <ul> "shop_amount"</ul>:<ul> 1.1</ul>, </li> <li> <ul> "shop_currency"</ul>: <ul>980</ul>, </li> <li> <ul> "shop_id"</ul>:<ul> 1092</ul>, </li> <li> <ul> "shop_order_id"</ul>:<ul> "234234232323"</ul>, </li> <li> <ul> "shop_refund"</ul>: <ul>1.1</ul>, </li> <li> <ul> "status"</ul>:<ul> 2</ul></li> <li> ` },` </li> <li> <ul> "error_code"</ul>:<ul> 0</ul>, </li> <li> <ul> "message"</ul>:<ul> "Ok"</ul>, </li> <li> <ul> "result"</ul>:<ul> true </ul> </li> } </li>

Где,

client_price – сумма платежа;

created – дата создания;

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

is_unique – уникальность номера платежа;

payment_id – идентификатор платежа на стороне Qostiq;

payway – платежное направление;

processed – дата проведения платежа;

ps_currency – валюта выставленного счета;

ps_data – дополнительная информация от платежной системы, например аккаунт плательщика;

shop_amount – сумма счета, переданная магазином;

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

shop_id – идентификатор магазина в системе Qostiq;

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

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

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

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

Параметр	Описание	Формат	Пример
`amount`	сумма платежа	String или number, количество знаков после запятой смотрите детальней в пункте "Указание суммы операции"	"1.00000001" или 1.00000001, или "10"
`currency`	валюта выставленного счета	String	"USDT"
`shop_id`	идентификатор магазина в системе Qostiq	Integer	6
`now`	время запроса	Integer	1691669000
`token`	токен подписки полученый в ответе на запрос создания подписки.	String	"f1cebac7-e05b-4c94-bb26-a222b976cb2d"
`scopes`	тип подписки	Array	["bill_recurrent"] - значение для получения токена на платежи по подписке
`shop_order_id`	номер счета на стороне Вашего сервиса	String	"test payment"
`sign`	подпись	String	"ac3503d0b2e21c4716c96fbd58f32da678cf0a179a34bdf60ce5f36016efa2a2"

Если shop_order_id не уникален по операциям bill в рамках магазина, в ответе содержится "is_unique":false и метод возвращает информацию по последнему созданному фиатному платежу с кошелька Qostiq.
Запрос статуса фиатного платежа по подписке [POST]

Request (application/json)

```json { "now": "2021-05-01 16:56:25.009469", "shop_id": "1092", "shop_order_id": "234234232323", "sign": "ad7fbe8df102bc70e28deddba8b45bb3f4e6cafdaa69ad1ecc0e8b1d4e770575" } ```

Response 200 ()

```json { "data": { "client_price": 1.16, "created": "2020-10-20 14:01:28", "description": "", "is_unique": true, "payment_id": 852095, "payway": "qostiq_usd", "processed": "2020-10-20 14:01:33", "ps_currency": 980, "ps_data": { "ps_payer_account": "201538122124" }, "shop_amount": 1.1, "shop_currency": 980, "shop_id": 1092, "shop_order_id": "234234232323", "shop_refund": 1.1, "status": 2 }, "error_code": 0, "message": "Ok", "result": true } ```

Запрос статуса криптовалютного платежа по подписке [/crypto/bill/shop_order_status]

URL:
https://core.qostiq.com/crypto/bill/shop_order_status

Метод: POST

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

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

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

{

"now"
:
1691676646

"shop_id"
:
6

"shop_order_id"
:
"test payment"

"sign"
:
97a8d477e41d7e61af1a65ac9c662d1b28064aa4248a4eebb641deb5524e37f1

}

Где,

Параметр Описание Формат Пример

now время запроса, в формате unixtimestamp Integer 1691676646

shop_id идентификатор магазина в системе Qostiq Integer 6

shop_order_id идентификатор счета на стороне магазина String "test payment"

sign подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign) String "97a8d477e41d7e61af1a65ac9c662d1b28064aa4248a4eebb641deb5524e37f1"

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

{
"data"
:

`{`

"created"
:
"2023-08-10 12:03:20"
,

"description"
:
""
,

"is_unique"
:
false
,

"payer_currency"
:
"USDT"
,

"payer_price"
:
"1.0"
,

"payment_id"
:
1579
,

"processed"
:
"2023-08-10 12:03:20"
,

`"ps_data"`:`{"ps_payer_account": 31645670435}`,

"shop_amount"
:
"1.0"
,

"shop_currency"
:
"1.0"
,

"shop_id"
:
"1.0"
,

"shop_order_id"
:
"test payment"
,

"shop_refund"
:
"0.97"
,

"status"
:
2

`},`

"error_code":
0,

"message":
"Ok",

"result":
true
}

Где,

created - дата создания платежа;

description - описание выставленного платежа,

is_unique - уникальность номера платежа на стороне магазина - shop_order_id ,

payer_currency - валюта списания суммы платежа payer_price с кошелька клиента,

payer_price - сумма списания с кошелька клиента в валюте payer_currency;

payment_id - уникальный номер операции на стороне Qostiq, возвращается в параметре id на запрос создания платежа /crypto/bill/create;

processed - время получения финального статуса платежа;

ps_data.ps_payer_account - номер кошелька плательщика;

shop_amount - сумма выставленного платежа в валюте shop_currency;

shop_currency - валюта платежа;

shop_id - номер магазина;

shop_order_id - номера платежа на стороне магазина;

shop_refund - сумма зачисления платежа на магазин в валюте shop_currency;

status - статус счета, информацию о статусах можно посмотреть в пункте Статусы платежей.

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

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

Если shop_order_id не уникален по операциям bill в рамках магазина, в ответе содержится "is_unique":false и метод возвращает информацию по последнему созданному Bill. Уникальность shop_order_id проверяется в зависимости от настроек магазина, рекомендуем включить данную функцию и передавать уникальное значение для вашего магазина, для избежание дублированного выставления счетов на оплату.

Запрос статуса криптовалютного платежа по подписке [POST]

Request

```json { "now": 1691676646, "shop_id": 6, "shop_order_id": "test payment", "sign": "97a8d477e41d7e61af1a65ac9c662d1b28064aa4248a4eebb641deb5524e37f1" } ```

Response 200 ()

```json { "data": { "created": "2023-08-10 12:03:20", "description": "", "is_unique": false, "payer_currency": "USDT", "payer_price": "1.0", "payment_id": 1579, "processed": "2023-08-10 12:03:20", "ps_data": { "ps_payer_account": "31645670435" }, "shop_amount": "1.0", "shop_currency": "USDT", "shop_id": 6, "shop_order_id": "test payment", "shop_refund": "0.97", "status": 2 }, "error_code": 0, "message": "Ok", "result": true } ```

Статус платежей по подписке [/bill/status]

Значение status Название Описание Финальный?

1 Waiting Платеж находится в стадии ожидания действий пользователя Нет

2 Paid Платеж оплачен клиентом Да

3 Canceled Платеж отменен клиентом Да

4 Expired Истёк срок жизни счёта Да

Запрос статуса Bill при неуникальном shop_order_id [POST]

Request (application/json)

```json { "now": "2021-05-01 16:56:25.009469", "shop_id": "112", "shop_order_id": "123billtest", "sign": "6fb934f7e00d205cb5ebb62117d9b74029d84c2ffc7c87fe5b38ac5196fecf02" } ```

Response 200 ()

```json { "data": { "client_price": 1.0, "created": "2021-06-09 13:47:05", "description": "", "is_unique": false, "payment_id": 19732961, "payway": "qostiq_usd", "processed": null, "ps_currency": 980, "ps_data": { "ps_payer_account": "201538122124" }, "shop_amount": 1.0, "shop_currency": 980, "shop_id": 1092, "shop_order_id": "123billtest", "shop_refund": 0.93, "status": 4 }, "error_code": 0, "message": "Ok", "result": true } ```

Ошибки при использовании функционала по подписке [/error]

Запрос `error_code` `message` Описание

/bill/recurrent /crypto/bill/recurrent /auth_token/revoke `10` `Auth token ({token}) not found` Токен не существует или неактивный

/bill/recurrent /crypto/bill/recurrent `9` `Insufficient payer (id=6) balance` Недостаточно средств для списания на кошельке клиента

/bill/recurrent /crypto/bill/recurrent `44` `Limit exceeds` Превышен установленый клиентом лимит на оплату по подписке

Запрос c ошибкой в ответе [POST]

Request

```json { "amount":"1", "currency":840, "shop_id": 6, "token": "0b2808dc-3b6e-48d0-ac9b-64e31b756182", "now": 1692098067, "shop_order_id":"test payment", "sign": "8a461f70b3a8d4f5e2668f9de4ad17c8d1759f891333caf03ae9f50d5015618d" } ```

Response 200 ()

```json { "data": null, "error_code": 44, "message": "Limit exceeds", "result": false } ```

Group Создание платежа

Общие рекомендации по работе с API выставления счетов для оплаты

Убедитесь, что Ваш магазин активирован и настроен для работы по API: получен ID магазина, указан URL взаимодействия, сгенерирован секретный ключ и указаны IP адреса ваших сервисов. Payway платежных направлений для выставления счетов Вы можете найти в личном кабинете в настройках магазина в разделе «Методы оплаты». Процесс выставления счетов выглядит следующим образом:

Отправляется запрос на предварительный расчет выставленного счета и получении дополнительных параметров try;

При получении result==ok, проверяется наличие дополнительной информации в add_ons_config, если присутствует, необходимо в запросе на выставлении счета передать данные дополнительные параметры. При получении result==error, необходимо анализировать сообщение об ошибке в message;

После проверки try отправляется запрос на выставление счет
invoice, с указанием обязательных параметров и дополнительной информации в add_ons_config (если она является обязательной для указанного платежного направления);
В ответе возвращается информация с выставленным счетом и данными для отправки указанным методом на указанный URL, для совершения оплаты; После совершения оплаты, система Qostiq отправит уведомление на URL взаимодействия магазина, с информацией об оплате.
Предварительный расчет инвойса [/invoice/try] Данный метод не является обязательным для выставления счета на оплату. Возвращает дополнительную информацию для создания invoice для оплаты и предварительный расчет по комиссиям. URL: https://core.qostiq.com/invoice/try Метод: POST Обязательные параметры: amount, currency, payway, shop_id, shop_order_id, sign Пример запроса: { "currency" : "980" , "sign" : "912b985f18959620bb981485132016b58fc344361a51a24eda27687613141f7f" , "payway" : "card_uah" , "amount" : "12.34" , "shop_id" : 112 , "shop_order_id" : 4128 } Параметр Описание Формат Пример shop_id идентификатор магазина в системе Qostiq Integer 5 amount сумма выставленного счета Number (Не больше 2х знаков после точки) 1, 1.0, 1.00 или "1.00" currency валюта выставленного счета Integer 980 - Украинская гривна, 840 - Доллар США, 978 - Евро payway платежное направление, для которого производится предварительный расчет String "card_uah" (можно уточнить у менеджера или в личном кабинете) sign подпись String "a7f5bcbb774cea9d9886cbb3ce2f8731359e356a7d759437b4e9e31da1152109" shop_order_id номер счета на стороне Вашего сервиса String "h8fj38dkh-hf8k-4f8d-9c8c-jd8dh38dksn92" description описание выставленного счета (не обязательный параметр) String "test bill" Пример ответа: { ` "data"`:` {` ` "add_ons_config"`:` {}`, ` "manual"`:` {}`, "payer_price" : 10.0 , "paymethod_id" : 3 , "paymethod_name" : "Visa/MasterCard" , "ps_currency" : 980 `}`, "error_code" : 0 , "message" : "Ok" , "result" : true } или { `"data"`:` {` `"add_ons_config"`: `{` `"email"`: `{` `"comment"`: `{` "en" : "Enter your e-mail" , "ru" : "Введите Ваш e-mail" , ` }`, "example" : "mail@example.com" , `"label"`:` {` "en" : "E-mail" , "ru" : "E-mail:" , `}`, "regex" : "^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+$" ` } ` `}`, ` "manual"`: `{}`, "payer_price" : 10.0 , "paymethod_id" : 4 , "paymethod_name" : "Visa/MasterCard" , "ps_currency" : 980 ` }`, "error_code" : 0 , "message" : "Ok" , "result" : true Пример ошибки: { "data" : null , "error_code" : 4 , "message" : "Payer price amount is too small, min: 1.0" , "result" : false } Предварительный расчет инвойса [POST] Request (application/json) ```json { "currency": "980", "sign": "912b985f18959620bb981485132016b58fc344361a51a24eda27687613141f7f", "payway": "card_uah", "amount": "12.34", "shop_id": 112, "shop_order_id": 4128 } ``` Response 200 () ```json { "data": { "add_ons_config": {}, "manual": {}, "payer_price": 12.34, "paymethod_id": 3, "paymethod_name": "Visa/MasterCard", "ps_currency": 980 }, "error_code": 0, "message": "Ok", "result": true } ``` Выставление счета [/invoice/create] Invoice. При помощи данного метода создаются платежи для оплаты в других платежных системах. Prod URL: https://core.qostiq.com/invoice/create Test URL: https://core.test-qostiq.com/invoice/create Метод: POST Обязательные параметры: amount, currency, payway, shop_id, shop_order_id, sign Уникальность shop_order_id проверяется в зависимости от настроек магазина, рекомендуем включить данную функцию и передавать уникальное значение для вашего магазина, для избежание дублированного выставления счетов на оплату. В запросе могут передаваться дополнительные параметры, например, description – описание счета, или phone – номер телефона, для оплаты через мобильную коммерцию. Пример запроса: { "currency" : "980" , "payway" : "card_uah" , "amount" : "12.34" , "shop_id" : 112 , "shop_order_id" : 4129 , "description" : "Test invoice" , "sign" :"8fb2cafda4da9de1f1c00787dd5d22e6a8094256d0e47b633783f652624b81d4" } Параметр Описание Формат Пример shop_id идентификатор магазина в системе Qostiq Integer 5 amount сумма выставленного счета Number (Не больше 2х знаков после точки) 1, 1.0, 1.00 или "1.00" currency валюта выставленного счета Integer 980 - Украинская гривна, 840 - Доллар США, 978 - Евро, payway платежное направление, для которого производится предварительный расчет String "card_uah" (можно уточнить у менеджера или в личном кабинете) sign подпись String "a7f5bcbb774cea9d9886cbb3ce2f8731359e356a7d759437b4e9e31da1152109" shop_order_id номер счета на стороне Вашего сервиса String "h8fj38dkh-hf8k-4f8d-9c8c-jd8dh38dksn92" Так же, в запросе можно передавать дополнительные параметры, в формировании подписи они не участвуют. Параметр Описание Формат Пример description описание выставленного счета (не обязательный параметр) String "test bill" failed_url URL, на который будет перенаправлен плательщик, после не успешной оплаты счета, String "https://qostiq.com/failed" success_url URL, на который будет перенаправлен плательщик, после успешной оплаты счета String "https://qostiq.com/success" callback_url URL адрес на который будет отправляться уведомление об успешной оплате String "https://qostiq.com/callback_url_kvt" callback_rejected_url URL адрес на который будет отправляться уведомление о неуспешной оплате String "https://qostiq.com/callback_rejected_url_kvt" Важно! Success URL, Fail URL, URL уведомлений, URL reject уведомлений указанные в настройках магазина, имееют приоритет выше переданных в запросе, поэтому необходимо удалить их из настроек магазина. Пример ответа: { `"data"`:` {` `"data"`:` {` "session_id" : "07bdd98b1c264fc4bd41f875419907a2" `}`, "id" : 1218989 , "method" : "GET" , "url" : ""https://card.qostiq.com/ru/payform/07bdd98b1c264fc4bd41f875419907a2" `}`, "error_code" : 0 , "message" : "Ok" , "result" : true } Пример ответа: Где, data - source для отправки методом method параметров из data. method – метод оправки data на source, формат: POST, GET url – URL на который необходимо отправить data методом method id – уникальный идентификатор счета в системе Qostiq После получения ответа на запрос создания счёта, мерчант должен сформировать HTML-страницу , содержащую форму с автозаполнением и автоматической отправкой данных. Это необходимо для корректного перехода клиента на страницу оплаты. В теле ответа на запрос создания счёта возвращаются параметры, которые требуется отправить методом POST на указанный URL. Рекомендуется использовать HTML-форму с автоотправкой, чтобы обеспечить надёжную и безопасную передачу данных. Обратите внимание: простой переход по ссылке из ответа не инициирует оплату. Использование HTML-формы обязательно, так как данные должны быть переданы методом POST. ### Важно: Поведение при оплате криптовалютой Если мерчант выставляет счет в фиате, а клиент оплачивает его в криптовалютой, в момент финального расчета может возникнуть расхождение между исходной суммой amount и фактически зачисленной суммой. Всегда сверяйте shop_refund, shop_amount и client_price в уведомлениях. При is_overwritten:true суммы будут отличаться от изначальных Когда суммы могут измениться? Сценарий Пример Как проявляется Изменение курса Клиент платит BTC, курс изменился за время подтверждения shop_amount ≠ исходному amount Переплата Клиент отправил больше криптовалюты, чем требовалось client_price > расчётного значения Недоплата Клиент отправил недостаточно криптовалюты client_price < минимального лимита Как обрабатывать ответы: Случай 1: Сумма не изменилась(is_overwritten: false) Пример ответа : "status": "completed", "amount": "100.00", "shop_amount": "100.00", "shop_refund": "99.50", "is_overwritten": false, "currency": "USD" Инструкция для мерчанта: Проверить статус Определение суммы (используйте исходную сумму: amount:) Зачисление средств Случай 2: Сумма изменилась(is_overwritten: true) Пример ответа : "status": "completed", "amount": "100.00", "overwrite_amount": "99.85", "shop_amount": "99.85", "shop_refund": "99.00", "is_overwritten": true, "currency": "USD" Инструкция для мерчанта: Проверка статуса. Коррекция суммы. (используйте актуальную сумму: overwrite_amount:) Сверка данных. (убедитесь, что: overwrite_amount ≈ shop_amount ) Зачислите себе сумму shop_refund Параметр Тип Обязательный Описание Пример currency string ✓ Код валюты ISO 4217 "980" payway string ✓ Платежный метод "card_uah" amount string ✓ Сумма платежа "100.00" shop_id integer ✓ ID магазина 112 shop_order_id integer ✓ ID заказа 4129 description string Описание платежа "Test invoice" sign string ✓ Подпись запроса "8fb2cafd..." overwrite_amount string Скорректированная сумма "99.85" is_overwritten boolean Флаг изменения суммы true shop_amount string ✓ Итоговая сумма счета "99.85" shop_refund string ✓ Сумма зачисления "99.00" Для перенаправления клиента для оплаты выставленного счета, необходимо данную информацию использовать для генерации и подтверждения HTML-формы, например: Method GET URL https://card.qostiq.com/ru/payform/07bdd98b1c264fc4bd41f875419907a2 input name="session_id" value="07bdd98b1c264fc4bd41f875419907a2" input type="submit" Пример ошибки при выставлении инвойса: { "data" : null , "message" : "Payway (id=3) is not found" , "error_code" : 1 , "result" : false } Где message – описание ошибки; error_code – код ошибки Выставление счета - invoice [POST] Request (application/json) ```json { "currency": "980", "payway": "card_uah", "amount": "12.34", "shop_id": 112, "shop_order_id": 4129, "description": "Test invoice" , "sign":"8fb2cafda4da9de1f1c00787dd5d22e6a8094256d0e47b633783f652624b81d4" } ``` Response 200 () ```json { "data": { "data": { "session_id": "07bdd98b1c264fc4bd41f875419907a2" }, "id": 2403182, "method": "GET", "url": "https://card.qostiq.com/ru/payform/07bdd98b1c264fc4bd41f875419907a2" }, "error_code": 0, "message": "Ok", "result": true } ``` Возможные ошибки [/invoice/errors] Пример отображения ошибки в консоли: "error_code": 10 Код ошибки Описание 1 PaywayNotFound 2 PaywayNotUsed 3 PaywayNotAvailable 4 AmountTooSmall 5 AmountTooLarge 6 OperationNotUnique 7 OperationNotFound 8 OperationIsProcessing 9 InsufficientBalance 10 IncorrectRequestParam 11 ShopNotFound 12 ShopNotActive 13 AccountNotFound 14 IncorrectAccountStatus 15 RequestIpDenied 16 InvalidCurrencyExchange 17 InvalidShopContract 18 IncorrectAccountType 19 ShopAggregatorRequire 20 InvalidProject 21 ProjectNotActive 100 IncorrectOperationStatus 2000 Другая ошибка Пример получения ошибки [POST] Request (application/json) ```json { "amount": "120000.00", "currency": 980, "payway": "card_uah", "shop_id": 112, "shop_order_id": 4129, "description": "Test invoice" , "sign":"8fb2cafda4da9de1f1c00787dd5d22e6a8094256d0e47b633783f652624b81d4" } ``` Response 200 () ```json { "data": null, "error_code": 5, "message": "Payer price amount is too large, max: 100000.0", "result": false } ``` Оффлайн методы оплаты [/invoice/offline] При выставлении счета на оплату через такие offline системы, в ответ на запрос invoice вернётся method = offline и url = offline, а в data будет передана информация для плательщика в виде HTML кода (информация может быть передана на нескольких языках). В данном случае, клиента не нужно никуда перенаправлять. К оффлайн методам относится мобильная коммерция и пополнение счета через терминалы. Пример запроса на оплату Оффлайн способом [POST] Request (application/json) ```json { "amount": 100, "currency": 980, "payway": "vodafone_uah", "phone": "9827908437", "shop_id": "112", "shop_order_id": "Invoice#61586603", "sign": "56789cc6d34ebc6e064daf416911baa9ae3aac9ca269e3566b13236cc554e1fb" } ``` Response 200 () ```json { data": { "data": { "en": "<h4>Уважаемый клиент!</h4> <p>Ваш запрос успешно принят. Вам отправлено СМС с подробной инструкцией для завершения оплаты.</p> <p>Просим Вас следовать указанным действиям.</p> Вы можете закрыть эту страницу, после подтверждения оплаты платеж будет обработан автоматически.</p> <br/>", "ru": "<h4>Уважаемый клиент!</h4> <p>Ваш запрос успешно принят. Вам отправлено СМС с подробной инструкцией для завершения оплаты.</p> <p>Просим Вас следовать указанным действиям.</p> Вы можете закрыть эту страницу, после подтверждения оплаты платеж будет обработан автоматически.</p> <br/>" }, "id": 132411408, "method": "OFFLINE", "url": "OFFLINE" }, "error_code": 0, "message": "Ok", "result": true } ``` Уведомление после оплаты [/invoice/callback] Callback - Данная функция применяется только для методов Bill и Invoice. После оплаты выставленного счета, система Qostiq производит отправку уведомления магазину на указанный в настройках URL взаимодействия. Уведомления отправляются с IP-адресов: 34.90.243.164 34.147.48.238 34.90.176.128 34.90.34.134 35.242.192.50 Необходимо обязательно сверять значения из уведомления со значениями в выставленном счете и проверять подпись в уведомлении. Важно! Всегда сверяйте суммы операции - shop_refund, shop_amount, client_price при получении уведомления. Так как при получении в уведомлении параметра "is_overwritten":true суммы операции будет изменены. Узнать будет ли включена на платежном направлении функция изменения суммы платежа - вы можете обратившись к вашему курирующему менеджеру или службу поддержки. Метод: POST, Content-Type=application/x-www-form-urlencoded Пример уведомления: { "client_price" : 5.0 , "created" : "2019-10-30 12:27:48" , "description" : null , "is_overwritten" : false , "lang" : "ru" , "payment_id" : 107120419 , "payway" : "card_uah" , "processed" : "2019-10-30 12:28:47" , "ps_currency" : 980 , `"ps_data"`:` "{"ps_payer_account": "537541XXXXXX7424"}"`, "shop_amount" : 5.0 , "shop_currency" : 980 , "shop_id" : 2104 , "shop_order_id" : "test_invoice" , "shop_refund" : 4.8 , "sign" : "f50c81db95829fdaf06263ef77a299eea7b3cf01efb04c053f37124cb21692db" , "status" : "success" }, Где, client_price – сумма, которую оплатил клиент, в валюте платежной системы; created – дата и время создания счета; processed – дата и время изменения статуса счета (оплата или отклонение); description – описание счета; is_overwritten – была ли изменена изначальная сумма платежа amount. При значении true сумма платежа была изменена и отличается от изначальной; payment_id – уникальный идентификатор выставленного счета в системе Qostiq; payway – платежное направление в системе Qostiq, через которое оплатил пользователь; ps_currency – валюта платежного направления, через которое оплатил пользователь; ps_data – дополнительная информация от платежной системы, например аккаунт плательщика; shop_amount – сумма выставленного счета, в валюте счета; shop_currency – валюта счета; shop_id – уникальный идентификатор магазина, в пользу которого осуществляется оплата; shop_order_id – номер счета, идентификатор переданный магазином; shop_refund – сумма зачисления на баланс магазина, в валюте счета; status – статус счета, success – оплачен и зачислен, rejected – отклонен клиентом или ПС; sign – подпись; test_add_on – пользовательский параметр, переданный магазином при создании счета на оплату; При получении уведомления по отклоненному платежу добавляется причина отказа в rejected_reason. Пример параметра в rejected-коллбэке: `"ps_data": "{\"ps_payer_account\": \"533669XXXXXX8888\", \"rejected_reason\": \"Na schete karty nedostatochno sredstv dlja vypolnenija operatsii\"}",` "status": "rejected", Подпись формируется по тому же алгоритму, что и при выставлении счета, но в формировании подписи участвуют уже все параметры, значение которых не null и пустая строка. При корректном получении и обработке уведомления, необходимо вернуть в ответ http статус 200 и тело сообщения OK. В ином случае уведомления будут высылаться повторно, с увеличивающемся интервалом, всего 25 попыток, последнее по истечении суток. Пример строки, по которой необходимо сгенерировать подпись 5.0:2019-10-30 12:27:48:false:ru:107120419:card_uah:2019-10-30 12:28:47:980:{"ps_payer_account": "537541XXXXXX7424"}:5.0:980:2104:test_invoice:4.8:successTestkey1 Пример уведомления по успешному платежу [POST] Request (application/x-www-form-urlencoded) ```json { "client_price": 2500, "created": "2020-01-19 15:38:59", "description": null, "is_overwritten": false, "payment_id": 132803748, "payway": "сard_uah", "processed": "2020-01-19 15:39:17", "ps_currency": 980, "ps_data": "{\"paymentPayerCode\": \"410014233707050\", \"ps_payer_account\": \"410014233707050\"}", "shop_amount": 2500, "shop_currency": 980, "shop_id": 112, "shop_order_id": "2750", "shop_refund": 2300, "sign": "490001f775c752c08a5a9de2337b0f26fcf6287c4a780eb70edce38386f5ffd8", "status": "success", } ``` Response 200 () ```json { "response_data": "OK", "shop": 112, "transfer": null, "withdraw": null } ``` Пример уведомления по неуспешному платежу [POST] Request (application/x-www-form-urlencoded) ```json { "client_price": 1500, "created": "2019-12-23 15:26:36", "description": null, "payment_id": 123166089, "payway": "card_uah", "processed": "2019-12-23 15:26:41", "ps_currency": 980, "ps_data": "{\"ps_payer_account\": \"533669XXXXXX8843\", \"rejected_reason\": \"Prevyshen limit po schetu karty\"}", "shop_amount": 1500, "shop_currency": 980, "shop_id": 112, "shop_order_id": "37962464", "shop_refund": 1440, "sign": "3f00f3b370ffce41d9de6a019e2c7a331b4f472e25ac26fef90f0bba49b7101d", "status": "rejected", } ``` Response 200 () ```json { "response_data": "OK", "shop": 112, "transfer": null, "withdraw": null } ``` Запрос статуса [/invoice_check] URL: https://core.qostiq.com/invoice/check Метод: POST Обязательные параметры: now, shop_id, shop_order_id Пример запроса: { "now" : "2018-06-15 09:58:01.01" , "shop_id" : 1 , "shop_order_id" : "123456789" , "sign" : "32b2c32caa8adecf89c6dfa72ffca3a0506f33febfe3aaab090cdbfbd0e8b953" } Важно! Всегда сверяйте суммы операции - shop_refund, shop_amount, client_price с полученого ответа. Так как при получении в параметра "is_overwritten":true суммы операции будет изменены. Узнать будет ли включена на платежном направлении функция изменения суммы платежа - вы можете обратившись к вашему курирующему менеджеру или службу поддержки. Параметр Описание Формат Пример now время запроса String "2018-06-15 09:58:01.01" shop_id идентификатор магазина в системе Qostiq Integer 1 shop_order_id номер счета на стороне Вашего сервиса String "123456789" sign подпись String "32b2c32caa8adecf89c6dfa72ffca3a0506f33febfe3aaab090cdbfbd0e8b953" Пример ответа: <li> { <li> ` "data"`:` { ` </li> <li> <ul> "client_price"</ul>:<ul> 10.2</ul>, </li> <li> <ul> "created"</ul>: <ul>"2018-06-18 17:22:49"</ul>, </li> <li> <ul> "description"</ul>:<ul> "Test+invoice"</ul>, </li> <li> <ul> "is_overwritten"</ul>:<ul> false</ul>, </li> <li> <ul> "is_unique"</ul>:<ul> false</ul>, </li> <li> <ul> "payment_id"</ul>: <ul>11639480</ul>, </li> <li> <ul> "payway"</ul>: <ul>"card_uah"</ul>, </li> <li> <ul> "processed"</ul>: <ul>null</ul>, </li> <li> <ul> "ps_currency"</ul>: <ul>980</ul>, </li> <li> <ul> "ps_data"</ul>: <ul>null</ul>, </li> <li> <ul> "shop_amount"</ul>:<ul> 10.0</ul>, </li> <li> <ul> "shop_currency"</ul>: <ul>980</ul>, </li> <li> <ul> "shop_id"</ul>:<ul> 3</ul>, </li> <li> <ul> "shop_order_id"</ul>:<ul> "101"</ul>, </li> <li> <ul> "shop_refund"</ul>: <ul>9.6</ul>, </li> <li> <ul> "status"</ul>:<ul> 2</ul>, </li> <li> <ul> "updated"</ul>:<ul> null</ul> </li> <li> ` },` </li> <li> <ul> "error_code"</ul>:<ul> 0</ul>, </li> <li> <ul> "message"</ul>:<ul> "Ok"</ul>, </li> <li> <ul> "result"</ul>:<ul> true </ul> </li> } </li> Где, client_price – сумма платежа; created – дата создания; description – наименование счета; is_overwritten – была ли изменена изначальная сумма платежа amount. При значении true сумма платежа была изменена и отличается от изначальной; is_unique – уникальность номера платежа; payment_id – идентификатор платежа; payway – платежное направление; processed – дата проведения платежа; ps_currency – валюта и время выставленного счета; ps_data – дополнительная информация от платежной системы, например аккаунт плательщика; shop_amount – сумма счета, переданная магазином; shop_currency – валюта счета, зачислемая в магазин; shop_id – идентификатор магазина в системе Qostiq; shop_order_id – номер счета на стороне магазина; shop_refund – сумма зачисления на баланс магазина, в валюте счета; status – Статус счета: Created = 1; Waiting = 2; PsCreatingError = 3; Success = 4; CallbackError = 5; Rejected = 6; Refunded = 7; Hold = 8; IntRefunded = 9; Captured = 10. updated – дата и время последнего изменения статуса платежа. Внимание! Запрос статуса необходимо делать не чаще чем раз в 10 секунд. Если shop_order_id не уникален по операциям Invoice в рамках магазина, в ответе содержится "is_unique":false и метод возвращает информацию по последнему созданному Invoice. Запросить статус счета [POST] Request (application/json) ```json { "now": "2018-06-15 09:58:01.01", "shop_id": 1, "shop_order_id": "123456789", "sign": "32b2c32caa8adecf89c6dfa72ffca3a0506f33febfe3aaab090cdbfbd0e8b953" } ``` Response 200 () ```json { "data": { "client_price": 10.2, "created": "2018-06-18 17:22:49", "description": "Test+invoice", "is_overwritten": false, "is_unique": false, "payment_id": 11639480, "payway": "card_uah", "processed": null, "ps_currency": 980, "ps_data": null, "shop_amount": 10.0, "shop_currency": 980, "shop_id": 3, "shop_order_id": "101", "shop_refund": 9.6, "status": 2, "updated": null }, "error_code": 0, "message": "Ok", "result": true } ``` Статус операций Invoice [/invoice/allstatuses] Если платеж успешно создан, то в ответе вернется уникальный идентификатор платежа и его статус. Статус может быть финальным и не финальным, при не финальном статусе необходимо делать запроса статуса до получения финального статуса. Status Значение Описание Финальный? 1 Created Создан запрос на платеж Нет, 2 Waiting Платеж находится в стадии ожидания действий пользователя Нет, 3 PsCreatingError Ошибка создания платежа на стороне платежной системы Нет, 4 Success Оплата успешно выполнена Да, 5 CallbackError Ошибка получения уведомления об оплате со стороны платежной системы Нет, 6 Rejected Отклонен на стороне платежной системы *Да, 7 Refunded Сумма счета возвращена плательщику платежной системой Да, 8 Hold Средства по оплате счета удержаны (холдирование) платежной системой Нет, 9 IntRefunded Сумма счета возвращена плательщику системой Qostiq Да, 10 Captured Средства по оплате счета заблокированы платежной системойx Нет, *Внимание! Статус Rejected может быть сменен на Success. Запросить статус счета [POST] Request (application/json) ```json { "now": "2018-06-15 09:58:01.01", "shop_id": 1, "shop_order_id": "123456789", "sign": "32b2c32caa8adecf89c6dfa72ffca3a0506f33febfe3aaab090cdbfbd0e8b953" } ``` Response 200 () ```json { "data": { "client_price": 10.2, "created": "2018-06-18 17:22:49", "description": "Test+invoice", "is_unique": false, "payment_id": 11639480, "payway": "card_uah", "processed": null, "ps_currency": 980, "ps_data": null, "shop_amount": 10.0, "shop_currency": 980, "shop_id": 3, "shop_order_id": "101", "shop_refund": 9.6, "status": 2, "updated": null }, "error_code": 0, "message": "Ok", "result": true } ``` Group Создание выплаты Общие рекомендации по работе с API для создания выплат Убедитесь, что Ваш магазин активирован и настроен для работы по API: получен ID магазина, указан URL взаимодействия, сгенерирован секретный ключ и указаны IP адреса ваших сервисов. Payway платежных направлений для совершения выплат и их особенности работы Вы можете найти в личном кабинете в настройках магазина в разделе «Направления вывода». Процесс совершения выплаты с магазина выглядит следующим образом: Отправляется запрос на предварительный расчет и получении дополнительных параметров для дальнейшего создания выплаты, метод withdraw/try; Если result == ok, отправляется запрос на предварительную проверку существования и возможности пополнения аккаунта, по указанному платежному направлению (при необходимости указываются дополнительные параметры, полученные из предыдущего запроса из account_info_config); При получении result == true, отправляется запрос на создание выплаты по проверенному аккаунту (с указанной дополнительной информацией в account_info_config, при необходимости). При получении result==error, необходимо анализировать сообщение об ошибке в message. В ответе возвращается информация с созданной заявкой на выплату, с указанием сумм и идентификатором выплаты. При этом происходит замораживание части баланса на кошельке магазина, с которого осуществляется выплата, до получения финального статуса по выплате. После создания выплаты, необходимо делать запрос статуса по созданной выплате, до получения финального состояния. После получения финального статуса выплата считается завершенной и средства списываются с баланса магазина (или возвращаются на баланс, если выплату завершить не удалось). Предварительный расчет выплаты [/withdraw/try] Withdraw/try.Данный метод не является обязательным для создания заявки на выплату. Возвращает дополнительную информацию для создания withdraw и предварительный расчет по комиссиям. URL: https://core.qostiq.com/withdraw/try Метод: POST Обязательные параметры:amount_type, shop_currency, payway, amount, shop_id, sign Пример запроса: { "amount_type" :"ps_amount" , "shop_currency" :980 , "sign" :"f97c52fa8d273a9d3ad37e86e6dab314a592281654104ac9f348f386c29a2953" , "payway" : "card_uah" , "amount" :0.5 , "shop_id" :112 } Где, Параметр Описание Формат Пример amount сумма получения или списания (зависит от amount_type) Number (Не больше 2х знаков после точки) 1, 1.0, 1.00 или "1.00" amount_type указывает на тип суммы, возможны значения: ps_amount – сумма к получению в платежной системе, shop_amount – сумма к списанию с баланса магазина String "ps_amount" или "shop_amount" payway направление для выплаты, можно узнать в личном кабинете или у курирующего менеджера. Валюта получения зависит от указанного направления для выплаты String "card_uah" shop_currency валюта списания с магазина, Integer 980 - Украинская гривна, 840 - Доллар США, 978 - Евро shop_id идентификатор магазина, с которого осуществляется выплата Integer 112 sign сформированая подпись String "f97c52fa8d273a9d3ad37e86e6dab314a592281654104ac9f348f386c29a2953" Пример ответа: { `"data"`:` {` `"account_info_config"`:` {` `"account"`:` {` ` "regex"`:` "^((4|5|6)[0-9]{15,17}|[a-z0-9]{32})$"`, "title" : "Номер карты без пробелов" `}` `}`, `"info"`: `{}`, "payee_receive" : 1 , "ps_currency" : 980 , "shop_currency" : 980 , "shop_write_off" : 1.01 `}`, "error_code" : 0 , "message" : "Ok" , "result" : true } Где, account_info_config- информация об аккаунте, в том числе регулярное выражение, которому должен соответствовать аккаунт. Также может возвращаться информация о дополнительных параметрах, для передачи их по платежному направлению; title– название поля аккаунта; regex– регулярное выражение для аккаунта; ps_currency– валюта платежного направления для вывода, формат: международные коды валют, 980; payee_receive– сумма к получению в платежной системе, в валюте платежного направления, формат: 1.0; shop_currency– валюта кошелька магазина, с которого производиться выплата, формат: международный формат валют, 980 shop_write_off– сумма списания с баланса магазина, в валюте кошелька, формат: 1.0; Запросить расчет выплаты[POST] для демонстрации запроса в правом окне смените Production на Mock Server Request (application/json) ```json { "amount_type":"ps_amount", "shop_currency":980, "sign":"f97c52fa8d273a9d3ad37e86e6dab314a592281654104ac9f348f386c29a2953", "payway": "card_uah", "amount":1, "shop_id":112 } ``` Response 200 () ```json { "data": { "account_info_config" { "account": { "regex": "^((4|5|6)[0-9]{15,17}|[a-z0-9]{32})$", "title": "Номер карты без пробелов" } } "payee_receive": 1, "ps_currency": 980, "shop_currency": 980, "shop_write_off": 1.02 }, "error_code": 0, "message": "Ok", "result": true } ``` Проверка аккаунта [/check_account] Проверка аккаунта на возможность пополнения check_account. Данный метод не является обязательным для создания заявки на выплату, но рекомендованный к выполнению перед запросом withdraw/create. Возвращает информацию по аккаунту, на который создается заявка на выплату. URL: https://core.qostiq.com/check_account Метод: POST Обязательные параметры: shop_id, sign, payway, account, amount. Если в ответе withdraw/try в поле account_info_config были дополнительные параметры, кроме account, они должны передаваться в поле account_details (в формировании подписи не участвует) Пример запроса: { "account" : "test_acc" , `"account_details"`:` {` "contract" : "C1234" `}`, "sign" : "faf7ee6db712752f2b107e05328bbd0d" , "payway" : card_uah , "amount" : 10.5 , "shop_id" : 1 } Где, Параметр Описание Формат Пример amount сумма планируемого зачисления на аккаунт в валюте платежного направления, данная информация необходима для более точной проверки о возможности зачисления, т.к. за частую на аккаунтах получателей устанавливаются лимиты пополнения Number (Не больше 2х знаков после точки) 1, 1.0, 1.00 или "1.00" account основной аккаунт для проверки на возможность пополнения, для каждого платежного направления может быть свой (информацию можно уточнить в личном кабинете) String "4111111111111111" payway направление для выплаты, можно узнать в личном кабинете или у курирующего менеджера. Валюта получения зависит от указанного направления для выплаты String "card_uah" shop_id идентификатор магазина, с которого осуществляется выплата Integer 112 sign сформированная подпись String "f97c52fa8d273a9d3ad37e86e6dab314a592281654104ac9f348f386c29a2953" account_details– дополнительная, обязательная информация для проверки аккаунта, данном примере это contract – номер договора аккаунта; Пример ответа: `{` `"data"`:` {` `"account_info"`: `{` "verified" : "true" `}`, "provider_status" : 1 , "result" : true `}`, "error_code" : 0 , "message" : "Ok" , "result" : true } Где, result- результат проверки возможности пополнения на аккаунт, формат: true, false provider_status- статус ответа провайдера, на запрос проверки возможности пополнения аккаунта, формат: 1 - провайдер доступен, проверка прошла без ошибок; 2 - ошибка на провайдере, результат проверки неизвестен; 3 - ошибка при обработке запроса, результат проверки неизвестен; account_info- дополнительная информация, возвращаемая от провайдера услуги, можно отображать плательщику, так как зачастую содержит его персональную информацию, например, ФИО владельца аккаунта; Запросить проверку[POST] Request (application/json) ```json { "account": "4111111111111111", "sign":"fcf9544776bb27ddd4b0b48482a4e0c35b0c54b7db5b7ea2553c2e2ac350d536", "payway": "card_uah" "amount":1, "shop_id":112 } ``` Response 200 () ```json { "data": { "account_info": null, "provider_status": 1, "result": true }, "error_code": 0, "message": "Ok", "result": true } ``` Создание вывода средств [/withdraw/create] Withdraw. Данный метод применяется для создания вывода средств в других валютах с баланса магазина на другие платежные системы. URL: https://core.qostiq.com/withdraw/create Метод: POST Обязательные параметры: account, amount_type, amount, payway, shop_currency, shop_id, shop_payment_id, sign Shop_payment_id должен быть уникальным для каждого нового платежа. В запросе могут передаваться дополнительные параметры, например, description – описание выплаты, или account_details – дополнительная информацию по аккаунту для выплаты (зависит от платежного направления). Пример запроса: { "account" : "test acc" , "amount" : 1 , "amount_type" : "ps_amount" , "payway" : card_uah , "shop_currency" : 840 , "shop_id" : 1 , "shop_payment_id" : "2e18aadc-cf87-4cdd-9a08-9a57f9ac4066" , "sign" : "9505e9fa97e8910a8b1d2797c348aae5d35f7846ad901cc5fc91d2afbdc978e3" } Параметр Описание Формат Пример account aккаунт получателя средств в платежной системе, например номер карты; String "4111111111111111" amount сумма получения или списания (зависит от amount_type) Number (Не больше 2х знаков после точки) 1, 1.0, 1.00 или "1.00" amount_type указывает на тип суммы, возможны значения: ps_amount – сумма к получению в платежной системе, shop_amount – сумма к списанию с баланса магазина String "ps_amount" или "shop_amount" payway направление для выплаты, можно узнать в личном кабинете или у курирующего менеджера. Валюта получения зависит от указанного направления для выплаты String "card_uah" shop_currency валюта списания с магазина, Integer 980 - Украинская гривна, 840 - Доллар США, 978 - Евро, shop_id идентификатор магазина, с которого осуществляется выплата Integer 1 shop_payment_id уникальный идентификатор платежа на стороне магазина String "2e18aadc-cf87-4cdd-9a08-9a57f9ac4066" callback_url URL для приема уведомления по операции (необязательный параметр, подробно об уведомлениях по выплатам) String "https://shop.com/withdraw/callback" Пример запроса с дополнительными параметрами: { "account" : "test acc" , `"account_details"`:` {` "fname" : "ksu" , "lname" : "ksu" `}`, "amount" : 1 , "amount_type" : "ps_amount" , "description" : "Test desc" , "email" : "test@email.com" , "payway" : card_uah , "shop_currency" : 840 , "shop_id" : 1 , "shop_payment_id" : "63288d86-241c-418e-94b8-db4bbf5026fe" , "sign" : "2d9270de3c0ae94ff6571991cc2ea3a3e1c4c53265e2e76a74f1f76e4d465127" } Где, account_details – дополнительный параметр, для детализации информации по аккаунту получателя средств (зависит от выбранного направления для выплат). Список полей можно посмотреть в личном кабинете по каждому направлению; description – дополнительный параметр, описание выплаты, сохраняется в истории платежа и передается в назначении, если платежная система имеет такую функцию; email – дополнительный параметр, не участвует в формировании подписи. Пример ответа: { `"data"`:` {` "balance" : 0.0 , "id" : 1 , "payee_receive" : 1 , "ps_currency" : 840 , "shop_currency" : 840 , "shop_payment_id" : "63288d86-241c-418e-94b8-db4bbf5026fe" , "shop_write_off" : 1.05 , "status" : 5 `}`, "error_code" : 0 , "message" : "Ok" , "result" : true } Где, balance – баланс магазина, после успешного создания выплаты; id – уникальный идентификатор платежа на стороне Qostiq; payee_receive – сумма к получению на счет в валюте ps_currency; ps_currency – валюта получения на счет суммы payee_receive; shop_currency – валюта списания с магазина суммы shop_write_off; shop_payment_id – уникальный идентификатор платежа на стороне магазина; shop_write_off – сумма списания с магазина в валюте shop_currency; status – статус выплаты. Рекомендации по отправке запросов на создание и проверку выплат 1. Если на запрос создания выплаты получили time out, то необходимо сделать запроса статуса по номеру платежа магазина /withdraw/shop_payment_status и, если в ответе вернулась ошибка, что такого платежа нет можно повторить запрос на создание выплаты. Если в ответе вернулся статус выплаты, то значит она была создана и надо ориентироваться на данный статус. Примечание: в системе присутствует защита от дублирования на создания выплат, shop_payment_id должен быть уникальным в рамках одного магазина 2. Рекомендуемая частота проверки статуса платежей – не чаще чем 1 запросов в 60 секунд, т.к. многим платежным система так же требуется время на обработку платежа. 3. Причину отклонения выплаты можно увидеть в параметре "rejected_reason" который возвращается в запросах на создание выплаты и запросах статуса выплаты. Вывести средства с магазина [POST] для демонстрации запроса в правом окне смените Production на Mock Server Request (application/json) ```json { "account": "test_acc", "amount": 1, "amount_type": "ps_amount", "payway": "card_uah", "shop_currency": 980, "shop_id": 112, "shop_payment_id": "63288d86-241c-418e-94b8-db4bbf5026f", "sign": "b4c3ca4b403bb065db1fe716b9cbf5138e3dabc7bc5d385750b3fa852ed97d46" } ``` Response 200 () ```json { "data": { "balance": 0.0, "id": 11298076, "payee_receive": 1, "ps_currency": 980, "shop_currency": 980, "shop_payment_id": "63288d86-241c-418e-94b8-db4bbf5026f", "shop_write_off": 1.02, "status": 3 }, "error_code": 0, "message": "Ok", "result": true } ``` Запрос статуса по withdraw_id [/withdraw/status] URL: https://core.qostiq.com/withdraw/status Метод: POST Обязательные параметры: now, shop_id, withdraw_id Данный запрос позволяет получить статус выплаты по идентификатору транзакции платежной системы withdraw_id Пример запроса: { "now" : "2017-05-16 16:56:25.009469" , "shop_id" : 112 , "withdraw_id" : 11298076 , "sign" : "e1dfc97b2c5430e21be08b1140f25259aa1865d56e166ee398c2368ad39712f7" } Где, Параметр Описание Формат Пример now время запроса String "2017-05-16 16:56:25.009469" shop_id идентификатор магазина в системе Qostiq Integer 112 withdraw_id уникальные идентификатор выплаты на стороне Qostiq, для которого необходимо узнать статус, формат integer (возвращается в параметре id, при успешно созданном платеже на запрос withdraw/create) Integer 11298076 sign подпись String "e1dfc97b2c5430e21be08b1140f25259aa1865d56e166ee398c2368ad39712f7" Пример ответа: { `"data"`:` {` "id" : 11298076 , "payee_receive" : 1 , "ps_currency" : 980 , "rejected_reason": "Номер карты не существует. Пожалуйста, проверьте правильность номера" , "shop_currency" : 980 , "shop_payment_id" : "63288d86-241c-418e-94b8-db4bbf5026f11" , "shop_write_off" : 1.02 , "status" : 6 `}`, "error_code" : 0 , "message" : "Ok" , "result" : true } Где, status – актуальный статус выплаты (см. таблицу «Статусы выплаты»); shop_payment_id – идентификатор выплаты на стороне магазина; shop_currency – валюта магазина; ps_currency – валюта получения в платежной системе; payee_receive – сумма зачисленная на баланс получателя в валюте ps_currency; shop_write_off – сумма списания с магазина в валюте shop_currency; id – уникальные идентификатор выплаты в системе Qostiq. rejected_reason – причина отмены выплаты. Пример ответа при ошибке: { "error_code" : 2000 , "message" : "Withdraw (id=3) wasn't found" , "data" : None , "result" : False } Запросить статус выплаты [POST] Request (application/json) ```json { "now": "2017-01-23 16:56:25.009469", "shop_id": 112, "withdraw_id": 11298076, "sign": "e1dfc97b2c5430e21be08b1140f25259aa1865d56e166ee398c2368ad39712f7" } ``` Response 200 () ```json { "data": { "id": 11298076, "payee_receive": 1, "ps_currency": 980, "shop_currency": 980, "shop_payment_id": "63288d86-241c-418e-94b8-db4bbf5026f", "shop_write_off": 1.02, "status": 5 }, "result": True, "error_code": 0, "message": "Ok" } ``` Запрос статуса по shop_payment_id [/withdraw/shop_payment_status] URL: https://core.qostiq.com/withdraw/shop_payment_status Метод: POST Обязательные параметры: now, shop_payment_id, shop_id Данный запрос позволяет получить статус выплаты по идентификатору транзакции магазина shop_payment_id Пример запроса: { "shop_id" : 112 , "shop_payment_id" : "63288d86-241c-418e-94b8-db4bbf5026f" , "now" : "2011-12-06 16:07:28.878200" , "sign" : "a1ab593500a4ab146abe33121ad9f08397beaef5f4ba9279ca6e1eee1c6b0bc1" } Где, Параметр Описание Формат Пример now время запроса String "2011-12-06 16:07:28.878200" shop_id идентификатор магазина в системе Qostiq Integer 112 shop_payment_id идентификатор транзакции на стороне магазина String "63288d86-241c-418e-94b8-db4bbf5026f" sign подпись String "e1dfc97b2c5430e21be08b1140f25259aa1865d56e166ee398c2368ad39712f7" Параметры ответа: status – актуальный статус выплаты (см. таблицу «Статусы выплаты»); shop_payment_id – идентификатор выплаты на стороне магазина; shop_currency – валюта магазина; ps_currency – валюта получения в платежной системе; payee_receive – сумма зачисленная на баланс получателя в валюте ps_currency; shop_write_off – сумма списания с магазина в валюте shop_currency; id – уникальные идентификатор выплаты в системе Qostiq. Пример ответа при ошибке: { "error_code": 2000, "message": "Withdraw (id=3) wasn't found", "data": None, "result": False } Запросить статус выплаты по транзакции [POST] Request (application/json) ```json { "shop_id":112, "shop_payment_id": "63288d86-241c-418e-94b8-db4bbf5026f", "now": "2011-12-06 16:07:28.878200", "sign": "a1ab593500a4ab146abe33121ad9f08397beaef5f4ba9279ca6e1eee1c6b0bc1" } ``` Response 200 () ```json { "data": { "id": 11298076, "payee_receive": 1, "ps_currency": 980, "shop_currency": 980, "shop_payment_id": "63288d86-241c-418e-94b8-db4bbf5026f", "shop_write_off": 1.02, "status": 5 }, "result": True, "error_code": 0, "message": "Ok" } ``` Уведомление по выплате [/withdraw/callback] После финализации выплаты, система Qostiq производит отправку уведомления магазину на указанный в настройках URL взаимодействия. Также URL для приема уведомления по выплате можно передать в дополнительном параметре callback_url в запросе создания выплаты /withdraw/create. Уведомления отправляются с IP-адресов: 34.90.243.164 34.147.48.238 34.90.176.128 34.90.34.134 35.242.192.50 34.90.247.48 34.90.185.30 34.147.69.92 35.198.183.103 35.234.123.199 34.159.7.106 Необходимо обязательно сверять значения из уведомления со значениями в созданой выплате и проверять подпись в уведомлении. Важно! Всегда сверяйте суммы операции и номера операций - shop_payment_id, "shop_write_off", payee_receive при получении уведомления. Метод: POST, Content-Type=application/json Пример уведомления: { `"account_details"`: `{"customer_id": "12345678"}`, "callback_type" : "withdraw" , "created" : "2024-11-18 13:41:57" , "description" : "example" , "payee_receive" : 10.5 , "payment_id" : 64045 , "payway" : "card_usd" , "processed" : "2024-11-18 13:45:38" , "ps_currency" : 840 , "shop_currency" : 840 , "shop_id" : 1 , "shop_payment_id" : "12345678" , "shop_write_off" : 11.5 , "sign" : "e02baf7a7be1c591f2ad8f44dc25e7df8324bef1f109765659b3633839441584" , "status" : "success" } Где, callback_type – тип операции, по которой пришло уведомление, "withdraw" для фиатной выплаты; created – дата и время создания выплаты; description – описание выплаты, переданное при создании; payee_receive – сумма к получению на счет в валюте ps_currency; payment_id – уникальный идентификатор выплаты на стороне Qostiq; payway – платежное направление в системе Qostiq, по которому создана выплата; processed – дата и время изменения статуса выплаты; ps_currency – валюта получения на счет суммы payee_receive; shop_currency – валюта списания с магазина суммы shop_write_off; shop_id – уникальный идентификатор магазина, который создал выплату; shop_payment_id – уникальный идентификатор платежа магазина, который создал выплату; shop_write_off – сумма списания с магазина в валюте shop_currency; sign – подпись; status – статус выплаты: success – выплата успешна, rejected – выплата отклонена; test_add_on – любой пользовательский параметр, переданный магазином при создании выплаты. Подпись формируется по тому же алгоритму, что и при выставлении счета, но в формировании подписи участвуют уже все параметры, значение которых не null и пустая строка. При корректном получении и обработке уведомления, необходимо вернуть в ответ http статус 200 и тело сообщения OK. В ином случае уведомления будут высылаться повторно, с увеличивающемся интервалом, всего 25 попыток, последнее по истечении суток. Пример строки, по которой необходимо сгенерировать подпись {"customer_id":"12345678"}:withdraw:2024-11-18 13:41:57:example:10.5:64045:card_usd:2024-11-18 13:45:38:840:840:1:12345678:11.5:successTestkey1 Пример уведомления по успешному платежу [POST] Request (application/json) ```json { "account_details": {"customer_id": "12345678"}, "callback_type": "withdraw", "created": "2024-11-18 13:41:57", "description": "example", "payee_receive": 10.5, "payment_id": 64045, "payway": "card_usd", "processed": "2024-11-18 13:45:38", "ps_currency": 840, "shop_currency": 840, "shop_id": 1, "shop_payment_id": "12345678", "shop_write_off": 11.5, "sign": "e02baf7a7be1c591f2ad8f44dc25e7df8324bef1f109765659b3633839441584", "status": "success" } ``` Response 200 () OK Пример уведомления по неуспешному платежу [POST] Request (application/json) ```json { "account_details": {"customer_id": "12345678"}, "callback_type": "withdraw", "created": "2024-11-18 13:41:57", "description": "example", "payee_receive": 10.5, "payment_id": 64045, "payway": "card_usd", "processed": "2024-11-18 13:45:38", "ps_currency": 840, "shop_currency": 840, "shop_id": 1, "shop_payment_id": "12345678", "shop_write_off": 11.5, "sign": "e02baf7a7be1c591f2ad8f44dc25e7df8324bef1f109765659b3633839441584", "status": "rejected", } ``` Response 200 () OK Статусы выплат [/withdraw/allstatuses] Если выплата успешна создана, то в ответе вернется уникальный идентификатор платежа и его статус. Статус может быть финальным и не финальным, при не финальном статусе необходимо делать запроса статуса до получения финального статуса. Status Значение Описание Финальный? 1 Created Платеж создан, ожидает обработки Нет, делать запрос статуса 2 WaitingManualConfirmation Ожидает ручного подтверждения оператора Нет, делать запрос статуса 3 PsProcessing Отправлен на платежную систему Нет, делать запрос статуса 4 PsProcessingError Ошибка при выплате на стороне платежной системы Нет, делать запрос статуса или обратиться в поддержку 5 Success Успешно выполнен Да, средства списаны с магазина 6 Rejected Отклонен на стороне платежной системы Да, средства не списаны с магазина 7 ManualConfirmed Подтвержден оператором и ожидает проводки Нет, делать запрос статуса 9 PsNetworkError Сетевая ошибка на стороне платежной системы Нет, делать запрос статуса 10 CanceledManually Вывод отменен вручную на стороне системы Qostiq Да,финальный статус 11 Refunded Успешный вывод отменен вручную на стороне системы Qostiq Да,финальный статус Возвращение неуспешного статуса по запросу [POST] Request (application/json) ```json { "now": "2020-01-19 15:11:18.34", "shop_id": "112", "sign": "e007c7641984e74620de9ee0f151aca845f0e0be1a96743ea154db9f0a2853ab", "withdraw_id": "25161103" } ``` Response 200 () ```json { "data": null, "error_code": 7, "message": "Withdraw (id=25161103) wasn't found", "result": false } ``` Group Прочие методы по магазину Запрос на регистрацию аккаунта [/registration] Запрос для активации магазина URL: https://core.qostiq.com/account/register Метод: POST Обязательные параметры: now, shop_id, email Формат даты - dd.mm.YYYY hh:mm:ss Пример запроса: <li> { <li> <ul> "shop_id"</ul>:<ul> 1</ul>,</li> <li> <ul> "now"</ul>: <ul>"30.06.2017 10:12:44"</ul>,</li> <li> <ul> "email"</ul>: <ul>"example@email.com"</ul>,</li> <li> <ul> "sign"</ul>:<ul> "32b2c32caa8adecf89c6dfa72ffca3a0506f33febfe3aaab090cdbfbd0e8b953"</ul></li> }</li> Где, обязательные параметры: Параметр Описание Формат Пример now время запроса String "30.06.2017 10:12:44" shop_id идентификатор магазина в системе Qostiq Integer 1 email почта регистрации кошелька String "example@email.com" sign подпись String "32b2c32caa8adecf89c6dfa72ffca3a0506f33febfe3aaab090cdbfbd0e8b953" Пример ответа: <li> { <li> ` "data"`:` {`</li> <li> <ul> "account_number"</ul>:<ul> "201499789419"</ul>,</li> <li> <ul> "email"</ul>: <ul>"example@email.com" </ul></li> <li> ` }`,</li> <li> <ul> "error_code"</ul>: <ul>0</ul>,</li> <li> <ul> "message"</ul>: <ul>"Ok"</ul>,</li> <li> <ul> "result"</ul>: <ul>true</ul></li> }</li> Отправить запрос на регистрацию аккаунта [POST] Request (application/json) ```json { "now":"30.06.2017 10:12:44", "email":"nevu77@carbtc.net", "shop_id":3, "sign":"bd4889102893c7f764c95ae3ed30b1d4fcb4fc01ca2ccbe5344b50ffdb64fe73" } ``` Response 200 () ```json { "data": { "account_number": "201499789419", "email": "example@email.com" }, "error_code": 0, "message": "Ok", "result": true } ``` Запрос баланса [/balance_request] Для получения актуального баланса по магазину URL: https://core.qostiq.com/shop_balance Метод: POST Обязательные параметры: now, shop_id Пример запроса: { "now" : "2017-05-17 10:48:45.509731" , "shop_id" : 1 , "sign" : "361f6310a04ef858df0847d1e2f6669ea61159a5c80d0ed6dcf17329751b4ef9" } Где, Параметр Описание Формат Пример now время запроса String "2017-05-17 10:48:45.509731" shop_id идентификатор магазина в системе Qostiq Integer 1 sign подпись String "361f6310a04ef858df0847d1e2f6669ea61159a5c80d0ed6dcf17329751b4ef9" Пример ответа: { ` "data"`: `{` "shop_id" : 1 , `"balances"`:` [{` "available" : 28.1 , "currency" : 980 , "hold" : 0.0 , "frozen" : 20.0 "rolling_reserve" : 15.0 ` }`, ` {` "available" : 0.0 , "currency" : 978 , "hold" : 0.0 , "frozen" : 0.0 "rolling_reserve" : 15.0 ` }`, `{` "available" : 0.0 , "currency" : 840 , "hold" : 0.0 , "frozen" : 0.0 "rolling_reserve" : 15.0 `}]` ` }`, "result" : True , "error_code" : 0 , "message" : "Ok" } Где, balances – баланс магазина в разрезе валют; currency – валюта баланса (Формат: 980, 840, 978); available – доступный баланс магазина; frozen – замороженные средства на балансе, например, под созданную выплату, которая находится в обработке; hold– временно удержанные средства, например, при проверке входящего поступления; rolling_reserve – временное удержание денежных средств на балансе магазина. Общий баланс магазина соответствует сумме available, frozen и hold в указанной валюте. Для выплат доступны средства available за исключением rolling_reserve. Запросить баланс [POST] Request (application/json) ```json { "now": "2017-12-06 12:31:19.500060", "shop_id": 112, "sign": "77c6cc948751ee5c13a68e5301c1f85f222e9e3333f4fefb987eb9632732c90b" } ``` Response 200 () ```json { "data": { "shop_id": 112, "balances": [{ "available": 28.1, "currency": 980, "hold": 0.0, "frozen": 20.0 }, { "available": 0.0, "currency": 978, "hold": 0.0, "frozen": 0.0 }, { "available": 0.0, "currency": 840, "hold": 0.0, "frozen": 0.0 }] }, "result": True, "error_code": 0, "message": "Ok" } ``` Получение доступных методов Invoice [/available_payment_methods_invoice ] URL: https://core.qostiq.com/shop_input_config/shop Метод: POST Обязательные параметры: now, shop_id Пример запроса: <li> { <li> <ul>"now"</ul>:<ul>"03.09.2018 11:19:55"</ul>, </li> <li><ul>"shop_id"</ul>:<ul>3</ul>,</li> <li><ul>"sign"</ul>:<ul>"588485c9d7f0d7fb3445e620450ca303ae11e35e159002bc33d2174398f9134c"</ul></li> }<li> Где: Параметр Описание Формат Пример now время запроса String "2018-06-15 09:58:01.01" shop_id идентификатор магазина в системе Qostiq Integer 3 sign подпись String "588485c9d7f0d7fb3445e620450ca303ae11e35e159002bc33d2174398f9134c" Пример ответа: { "data" : [ ` { ` "id" : 3 , "name" : "Visa/MC" , "payways" : [ `{ ` "add_ons_config" : null , "alias" : "card_uah" , "currency" : 980 , `"fee_config"`:` { ` "fix" : 0.0 , "percent" : 6.0 `}, ` `"fee_part_config"`:` { ` "fix_part" : 0 , "percent_part" : 1.0 ` }`, "id" : 154 , "is_active" : true , "max_amount" : 100000.0 , "min_amount" : 1.0 ` }`, ] , "rating" : 2 ` }`, ] "error_code" : 0 , "message" : "Ok" , "result" : true } Где, id – ID платежного метода; name – наименование Платежного метода; payways - платежные направления, которые включены магазину; add_ons_config - дополнительная информация, если она требуется по платежному направлению; alias - наименование платежного направления; currency - валюта в разрезе платежного направления (Формат: 980, 840, 978); fee_config - размер комиссии; fix - фиксированная комиссия; percent - процентная комиссия ; fee_part_config - настройки распределения комисии между магазином и плательщиком; fix_part - распределение фиксированной комиссии (0 - на плательщике, 1 - на магазине); percent_part - распределение процентной комиссии (0,0-1,0); id - Id платежного направления; is_active - статус активации (True, False); max_amount - максимальная сумма платежа в разрезе направления; min_amount - минимальная сумма платежа в разрезе направления. Запросить платежные методы доступные магазину Invoice[POST] Request (application/json) ```json { now":"03.09.2018 11:19:55", "shop_id":3, "sign":"588485c9d7f0d7fb3445e620450ca303ae11e35e159002bc33d2174398f9134c" } ``` Response 200 () ```json { "data": [ { "id": 3, "name": "Visa/MC", "payways": [ { "add_ons_config": null, "alias": "card_uah", "currency": 980, "fee_config": { "fix": 0.0, "percent": 6.0 }, "fee_part_config": { "fix_part": 0, "percent_part": 1.0 }, "id": 154, "is_active": true, "max_amount": 100000.0, "min_amount": 1.0 }, ], "rating": 2 }, ] "error_code": 0, "message": "Ok", "result": true } ``` Получение доступных методов Withdraw [/available_payment_methods_withdraw ] URL: https://core.qostiq.com/shop_output_config/shop Метод: POST Обязательные параметры: now, shop_id Пример запроса: <li>{ <li> <ul>"now"</ul>:<ul>"03.09.2018 11:19:55"</ul>,</li> <li><ul>"shop_id"</ul>:<ul>3</ul>, </li> <li> <ul>"sign"</ul>:<ul>"588485c9d7f0d7fb3445e620450ca303ae11e35e159002bc33d2174398f9134c"</ul></li> }</li> Где, Параметр Описание Формат Пример now время запроса String "2018-06-15 09:58:01.01" shop_id идентификатор магазина в системе Qostiq Integer 3 sign подпись String "588485c9d7f0d7fb3445e620450ca303ae11e35e159002bc33d2174398f9134c" Пример ответа: { "data" : [ ` { ` "id" : 1 , "name" : "Visa/MC" , "payways" : [ ` {` ` "account_info_config"`: `{` ` "account"`:` { ` ` "regex"`:` "^(4|5|6)[0-9]{15,17}$",` "title" : "Номер карты" ` } ` ` }`, "alias" : "card_uah" , "currency" : 980 , ` "fee_config"`: `{ ` "fix" : 10.0 , "percent" : 1.5 ` },` "info_id" : null , "max_amount" : 14999.0 , "min_amount" : 1.0 ` } ` ] , "rating" : 1 ` }`, ` { ` "id" : 3 , "is_transfer_config" : true, "name" : "Qostiq", "payways" : [ ` { ` ` "account_info_config"`: `{ ` ` "payee_account"`:` { ` ` "regex"`: `"^20[\\d]{10}$|^([a-zA-Z0-9_-]+\\.)*[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)*\\.[a-zA-Z]{2,6}$", ` "title" : "Номер кошелька или email" ` }` `}`, "alias" : "qostiq_usd" , "currency" : 980 , ` "fee_config"`: ` {` "fix" : 0.0 , "percent" : 0.0 ` }`, "info_id" : null , "max_amount" : 10000.0 , "min_amount" : 0.5 ` }`, ] , "rating" : 22 ` } ` ] , "error_code" : 0 , "message" : "Ok" , "result" : true } Где, id – ID платежного метода; name – наименование Платежного метода; payways - платежные направления, которые включены магазину; add_ons_config - дополнительная информация, если она требуется по платежному направлению; alias - наименование платежного направления; currency - валюта в разрезе платежного направления (Фрмат: 980, 840, 978); fee_config - размер комиссии; fix - фиксированная комиссия; percent - процентная комиссия ; fee_part_config - настройки распределения комисии между магазином и плательщиком; fix_part - распределение фиксированной комиссии (0 - на плательщике, 1 - на магазине); percent_part - распределение процентной комиссии (0,0-1,0); id - Id платежного направления; is_active - статус активации (True, False); max_amount - максимальная сумма платежа в разрезе направления; min_amount - минимальная сумма платежа в разрезе направленияє; is_transfer_config": true - признак указывающий, что это Transfer (перевод на кошельки Qostiq), для выплат нужно использовать метод api transfer. Запросить доступные методы Withdraw[POST] Request (application/json) ```json { now":"03.09.2018 11:19:55", "shop_id":3, "sign":"588485c9d7f0d7fb3445e620450ca303ae11e35e159002bc33d2174398f9134c" } ``` Response 200 () ```json { "data": [ { "id": 1, "name": "Visa/MC", "payways": [ { "account_info_config": { "account": { "regex": "^(4|5|6)[0-9]{15,17}$", "title": "Номер карты" } }, "alias": "card_uah", "currency": 980, "fee_config": { "fix": 10.0, "percent": 1.5 }, "info_id": null, "max_amount": 14999.0, "min_amount": 1.0 } ], "rating": 1 }, { "id": 3, "is_transfer_config": true, "name": "Qostiq", "payways": [ { "account_info_config": { "payee_account": { "regex": "^20[\\d]{10}$|^([a-zA-Z0-9_-]+\\.)*[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)*\\.[a-zA-Z]{2,6}$", "title": "Номер кошелька или email" } }, "alias": "qostiq_usd", "currency": 980, "fee_config": { "fix": 0.0, "percent": 0.0 }, "info_id": null, "max_amount": 10000.0, "min_amount": 0.5 }, ], "rating": 22 } ], "error_code": 0, "message": "Ok", "result": true } ``` Запрос доступности сервиса [/service_check] URL: https://core.qostiq.com/check_status Метод: POST Пример Ответа: { "status" : "OK" } Запросить доступность сервиса [POST] Request ```json { https://core.qostiq.com/check_status } ``` Response 200 () ```json { "status": "OK" } ``` ##Group Протокол взаимодействия Host2Host Взаимодействие по прооколу Host2Host позволяет производить процесс сбора карточных данных на стороне ресурса, в случае наличия сертификата PCI DSS. Взаимодействие между ресурсом с сервисом Qostiq осуществляется с помощью запросов по API. Для создания платежа методом Host2Host необходимо отправить запрос Invoice create. В ответе на запрос о создании счета возвращается ID session_id, который необходимо использовать для передачи карточных данных. Отправить запрос H2H Data для получения токена. В ответе на запрос возвращается токен form_token и URL payform_url, которые необходимо использовать для передачи карточных данных. После ответа на запрос H2H Data, необходимо сформировать и подтвердить HTML форму Pay Form на payform_url методом POST с данными карты плательщика ###Запрос H2H Data [/h2hdata] Test URL: https://test-core.tech-icard.com/h2h_data Production URL: https://core.tech-icard.com/h2h_data Метод: POST Обязательные параметры: session_id С помощью запроса H2H Data необходимо передать session_id. В ответе вернется токен form_token и URL payform_url, которые необходимо использовать для передачи карточных данных. Пример Запроса: { "session_id" :"26d90ef012e34b44aa9d74a3556e15a6" } Где: Параметр Описание Формат session_id ID полученный в ответе на запрос Invoice create string Пример ответа: { "data" : `{` "form_token" :"uerhdw47d748yd784dy83uhueh834h84dh84hd8dh8" , "payform_url" :https://card.qostiq.com/payform/ `},` "error_code": 0, "message": "success", "result": true } Где: Параметр Описание Формат form_token Токен для передачи карточных данных string payform_url URL для редиректа пользователя с карточными данными string Group Запрос H2H Data [POST] Request (application/json) ```json { "session_id":"26d90ef012e34b44aa9d74a3556e15a6" } ``` Response 200 () ```json { "data": { "form_token":"uerhdw47d748yd784dy83uhueh834h84dh84hd8dh8", "payform_url":"https://card.qostiq.com/payform", }, "error_code": 0, "message": "Ok", "result": true } ``` ###Формирование HTML формы Payform [/Payform] Метод: POST Обязательные параметры: session_id,card_number,card_holder,expiry_month,expiry_year,cvv,payform_url,form_token. Параметр session_id берется из ответа запроса Invoice create . После подтверждения HTML формы пользователь будет перенаправлен на страницу 3ds верификации. После прохождения 3ds пользователь будет возвращен на соответствующие success или failed URL, которые передаются в запросе Invoice create . Параллельно, вам будет отправлен callback. Если платеж неуспешен, то в callback вернется причина отказа, в случае ели она была передана шлюзом. Пример Формы: action="https://card.tech-icard.com/en/payform" method="POST" type="hidden" name="session_id" value="26d90ef012e34b44aa9d74a3556e15a6" type="hidden" name="form_token" value="uerhdw47d748yd784dy83uhueh834h84dh84hd8dh8" type="hidden" name="card_number" value="4111111111111111" type="hidden" name="card_holder" value="TEST TEST" type="hidden" name="expiry_month" value="12" type="hidden" name="expiry_year" value="22" type="hidden" name="cvv" value="123" type="submit" Параметр Описание Формат expiry_year год окончания действия карты 22 card_holder TEST TEST https://qostiq.com/failed/ card_number номер карты пользователяа 4111111111111111 expiry_month месяц окончания действия срока карты 12 cvv трёхзначный код проверки подлинности карты 123 session_id уникальный идентификатор операции оплаты 26d90ef012e34b44aa9d74a3556e15a6 form_token токен для передачи карточных даннх 0e61dd5935054d7e99d3da0cef411758 action URL для редиректа пользователя с карточными данными https://card.tech-icard.com/en/payform ###Отправить запрос PayForm [POST] Request ```json {'expiry_year': '**', 'cvv': '***', 'expiry_month': '**', 'card_number': '****************', 'card_holder': '************', 'sign': 'bcc0f7c61d0ef0f7063b1aef59989a0b7c0ac3daa8f5ae3fca85c28c436fb28a', 'session_id': '033695c6ba634e0c94533085c5c372ca'}", ``` Response 200 () ```json { https://tech-icard.com/ } ``` Group Рекурренты Рекуррентные платежи дают возможность выполнять регулярные списания денег с банковской карты покупателя без повторного ввода реквизитов карты и без участия плательщика для инициации очередного платежа. ВАЖНО: Данный функционал доступен только в случае согласования с менеджером. Иницииация первого платежа с признаком рекуррентности происходит по платежному направлению "payway": "card_uah" в несколько этапов: Для создания 1-го в цепочке платежа, в запросе Invoice/Create необходимо передать дополнительный параметр “required_pay_token”: “true”. На запрос поступит Callback с дополнительным параметром “pay_token” в поле “ps_data”. ВАЖНО: Параметр pay_token будет передаваться только в случае успешно проведенной транзакции. Для иницииации последующих списаний с карты в запросе Invoice/Create необходимо передать ранее полученный pay_token. ВАЖНО: В ответе на запрос вернется method: offline и url: offline - Это означает, что плательщика не нужно переадресовывать на страницу платежной системы. При этом запрос Invoice/Pay уже не запускается. Результат платежа приходит в Callback. Пример Запроса: Test URL: https://core.test-qostiq.com/invoice/create Production URL: https://core.qostiq.com/invoice/create Метод: POST Обязательные параметры: amount, currency, payway, shop_id, shop_order_id, “required_pay_token”: “true”, sign. <li>{</li> <li><ul>"amount":</ul> <ul>"1",</ul></li> <li><ul>"currency":</ul> <ul>"980",</ul></li> <li><ul>"description":</ul> <ul>"Test invoice",</ul></li> <li><ul>"payway":</ul> <ul>"card_uah",</ul></li> <li><ul>"pay_token":</ul> <ul>"9af6e26f3b4b44e28c26c2bd994987c4",</ul></li> <li><ul>"shop_id":</ul> <ul>"158",</ul></li> <li><ul>"shop_order_id":</ul> <ul>"49135760",</ul></li> <li><ul>"sign":</ul> <ul>"f63b494eb33e5d3549385d0ba2cb68b139e4a1b4483fd707aaac2095ab01bf42"</ul></li> <li>},</li> Пример Успешного ответа: <li>{</li> <li><ul>"data":</ul></li> <li>{</li> <li><ul>"data":</ul></li> <li>{</li> <li><ul>"en":</ul><ul>"No manual. Please, pay invoice",</ul></li> <li>},</li> <li><ul>"ru":</ul><ul>"Инструкция отсутствует. Пожалуйста, оплатите выставленный счет",</ul></li> <li>},</li> <li><ul>"uk":</ul><ul>"нструкція відсутня. Будь ласка, оплатіть рахунок",</ul></li> <li>},</li> <li><ul>"id":</ul><ul>OFFLINE,</ul></li> <li><ul>"method":</ul><ul>"OFFLINE",</ul></li> <li><ul>"url":</ul><ul>"OFFLINE",</ul></li> <li>},</li> <li><ul>"error_code":</ul><ul>0,</ul></li> <li><ul>"message":</ul><ul>"Ok",</ul></li> <li><ul>"result":</ul><ul>true</ul></li> <li>},</li> <li><ul>"shop_id":</ul><ul>158,</ul></li> <li><ul>"transfer_id":</ul><ul>null,</ul></li> <li><ul>"withdraw_id":</ul><ul>null</ul></li> <li>}</li> Пример Неуспешного ответа: <li>{</li> <li><ul>“data”:</ul> <ul>None,</ul></li> <li><ul>“error_code”:</ul> <ul>1,</ul></li> <li><ul>“message”:</ul> <ul>"IncorrectRequestParam",</ul></li> <li><ul>“result”:</ul> <ul>False</ul></li> <li>}</li> Group Криптовалютные платежи с персонального кошелька Qostiq Crypto bill - Этот метод позволяет выставлять криптовалютные счета для оплаты при помощи криптовалютного баланса с кошельков Qostiq wallet. Предварительный расчет платежа с кошелька Qostiq [/crypto/bill/try] URL: https://core.qostiq.com/crypto/bill/try Метод: POST Обязательные параметры: now, payer_currency, shop_amount, shop_currency, shop_id, shop_order_id Данный запрос не является обязательным для создания счета на оплату криптовалютного платежа с кошелька Qostiq. Запрос уточняет возможность создания платежа с указанными параметрами, возвращает суммы списания с кошелька клиента и получения магазином после расчета комиссии или конвертации. Пример Запроса: { "now" :1666266703 "payer_currency" :"USDT"" "shop_amount" :"1" "shop_currency" :"USDT" "shop_id" :13 "shop_order_id" :"test_bill_01" "sign" :af6c9c845d855013237f25sdhf80d0f91fe1569f9ee6e6125332714c322f744 } Где, Параметр Описание Формат Пример now время запроса, в формате unixtimestamp Integer 1666266703 payer_currency валюта списания средств с кошелька клиента String "USDT" shop_amount сумма операции в криптовалюте String или number, количество знаков после запятой смотрите детальней в пункте "Указание суммы операции" "1.00000001" или 1.00000001 shop_currency валюта получения средств на баланс магазина String "USDT" shop_id идентификатор магазина в системе Qostiq Integer 6 shop_order_id идентификатор счета на стороне магазина String "test_bill_01" sign подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign) String "af6c9c845d855013237f25sdhf80d0f91fe1569f9ee6e6125332714c322f744" Пример ответа: { "data" : `{` "payee_currency" :"USDT" , "payer_fee" :"0.0" , "payer_price" :"1.0" , "shop_amount" :"1.0" , "shop_currency" :"USDT" , "shop_refund" :"0.97" `},` "error_code": 0, "message": "Ok", "result": true } Где, data.payee_currency - валюта списания с клиента; data.payer_fee - сумма комисии которую платит клиент по операции в payee_currency, data.payer_price - сумма списания с баланса кошелька клиента по операции в payee_currency, data.shop_amount - сумма выставленного счета в валюте shop_currency, data.shop_currency - валюта зачисления суммы платежа на магазин магазина в валюте shop_currency; data.shop_refund - сумма зачисления на баланс магазина в валюте shop_currency. Предрасчет выставления счета [POST] Request ```json { "now": 1666266703, "payer_currency": "USDT", "shop_amount": "1", "shop_currency": "USDT", "shop_id": 13, "shop_order_id": "test_bill_01", "sign": "af6c9c845d855013237f25sdhf80d0f91fe1569f9ee6e6125332714c322f744" } ``` Response 200 () ```json { "data": { "payer_currency": "USDT", "payer_fee": "0.0", "payer_price": "1.0", "shop_amount": "1.0", "shop_currency": "USDT", "shop_refund": "0.97" }, "error_code": 0, "message": "Ok", "result": true } ``` Выставление платежа с кошелька Qostiq [/crypto/bill/create] URL: https://core.qostiq.com/crypto/bill/create Метод: POST Обязательные параметры: now, payer_currency, shop_amount, shop_currency, shop_id, shop_order_id Данный запрос создает сущность платежа который клиент может оплатить с помощью кошелька Qostiq. Уникальность shop_order_id проверяется в зависимости от настроек магазина, рекомендуем включить данную функцию и передавать уникальное значение для вашего магазина, для избежание дублированного выставления счетов на оплату. В запросе могут передаваться дополнительные параметры, например, payer_account – email/номер кошелька аккаунта плательщика в системе Qostiq. Пример Запроса: { "now" :1666687437 "payer_currency" :"USDT"" "shop_amount" :"1" "shop_currency" :"USDT" "shop_id" :13 "shop_order_id" :"test_bill_01" "sign" :8j2b0fn48dbsklhdhf8jd4hf80d0f91fe1569f9ee6e6125332714c322f744 } Где, Параметр Описание Формат Пример now время запроса, в формате unixtimestamp Integer 1666687437 payer_currency валюта списания средств с кошелька клиента String "USDT" shop_amount сумма операции в криптовалюте String или number, количество знаков после запятой смотрите детальней в пункте "Указание суммы операции" "1.00000001" или 1.00000001 shop_currency валюта получения средств на баланс магазина String "USDT" shop_id идентификатор магазина в системе Qostiq Integer 6 shop_order_id идентификатор счета на стороне магазина String "test_bill_01" sign подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign) String "8j2b0fn48dbsklhdhf8jd4hf80d0f91fe1569f9ee6e6125332714c322f744" Также, в запросе можно передавать дополнительные параметры, в формировании они не участвуют. Параметр Описание Формат Пример description описание выставленного счета String "test bill description" payer_account email или номер кошелька плательщика на стороне платежной системы Qostiq к которому будет выставлени и привязан счет, String или integer "client@shop.com" или 301494711279 failed_url URL, на который будет перенаправлен плательщик, после отклонения счета, String "https://shop.com/failed" success_url URL, на который будет перенаправлен плательщик, после успешной оплаты счета String "https://shop.com/success" crypto_callback_url URL адрес на который будет отправляться уведомление о финальном статусе счета String "https://shop.com/crypto_callback_url" lifetime время действия счета для оплаты, в минутах (по умолчанию 90 минут) String "90" Важно! Success_URL, Fail_URL, Crypto_callback_url указанные в настройках магазина, имееют приоритет выше переданных в запросе, поэтому необходимо удалить их из настроек магазина. Пример ответа: { "data" : `{` "created" :"Tue, 25 Oct 2022 08:43:57 GMT" , "id" :78 , "lifetime" :90 , "payer_account" :null , "payer_currency" :"USDT" , "payer_price" :"1.0" , "shop_amount" :"1.0" , "shop_currency" :"USDT" , "shop_id" :13 , "shop_order_id" :"test_bill_01" , "shop_refund" :"0.97" , "url" :"https://wallet.qostiq.com/ru/crypto/bill/pay/950db2bd333840b9b4b2360baccbfc2f" `},` "error_code": 0, "message": "Ok", "result": true } Где, created - дата создания платежа; id - уникальный номер операции bill на стороне системы Qostiq, lifetime - срок жизни счета в минутах, payer_account - номер кошелька к которому привязан счет, payer_currency - валюта оплаты счета с кошелька клиента; payer_price - сумма оплаты счета с кошелька клиента; shop_amount - сумма выставленого счета; shop_currency - валюта зачисления суммы операции на магазин; shop_id - номер магазина в системе Qostiq; shop_order_id - номер операции на стороне магазина; shop_refund - сумма зачисления на баланс магазина в валюте shop_currency; url - URL для редиректа клиента для оплаты выставленого счета. Выставление платежа [POST] Request ```json { "now": 1666687437, "payer_currency": "USDT", "shop_amount": "1", "shop_currency": "USDT", "shop_id": 13, "shop_order_id": "test_bill_01", "sign": "8j2b0fn48dbsklhdhf8jd4hf80d0f91fe1569f9ee6e6125332714c322f744" } ``` Response 200 () ```json { "data": { "created": "Tue, 25 Oct 2022 08:43:57 GMT", "id": 78, "lifetime": 90, "payer_account": null, "payer_currency": "USDT", "payer_price": "1.0", "shop_amount": "1.0", "shop_currency": "USDT", "shop_id": 13, "shop_order_id": "test_bill_01", "shop_refund": "0.97", "url": "https://wallet.test-qostiq.com/ru/crypto/bill/pay/950db2bd333840b9b4b2360baccbfc2f" }, "error_code": 0, "message": "Ok", "result": true } ``` Выставление счетов Bill v.2 с возможностью оплаты на свободную сумму [/crypto/bill/create/v2] Bill v.2 - новый метод позволяет выставлять счета для оплаты при помощи кошельков Qostiq wallet в 2х вариантах: на фиксированную сумму - вы определяете сколько клиент должен заплатить за ваши услуги (если передан amount); на свободную сумму - вы оставляете за клиентом право указывать сумму которая будет зачислена на магазин (если не передан amount). URL: https://core.qostiq.com/crypto/bill/create/v2 Метод: POST Обязательные параметры: currency, now, shop_id, shop_order_id Уникальность shop_order_id проверяется в зависимости от настроек магазина, рекомендуем включить данную функцию и передавать уникальное значение для вашего магазина, для избежание дублированного выставления счетов на оплату. В запросе могут передаваться дополнительные параметры, например description – описание счета, или email – email кошелька плательщика в системе Qostiq Пример Запроса: { "currency" :"USDT" "now" :1687520474 "shop_id" :6 "shop_order_id" :"dc5a286e-6c5e-43e8-8c68-926fa15d09ec" "sign" :3cbafdf3c4abe41969a994c28e3472cff1bd4711e4ab58f142b88655fef6cf27 } Где, Параметр Описание Формат Пример now время запроса, в формате unixtimestamp Integer 1687520474 currency валюта списания средств с кошелька клиента String "USDT" shop_id идентификатор магазина в системе Qostiq Integer 6 shop_order_id идентификатор счета на стороне магазина String "dc5a286e-6c5e-43e8-8c68-926fa15d09ec" sign подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign) String "3cbafdf3c4abe41969a994c28e3472cff1bd4711e4ab58f142b88655fef6cf27" Также, в запросе можно передавать дополнительные параметры, в формировании они не участвуют. Параметр Описание Формат Пример amount сумма операции в криптовалюте String или number, количество знаков после запятой смотрите детальней в пункте "Указание суммы операции" "1.00000001" или 1.00000001 description описание выставленного счета String "test bill description" failed_url URL, на который будет перенаправлен плательщик, после отклонения счета, String "https://shop.com/failed" success_url URL, на который будет перенаправлен плательщик, после успешной оплаты счета String "https://shop.com/success" crypto_callback_url URL адрес на который будет отправляться уведомление о финальном статусе счета String "https://shop.com/crypto_callback_url" lifetime время действия счета для оплаты, в минутах (по умолчанию 90 минут) String "90" email email кошелька плательщика на стороне платежной системы Qostiq String "example@mail.com" lang язык страницы оплаты (доступны английский "en", польский - "pl", русский - "ru", украинский - "uk") String "en" Важно! Success_URL, Fail_URL, Crypto_callback_url указанные в настройках магазина, имееют приоритет выше переданных в запросе, поэтому необходимо удалить их из настроек магазина. Пример ответа: { "data" : `{` "created" :"Tue, 25 Oct 2022 08:43:57 GMT" , "id" :1446 , "lifetime" :90 , "payer_account" :null , "payer_currency" :"USDT" , "payer_price" :null , "shop_amount" :null , "shop_currency" :"USDT" , "shop_id" :6 , "shop_order_id" :"dc5a286e-6c5e-43e8-8c68-926fa15d09ec" , "shop_refund" :null , "url" :"https://wallet.qostiq.com/ru/crypto/bill/pay/950db2bd333840b9b4b2360baccbfc2f" `},` "error_code": 0, "message": "Ok", "result": true } Где, created - дата создания платежа; id - уникальный номер операции bill на стороне системы Qostiq, lifetime - срок жизни счета в минутах, payer_account - номер кошелька к которому привязан счет, payer_currency - валюта оплаты счета с кошелька клиента; payer_price - сумма оплаты счета с кошелька клиента; shop_amount - сумма выставленого счета; shop_currency - валюта зачисления суммы операции на магазин; shop_id - номер магазина в системе Qostiq; shop_order_id - номер операции на стороне магазина; shop_refund - сумма зачисления на баланс магазина в валюте shop_currency; url - URL для редиректа клиента для оплаты выставленого счета. Выставление платежа [POST] Request ```json { "currency": "USDT", "shop_id": 6, "now": 1687520474, "shop_order_id": "dc5a286e-6c5e-43e8-8c68-926fa15d09ec", "sign": "3cbafdf3c4abe41969a994c28e3472cff1bd4711e4ab58f142b88655fef6cf27" } ``` Response 200 () ```json { "data": { "created": "Fri, 23 Jun 2023 12:37:45 GMT", "id": 1446, "lifetime": 90, "payer_account": null, "payer_currency": "USDT", "payer_price": null, "shop_amount": null, "shop_currency": "USDT", "shop_id": 6, "shop_order_id": "dc5a286e-6c5e-43e8-8c68-926fa15d09ec", "shop_refund": null, "url": "https://wallet.test-qostiq.com/ru/crypto/bill/pay/5379b266fa244c85b42f704d92366165" }, "error_code": 0, "message": "Ok", "result": true } ``` Запрос статуса платежа с кошелька Qostiq [/crypto/bill/shop_order_status] URL: https://core.qostiq.com/crypto/bill/shop_order_status Метод: POST Обязательные параметры: now, shop_id, shop_order_id Данный запрос не является обязательным. Запрос дает возможность узнать актуальный статус выставленого счета. Пример Запроса: { "now" :1666688539 "shop_id" :13 "shop_order_id" :"test_bill_01" "sign" :hsd8dhf88kdpc8sn9c237f25sdhf80d0f91fe1569f9ee6e6125332714c322f744 } Где, Параметр Описание Формат Пример now время запроса, в формате unixtimestamp Integer 1666688539 shop_id идентификатор магазина в системе Qostiq Integer 6 shop_order_id идентификатор счета на стороне магазина String "test_bill_01" sign подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign) String "hsd8dhf88kdpc8sn9c237f25sdhf80d0f91fe1569f9ee6e6125332714c322f744" Пример ответа: { "data" : `{` "created" :"2022-10-25 08:43:57" , "description" :"" , "is_unique" :false , "payer_currency" :"USDT" , "payer_price" :"1.0" , "payment_id" :78 , "processed" :null , `"ps_data"`:`{"ps_payer_account": null}`, "shop_amount" :"1.0" , "shop_currency" :"1.0" , "shop_id" :"1.0" , "shop_order_id" :"1.0" , "shop_refund" :"0.97" , "status" :1 `},` "error_code": 0, "message": "Ok", "result": true } Где, created - дата создания платежа; description - описание выставленного платежа, is_unique - уникальность номера платежа на стороне магазина - shop_order_id , payer_currency - валюта списания суммы платежа payer_price с кошелька клиента, payer_price - сумма списания с кошелька клиента в валюте payer_currency; payment_id - уникальный номер операции на стороне Qostiq, возвращается в параметре id на запрос создания платежа /crypto/bill/create; processed - время получения финального статуса платежа; ps_data.ps_payer_account - номер кошелька плательщика; shop_amount - сумма выставленного платежа в валюте shop_currency; shop_currency - валюта платежа; shop_id - номер магазина; shop_order_id - номера платежа на стороне магазина; shop_refund - сумма зачисления платежа на магазин в валюте shop_currency; status - статус счета, информацию о статусах можно посмотреть в пункте Статусы платежей. Внимание! Запрос статуса необходимо делать не чаще чем раз в 10 секунд.

Значение `status`	Название	Описание	Финальный?
`1`	Waiting	Платеж находится в стадии ожидания действий пользователя	Нет
`2`	Paid	Платеж оплачен клиентом	Да
`3`	Canceled	Платеж отменен клиентом	Да
`4`	Expired	Истёк срок жизни счёта	Да

Запрос	`error_code`	`message`	Описание
/bill/recurrent /crypto/bill/recurrent /auth_token/revoke	`10`	`Auth token ({token}) not found`	Токен не существует или неактивный
/bill/recurrent /crypto/bill/recurrent	`9`	`Insufficient payer (id=6) balance`	Недостаточно средств для списания на кошельке клиента
/bill/recurrent /crypto/bill/recurrent	`44`	`Limit exceeds`	Превышен установленый клиентом лимит на оплату по подписке

Параметр	Описание	Формат	Пример
`description`	описание выставленного счета (не обязательный параметр)	String	"test bill"
`failed_url`	URL, на который будет перенаправлен плательщик, после не успешной оплаты счета,	String	"https://qostiq.com/failed"
`success_url`	URL, на который будет перенаправлен плательщик, после успешной оплаты счета	String	"https://qostiq.com/success"
`callback_url`	URL адрес на который будет отправляться уведомление об успешной оплате	String	"https://qostiq.com/callback_url_kvt"
`callback_rejected_url`	URL адрес на который будет отправляться уведомление о неуспешной оплате	String	"https://qostiq.com/callback_rejected_url_kvt"

Сценарий	Пример	Как проявляется
`Изменение курса`	Клиент платит BTC, курс изменился за время подтверждения	`shop_amount ≠ исходному amount`
`Переплата`	Клиент отправил больше криптовалюты, чем требовалось	`client_price > расчётного значения`
`Недоплата`	Клиент отправил недостаточно криптовалюты	`client_price < минимального лимита`

Параметр	Тип	Обязательный	Описание	Пример
`currency`	string	✓	Код валюты ISO 4217	"980"
`payway`	string	✓	Платежный метод	"card_uah"
`amount`	string	✓	Сумма платежа	"100.00"
`shop_id`	integer	✓	ID магазина	112
`shop_order_id`	integer	✓	ID заказа	4129
`description`	string		Описание платежа	"Test invoice"
`sign`	string	✓	Подпись запроса	"8fb2cafd..."
`overwrite_amount`	string		Скорректированная сумма	"99.85"
`is_overwritten`	boolean		Флаг изменения суммы	true
`shop_amount`	string	✓	Итоговая сумма счета	"99.85"
`shop_refund`	string	✓	Сумма зачисления	"99.00"

Код ошибки	Описание
1	PaywayNotFound
2	PaywayNotUsed
3	PaywayNotAvailable
4	AmountTooSmall
5	AmountTooLarge
6	OperationNotUnique
7	OperationNotFound
8	OperationIsProcessing
9	InsufficientBalance
10	IncorrectRequestParam
11	ShopNotFound
12	ShopNotActive
13	AccountNotFound
14	IncorrectAccountStatus
15	RequestIpDenied
16	InvalidCurrencyExchange
17	InvalidShopContract
18	IncorrectAccountType
19	ShopAggregatorRequire
20	InvalidProject
21	ProjectNotActive
100	IncorrectOperationStatus
2000	Другая ошибка

Status	Значение	Описание	Финальный?
1	`Created`	Создан запрос на платеж	Нет,
2	`Waiting`	Платеж находится в стадии ожидания действий пользователя	Нет,
3	`PsCreatingError`	Ошибка создания платежа на стороне платежной системы	Нет,
4	`Success`	Оплата успешно выполнена	Да,
5	`CallbackError`	Ошибка получения уведомления об оплате со стороны платежной системы	Нет,
6	`Rejected`	Отклонен на стороне платежной системы	*Да,
7	`Refunded`	Сумма счета возвращена плательщику платежной системой	Да,
8	`Hold`	Средства по оплате счета удержаны (холдирование) платежной системой	Нет,
9	`IntRefunded`	Сумма счета возвращена плательщику системой Qostiq	Да,
10	`Captured`	Средства по оплате счета заблокированы платежной системойx	Нет,

Параметр	Описание	Формат	Пример
`amount`	сумма получения или списания (зависит от amount_type)	Number (Не больше 2х знаков после точки)	1, 1.0, 1.00 или "1.00"
`amount_type`	указывает на тип суммы, возможны значения: ps_amount – сумма к получению в платежной системе, shop_amount – сумма к списанию с баланса магазина	String	"ps_amount" или "shop_amount"
`payway`	направление для выплаты, можно узнать в личном кабинете или у курирующего менеджера. Валюта получения зависит от указанного направления для выплаты	String	"card_uah"
`shop_currency`	валюта списания с магазина,	Integer	980 - Украинская гривна, 840 - Доллар США, 978 - Евро
`shop_id`	идентификатор магазина, с которого осуществляется выплата	Integer	112
`sign`	сформированая подпись	String	"f97c52fa8d273a9d3ad37e86e6dab314a592281654104ac9f348f386c29a2953"

Параметр	Описание	Формат	Пример
`amount`	сумма планируемого зачисления на аккаунт в валюте платежного направления, данная информация необходима для более точной проверки о возможности зачисления, т.к. за частую на аккаунтах получателей устанавливаются лимиты пополнения	Number (Не больше 2х знаков после точки)	1, 1.0, 1.00 или "1.00"
`account`	основной аккаунт для проверки на возможность пополнения, для каждого платежного направления может быть свой (информацию можно уточнить в личном кабинете)	String	"4111111111111111"
`payway`	направление для выплаты, можно узнать в личном кабинете или у курирующего менеджера. Валюта получения зависит от указанного направления для выплаты	String	"card_uah"
`shop_id`	идентификатор магазина, с которого осуществляется выплата	Integer	112
`sign`	сформированная подпись	String	"f97c52fa8d273a9d3ad37e86e6dab314a592281654104ac9f348f386c29a2953"

Параметр	Описание	Формат	Пример
`account`	aккаунт получателя средств в платежной системе, например номер карты;	String	"4111111111111111"
`amount`	сумма получения или списания (зависит от amount_type)	Number (Не больше 2х знаков после точки)	1, 1.0, 1.00 или "1.00"
`amount_type`	указывает на тип суммы, возможны значения: ps_amount – сумма к получению в платежной системе, shop_amount – сумма к списанию с баланса магазина	String	"ps_amount" или "shop_amount"
`payway`	направление для выплаты, можно узнать в личном кабинете или у курирующего менеджера. Валюта получения зависит от указанного направления для выплаты	String	"card_uah"
`shop_currency`	валюта списания с магазина,	Integer	980 - Украинская гривна, 840 - Доллар США, 978 - Евро,
`shop_id`	идентификатор магазина, с которого осуществляется выплата	Integer	1
`shop_payment_id`	уникальный идентификатор платежа на стороне магазина	String	"2e18aadc-cf87-4cdd-9a08-9a57f9ac4066"
`callback_url`	URL для приема уведомления по операции (необязательный параметр, подробно об уведомлениях по выплатам)	String	"https://shop.com/withdraw/callback"

Параметр	Описание	Формат	Пример
`now`	время запроса	String	"2017-05-16 16:56:25.009469"
`shop_id`	идентификатор магазина в системе Qostiq	Integer	112
`withdraw_id`	уникальные идентификатор выплаты на стороне Qostiq, для которого необходимо узнать статус, формат integer (возвращается в параметре `id`, при успешно созданном платеже на запрос `withdraw/create`)	Integer	11298076
`sign`	подпись	String	"e1dfc97b2c5430e21be08b1140f25259aa1865d56e166ee398c2368ad39712f7"

Параметр	Описание	Формат	Пример
`now`	время запроса	String	"2011-12-06 16:07:28.878200"
`shop_id`	идентификатор магазина в системе Qostiq	Integer	112
`shop_payment_id`	идентификатор транзакции на стороне магазина	String	"63288d86-241c-418e-94b8-db4bbf5026f"
`sign`	подпись	String	"e1dfc97b2c5430e21be08b1140f25259aa1865d56e166ee398c2368ad39712f7"

Status	Значение	Описание	Финальный?
1	`Created`	Платеж создан, ожидает обработки	Нет, делать запрос статуса
2	`WaitingManualConfirmation`	Ожидает ручного подтверждения оператора	Нет, делать запрос статуса
3	`PsProcessing`	Отправлен на платежную систему	Нет, делать запрос статуса
4	`PsProcessingError`	Ошибка при выплате на стороне платежной системы	Нет, делать запрос статуса или обратиться в поддержку
5	`Success`	Успешно выполнен	Да, средства списаны с магазина
6	`Rejected`	Отклонен на стороне платежной системы	Да, средства не списаны с магазина
7	`ManualConfirmed`	Подтвержден оператором и ожидает проводки	Нет, делать запрос статуса
9	`PsNetworkError`	Сетевая ошибка на стороне платежной системы	Нет, делать запрос статуса
10	`CanceledManually`	Вывод отменен вручную на стороне системы Qostiq	Да,финальный статус
11	`Refunded`	Успешный вывод отменен вручную на стороне системы Qostiq	Да,финальный статус

Параметр	Описание	Формат	Пример
`now`	время запроса	String	"30.06.2017 10:12:44"
`shop_id`	идентификатор магазина в системе Qostiq	Integer	1
`email`	почта регистрации кошелька	String	"example@email.com"
`sign`	подпись	String	"32b2c32caa8adecf89c6dfa72ffca3a0506f33febfe3aaab090cdbfbd0e8b953"

Параметр	Описание	Формат	Пример
`now`	время запроса	String	"2017-05-17 10:48:45.509731"
`shop_id`	идентификатор магазина в системе Qostiq	Integer	1
`sign`	подпись	String	"361f6310a04ef858df0847d1e2f6669ea61159a5c80d0ed6dcf17329751b4ef9"

Параметр	Описание	Формат	Пример
now	время запроса	String	"2018-06-15 09:58:01.01"
shop_id	идентификатор магазина в системе Qostiq	Integer	3
sign	подпись	String	"588485c9d7f0d7fb3445e620450ca303ae11e35e159002bc33d2174398f9134c"

Параметр	Описание	Формат
`session_id`	ID полученный в ответе на запрос Invoice create	string

Параметр	Описание	Формат
`form_token`	Токен для передачи карточных данных	string
`payform_url`	URL для редиректа пользователя с карточными данными	string

Параметр	Описание	Формат
`expiry_year`	год окончания действия карты	`22`
`card_holder`	TEST TEST	`https://qostiq.com/failed/`
`card_number`	номер карты пользователяа	`4111111111111111`
`expiry_month`	месяц окончания действия срока карты	`12`
`cvv`	трёхзначный код проверки подлинности карты	`123`
`session_id`	уникальный идентификатор операции оплаты	`26d90ef012e34b44aa9d74a3556e15a6`
`form_token`	токен для передачи карточных даннх	`0e61dd5935054d7e99d3da0cef411758`
`action`	URL для редиректа пользователя с карточными данными	`https://card.tech-icard.com/en/payform`

Параметр	Описание	Формат	Пример
`now`	время запроса, в формате unixtimestamp	Integer	1666266703
`payer_currency`	валюта списания средств с кошелька клиента	String	"USDT"
`shop_amount`	сумма операции в криптовалюте	String или number, количество знаков после запятой смотрите детальней в пункте "Указание суммы операции"	"1.00000001" или 1.00000001
`shop_currency`	валюта получения средств на баланс магазина	String	"USDT"
`shop_id`	идентификатор магазина в системе Qostiq	Integer	6
`shop_order_id`	идентификатор счета на стороне магазина	String	"test_bill_01"
`sign`	подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign)	String	"af6c9c845d855013237f25sdhf80d0f91fe1569f9ee6e6125332714c322f744"

Параметр	Описание	Формат	Пример
`now`	время запроса, в формате unixtimestamp	Integer	1666687437
`payer_currency`	валюта списания средств с кошелька клиента	String	"USDT"
`shop_amount`	сумма операции в криптовалюте	String или number, количество знаков после запятой смотрите детальней в пункте "Указание суммы операции"	"1.00000001" или 1.00000001
`shop_currency`	валюта получения средств на баланс магазина	String	"USDT"
`shop_id`	идентификатор магазина в системе Qostiq	Integer	6
`shop_order_id`	идентификатор счета на стороне магазина	String	"test_bill_01"
`sign`	подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign)	String	"8j2b0fn48dbsklhdhf8jd4hf80d0f91fe1569f9ee6e6125332714c322f744"

Параметр	Описание	Формат	Пример
`description`	описание выставленного счета	String	"test bill description"
`payer_account`	email или номер кошелька плательщика на стороне платежной системы Qostiq к которому будет выставлени и привязан счет,	String или integer	"client@shop.com" или 301494711279
`failed_url`	URL, на который будет перенаправлен плательщик, после отклонения счета,	String	"https://shop.com/failed"
`success_url`	URL, на который будет перенаправлен плательщик, после успешной оплаты счета	String	"https://shop.com/success"
`crypto_callback_url`	URL адрес на который будет отправляться уведомление о финальном статусе счета	String	"https://shop.com/crypto_callback_url"
`lifetime`	время действия счета для оплаты, в минутах (по умолчанию 90 минут)	String	"90"

Параметр	Описание	Формат	Пример
`now`	время запроса, в формате unixtimestamp	Integer	1687520474
`currency`	валюта списания средств с кошелька клиента	String	"USDT"
`shop_id`	идентификатор магазина в системе Qostiq	Integer	6
`shop_order_id`	идентификатор счета на стороне магазина	String	"dc5a286e-6c5e-43e8-8c68-926fa15d09ec"
`sign`	подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign)	String	"3cbafdf3c4abe41969a994c28e3472cff1bd4711e4ab58f142b88655fef6cf27"

Параметр	Описание	Формат	Пример
`amount`	сумма операции в криптовалюте	String или number, количество знаков после запятой смотрите детальней в пункте "Указание суммы операции"	"1.00000001" или 1.00000001
`description`	описание выставленного счета	String	"test bill description"
`failed_url`	URL, на который будет перенаправлен плательщик, после отклонения счета,	String	"https://shop.com/failed"
`success_url`	URL, на который будет перенаправлен плательщик, после успешной оплаты счета	String	"https://shop.com/success"
`crypto_callback_url`	URL адрес на который будет отправляться уведомление о финальном статусе счета	String	"https://shop.com/crypto_callback_url"
`lifetime`	время действия счета для оплаты, в минутах (по умолчанию 90 минут)	String	"90"
`email`	email кошелька плательщика на стороне платежной системы Qostiq	String	"example@mail.com"
`lang`	язык страницы оплаты (доступны английский "en", польский - "pl", русский - "ru", украинский - "uk")	String	"en"

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

Если shop_order_id не уникален по операциям bill в рамках магазина, в ответе содержится "is_unique":false и метод возвращает информацию по последнему созданному Bill. Уникальность shop_order_id проверяется в зависимости от настроек магазина, рекомендуем включить данную функцию и передавать уникальное значение для вашего магазина, для избежание дублированного выставления счетов на оплату. Запрос статуса платежа [POST] Request ```json { "now": 1666688539, "shop_id": 13, "shop_order_id": "test_bill_01", "sign": "hsd8dhf88kdpc8sn9c237f25sdhf80d0f91fe1569f9ee6e6125332714c322f744" } ``` Response 200 () ```json { "data": { "created": "2022-10-25 08:43:57", "description": "", "is_unique": false, "payer_currency": "USDT", "payer_price": "1.0", "payment_id": 78, "processed": null, "ps_data": { "ps_payer_account": null }, "shop_amount": "1.0", "shop_currency": "USDT", "shop_id": 13, "shop_order_id": "test_bill_01", "shop_refund": "0.97", "status": 1 }, "error_code": 0, "message": "Ok", "result": true } ``` Уведомление после оплаты платежа с кошелька Qostiq [/crypto/bill/callback] Метод: POST, Content-Type=application/json После оплаты оплаты или отклонения счета клиентом, система Qostiq производит отправку уведомления магазину на указанный в настройках URL crypto взаимодействия или переданный crypto_calback_url в запросе создания счета. Уведомления отправляются с 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. Пример уведомления: { "callback_type" :"crypto_bill" , "client_price" :"0.1" , "created" :"2022-10-21 13:25:30" , "description" : null , "payment_id" :71 , "payway" : "qostiq_usdt" , "processed" : "2022-10-21 13:25:53" , "ps_currency" : "USDT" , "ps_data": "{"ps_payer_account": "31645670659"}", "shop_amount" :"0.1" , "shop_currency" :"USDT" , "shop_id" : 59 , "shop_order_id" : "16384496" , "shop_refund" : "0.097" , "sign" : "5d66740075e54cb90a1ed9e4352a957b2a7cf4955e40638e5df4a54c8f89d780" , "status" : "success" }, Где, callback_type – тип операции по которой пришло уведомление, "crypto_bill" при платеже; client_price – сумма, которую оплатил клиент, в валюте "ps_currency"; created – дата и время создания платежа; processed – дата и время получения финального статуса платежа (оплата или отклонение); description – описание счета; payment_id - уникальный номер операции на стороне Qostiq, возвращается в параметре id на запрос создания платежа /crypto/bill/create; payway – платежное направление в системе Qostiq, через которое оплатил пользователь; ps_currency – валюта платежного направления, через которое оплатил пользователь; ps_data.ps_payer_account - номер кошелька клиента который оплатил или отменил выставленый счет; shop_amount – сумма созданного счета, в валюте счета; shop_currency – валюта счета; shop_id – уникальный идентификатор магазина, в пользу которого осуществляется оплата; shop_order_id – номер операции на стороне магазина; shop_refund – сумма зачисления на баланс магазина, в валюте shop_currency; status – статус счета, детальней можно посмотреть в пункте Статусы платежей , sign – подпись. Подпись формируется по алгоритму, что и по всем операциям, но в формировании подписи участвуют все параметры, значение которых не null и пустая строка. Пример строки, по которой необходимо сгенерировать подпись: crypto_bill:0.1:2022-10-21 13:25:30:71:qostiq_usdt:2022-10-21 13:25:53:USDT:{"ps_payer_account": "31645670659"}:0.1:USDT:59:16384496:0.097:successTestkey1 При корректном получении и обработке уведомления, необходимо вернуть в ответ http статус 200 и тело сообщения OK. В ином случае уведомления будут высылаться повторно, с увеличивающемся интервалом, всего 25 попыток, последнее по истечении суток. Пример уведомления после оплаты [POST] Request ```json { "callback_type": "crypto_bill", "client_price": "0.1", "created": "2022-10-21 13:25:30", "description": null, "payment_id": 71, "payway": "qostiq_usdt", "processed": "2022-10-21 13:25:53", "ps_currency": "USDT", "ps_data": "{"ps_payer_account": "31645670659"}", "shop_amount": "0.1", "shop_currency": "USDT", "shop_id": 59, "shop_order_id": "16384496", "shop_refund": "0.097", "sign": "5d66740075e54cb90a1ed9e4352a957b2a7cf4955e40638e5df4a54c8f89d780", "status": "success" } ``` Response 200 () ```json { OK } ``` Статусы платежей с кошелька Qostiq [/crypto/bill/status] Status Значение Описание Финальный? 1 Waiting Счет создан, ожидает оплаты Нет 2 Success - значение приходит в уведомлении Счет оплачен Да,средства зачислены на баланс магазина 3 Rejected - значение приходит в уведомлении Клиент отменил счет Да, средства не зачислены на баланс магазина 4 Expired Срок возможной оплаты счета исчерпан Да, средства не зачислены на баланс магазина Запрос статуса платежа [POST] Request ```json { "now": 1666688539, "shop_id": 13, "shop_order_id": "test_bill_02", "sign": "hsd8dhf88kdpc8sn9c237f25sdhf80d0f91fe1569f9ee6e6125332714c322f744" } ``` Response 200 () ```json { "data": { "created": "2022-10-27 07:03:10", "description": "", "is_unique": false, "payer_currency": "USDT", "payer_price": "1.0", "payment_id": 90, "processed": "2022-10-27 07:04:22", "ps_data": { "ps_payer_account": "31645670435" }, "shop_amount": "1.0", "shop_currency": "USDT", "shop_id": 13, "shop_order_id": "test_bill_02", "shop_refund": "0.97", "status": 3 }, "error_code": 0, "message": "Ok", "result": true } ``` Group Криптовалютные выплаты на персональный кошелек Qostiq Crypto transfer - Этот метод позволяет совершить криптовалютные выплаты с криптовалютного баланса магазина на персональный Qostiq кошелек. Предварительный расчет выплаты на кошелек Qostiq [/crypto/transfer/try] URL: https://core.qostiq.com/crypto/transfer/try Метод: POST Обязательные параметры: amount, amount_type, now, payer_currency, shop_currency, shop_id Данный запрос не является обязательным для создания выплаты на криптовалютный кошелек Qostiq. Запрос уточняет возможность создания выплаты с указанными параметрами, возвращает суммы списания с магазина и получения на кошелек получателя после расчета комиссии или конвертации. Пример Запроса: { "amount" :10 "amount_type" :"writeoff_amount" "now" :1691400155 "payee_currency" :"TRX" "shop_currency" :"TRX" "shop_id" :6 "sign" :"e77dc50d3e4bc3b307924aaefeab1887d38e1aa0d73ba17a2bdad99893b984e6" } Где, Параметр Описание Формат Пример amount сумма выплаты String или number, количество знаков после запятой смотрите детальней в пункте "Указание суммы операции" "1.00000001" или 1.00000001 amount_type указывает на тип суммы amount, возможны значения: receive_amount – сумма к получению на кошелек в валюте payer_currency, writeoff_amount - сумма к списанию с баланса магазина в валюте shop_currency String "receive_amount" или "writeoff_amount" now время запроса, в формате unixtimestamp Integer 1691400155 payer_currency валюта получения средств на кошелек клиента String "TRX" shop_currency валюта списания средств с баланса магазина String "TRX " shop_id идентификатор магазина в системе Qostiq Integer 6 sign подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign) String "e77dc50d3e4bc3b307924aaefeab1887d38e1aa0d73ba17a2bdad99893b984e6" Пример ответа: { "data" : `{` "fee" :"0.0" , "payee_currency" :"TRX" , "receive_amount" :"10.0" , "shop_currency" :"TRX" , "write_off_amount" :"10.0" `},` "error_code": 0, "message": "Ok", "result": true } Где, fee - комиссия за выплату; payee_currency - валюта получения выплаты; receive_amount - сумма к получению на счет в валюте с параметра payee_currency; shop_currency - валюта списания с баланса магазина; write_off_amount - сумма списания с магазина в валюте с параметра shop_currency. Предварительный расчет выплаты на кошелек Qostiq [POST] Request ```json { "amount":10, "amount_type":"writeoff_amount", "now":1691400155, "payee_currency":"TRX", "shop_currency":"TRX", "shop_id":6, "sign": "e77dc50d3e4bc3b307924aaefeab1887d38e1aa0d73ba17a2bdad99893b984e6" } ``` Response 200 () ```json { "data": { "fee": "0.0", "payee_currency": "TRX", "receive_amount": "10.0", "shop_currency": "TRX", "write_off_amount": "10.0" }, "error_code": 0, "message": "Ok", "result": true } ``` Создание выплаты на кошелек Qostiq [/crypto/transfer/create] URL: https://core.qostiq.com/crypto/transfer/create Метод: POST Обязательные параметры: amount, amount_type, now, payee_account, payer_currency, shop_currency, shop_id, shop_payment_id Данный запрос создает сущность выплаты на Qostiq кошелек клиента. Значение параметра shop_payment_id должен быть уникальным для каждого нового перевода. В запросе могут передаваться дополнительные параметры, например, description – описание выплаты. Внимание! На текущий момент совершение выплат с конвертаций недоступно. При создании должна быть указанная одинаковая валюта в параметрах "payee_currency" и "shop_currency" иначе запрос получит ошибку "message": "Currencies must be the same". Пример Запроса: { "amount" :10 , "amount_type" :"writeoff_amount" , "now" :1691484449 "payee_account" :"31645670435" , "payee_currency" :"TRX" , "shop_currency" :"TRX" , "shop_id" :6 , "shop_payment_id" :"bfe31d10-adea-40f4-9249-d2dafa2e09db" , "sign" :"6a3a94b38df2d2041ad75b44d3f259b75064b3deebba8f6c50c784cbe686b9bf" } Где, Параметр Описание Формат Пример amount сумма выплаты String или number, количество знаков после запятой смотрите детальней в пункте "Указание суммы операции" "1.00000001" или 1.00000001 amount_type указывает на тип суммы amount, возможны значения: receive_amount – сумма к получению на кошелек в валюте payer_currency, writeoff_amount - сумма к списанию с баланса магазина в валюте shop_currency String "receive_amount" или "writeoff_amount" now время запроса, в формате unixtimestamp Integer 1691484449 payee_account аккаунт получателя средств в системе Qostiq, может быть передан как номер кошелька, так и email пользователя String "31645670435" или "example@mail.com"; payer_currency валюта получения средств на кошелек клиента String "TRX" shop_currency валюта списания средств с баланса магазина String "TRX " shop_id идентификатор магазина в системе Qostiq Integer 6 shop_payment_id уникальный идентификатор платежа на стороне магазина String "bfe31d10-adea-40f4-9249-d2dafa2e09db" sign подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign) String "6a3a94b38df2d2041ad75b44d3f259b75064b3deebba8f6c50c784cbe686b9bf" Пример ответа: { "data" : `{` "fee" :"0.0" , "id" :1266 , "payee_currency" :"TRX" , "receive_amount" :"10.0" , "shop_currency" :"TRX" , "write_off_amount" :"10.0" `},` "error_code": 0, "message": "Ok", "result": true } Где, fee - комиссия за выплату; id - уникальный идентификатор перевода на стороне Qostiq; payee_currency - валюта получения выплаты; receive_amount - сумма к получению на счет в валюте с параметра payee_currency; shop_currency - валюта списания с баланса магазина; write_off_amount - сумма списания с магазина в валюте с параметра shop_currency. Внимание! У операции transfer отсутствует статус, т.к. если он создался и в ответе вернулся ID перевода, то перевод считается успешно проведенным, дополнительных запросов не требуется. Создание выплаты на кошелек Qostiq [POST] Request ```json { "amount":10, "amount_type":"writeoff_amount", "now":1691484449, "payee_currency":"TRX", "payee_account":"31645670435", "shop_currency":"TRX", "shop_payment_id":"bfe31d10-adea-40f4-9249-d2dafa2e09db", "shop_id":6, "sign": "6a3a94b38df2d2041ad75b44d3f259b75064b3deebba8f6c50c784cbe686b9bf" } ``` Response 200 () ```json { "data": { "fee": "0.0", "id": 1266, "payee_currency": "TRX", "receive_amount": "10.0", "shop_currency": "TRX", "write_off_amount": "10.0" }, "error_code": 0, "message": "Ok", "result": true } ``` Запрос статуса выплаты на кошелек Qostiq [/crypto/transfer/status] Запрос статуса по переводу transfer выполняется по номеру платежа магазина. В случае получения time-out или других ошибок на запрос создания transfer, можно сделать запрос статуса выплаты с помощью данного метода. Если в ответе вернулся идентификатор и данные по переводу, то значит выплата была успешно создана и проведена. В противном случае вернется ошибка, что выплата не найдена и необходимо будет повторить запрос на создание выплаты. URL: https://core.qostiq.com/crypto/transfer/status Метод: POST Обязательные параметры: now, shop_id, shop_payment_id Параметр Описание Формат Пример now время запроса Integer 1691491958 shop_payment_id номер счета на стороне Вашего сервиса String "bfe31d10-adea-40f4-9249-d2dafa2e09db" shop_id идентификатор магазина в системе Qostiq Integer 6 sign подпись String "a39c6eee74e6213a722e4f85ee05b0207d05e25b7c54b75f14fe646a86832948" Пример запроса: { "shop_id" : 6 , "shop_payment_id" : "bfe31d10-adea-40f4-9249-d2dafa2e09db" , "now" : 1691491958 , "sign" : "a39c6eee74e6213a722e4f85ee05b0207d05e25b7c54b75f14fe646a86832948" } Пример ответа, если transfer был создан и проведен: { "data" : `{` "fee" :"0.0" , "id" :1266 , "payee_currency" :"TRX" , "receive_amount" :"10.0" , "shop_currency" :"TRX" , "write_off_amount" :"10.0" `},` "error_code": 0, "message": "Ok", "result": true } Пример ответа, если transfer не был создан (не найден): { "data" : null , "error_code" : 7 , "message" : "Transfer (shop_payment_id=test_order_name) wasn't found" , "result" : false } Запросить статус transfer [POST] Request (application/json) ```json { "shop_id": 6, "shop_payment_id": "bfe31d10-adea-40f4-9249-d2dafa2e09db", "now": 1691491958, "sign": "a39c6eee74e6213a722e4f85ee05b0207d05e25b7c54b75f14fe646a86832948" } ``` Response 200 () ```json { "data": { "fee": "0.0", "id": 1266, "payee_currency": "TRX", "receive_amount": "10.0", "shop_currency": "TRX", "write_off_amount": "10.0" }, "error_code": 0, "message": "Ok", "result": true } ``` Response 200 () ```json { "data": null, "error_code": 7, "message": "Transfer (shop_payment_id=test_order_name) wasn't found", "result": false } ``` Group Криптовалютные платежи Для подключения на магазин криптовалютного баланса и криптовалютных направлений необходимо обратиться к курирующему менеджеру или на 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, за вычетом комиссии блокчейна за перевод. Внимание! Для совершения возврата магазин должен уточнить у клиента адрес клиента на который клиент будет получать возврат, так как адрес с которого был совершен платеж зачастую не является персональным адресом клиента. Возвраты запрещено делать на адреса системы 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" : `{` "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 } ``` Group Криптовалютные выплаты Для подключения на магазин криптовалютного баланса и криптовалютных направлений необходимо обратиться к курирующему менеджеру или на 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,/code> "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 Пример уведомления: <div> <ul> <li>{ <li><ul>"address"</ul>:<ul>"0xf8227AA7aF9B5166AF69581C703A4398387B2B07"</ul>,</li> <li><ul>"callback_type"</ul>:<ul>"crypto_withdraw"</ul>,</li> <li><ul>"created"</ul>:<ul>"2022-06-29 10:29:47"</ul>,</li> <li><ul>"description"</ul>:<ul> null</ul>,</li> <li><ul>"payee_receive"</ul>:<ul>"0.000100000000000000"</ul>,</li> <li><ul>"payment_id"</ul>:<ul>58</ul>,</li> <li><ul>"payway"</ul>: <ul>"bnb_bep20"</ul>,</li> <li><ul>"processed"</ul>:<ul> "2022-06-29 10:30:33"</ul>,</li> <li><ul>"ps_currency"</ul>: <ul>"BNB"</ul>,</li> <li><ul>"ps_data"</ul>:<ul> "{"transaction_hash": "0x8d3d3f6851a16c4f5d957124fa8444f4be9add351aa9c4e301e2eeff13a910df"}"</ul>,</li> <li><ul>"shop_currency"</ul>:<ul>"BNB"</ul>,</li> <li><ul>"shop_id"</ul>:<ul> 6</ul>,</li> <li><ul>"shop_order_id"</ul>:<ul>"test_withdraw_id_5"</ul>,</li> <li><ul>"shop_write_off"</ul>:<ul>"0.000103000000000000"</ul>,</li> <li><ul>"sign"</ul>:<ul> "f8ec782aa4d1332532cc7ac5364ef979f593079505529d895e1f2c4a7cd0e024"</ul>,</li> <li><ul>"status"</ul>: <ul>"success"</ul></li> },</li> </ul> </div> Где, 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 ```json { "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 () ```json ```json { OK } ### Выплата: запрос статуса по withdraw_id [/crypto/withdraw/status] <div id="/crypto/withdraw/status"> </div> <strong>URL:</strong> <code>https://core.qostiq.com/crypto/withdraw/status</code> <strong>Метод:</strong> <code>POST</code> <strong>Обязательные параметры:</strong> <code>now, shop_id, withdraw_id</code> <strong>Пример Запроса:</strong> <div> <ul> <li> { <li> <ul>"now"</ul>:<ul>1655802380</ul> </li> <li> <ul>"shop_id"</ul>:<ul>6</ul> </li> <li> <ul>"withdraw_id"</ul>:<ul>15</ul> </li> <li> <ul>"sign"</ul>:<ul>bc21703c682f0b9f53d4b554cfd55d8a25fc75c0e386fe589033aa0f49f35d07</ul> </li> } </li> </ul> </div> Где, <table><tr><th>Параметр</th> <th>Описание</th> <th>Формат</th> <th>Пример</th></tr> <tr><td><code>now</code></td> <td>время запроса, в формате unixtimestamp</td> <td>Integer</td> <td>1655815845</td></tr> <tr><td><code>shop_id</code></td> <td>идентификатор магазина в системе Qostiq</td> <td>Integer</td> <td>6</td></tr> <tr><td><code>withdraw_id</code></td> <td>Номер операции на стороне Qostiq (возвращается в ответе на запрос <a href="#crypto_wd_response">создания выплаты в параметре <code>data.id</code></a>)</td> <td>Integer</td> <td>15</td></tr> <tr><td><code>sign</code></td> <td>подпись, см. п. <a href="#sign">Правила формирования подписи для операций с криптовалютой (sign)</a></td> <td>String</td> <td>"175365f50e85fa717be6cb5dc3e456b09c5d3e2e6ee7046286ef31019f87ff59"</td></tr></table> <strong>Пример ответа:</strong> <div> <ul> <li> { <li><ul>"data"</ul>:</li> <li><ul>{</ul></li> <li><ul>"id"</ul>:<ul>15</ul>, </li> <li><ul>"payee_address"</ul>:<ul>"0xf8227AA7aF9B5166AF69581C703A4398387B2B07"</ul>, </li> <li><ul>"payee_currency"</ul>:<ul>"USDT"</ul>, </li> <li><ul>"payee_receive"</ul>:<ul>"0.0001"</ul>, </li> <li><ul>"shop_currency"</ul>:<ul>"USDT"</ul>, </li> <li><ul>"shop_payment_id"</ul>:<ul>"test_withdraw_id_4"</ul>, </li> <li><ul>"shop_write_off"</ul>:<ul>"0.000103"</ul>, </li> <li><ul>"status"</ul>:<ul>2</ul> </li> <li><ul>},</ul></li> <li><ul>"error_code":</ul><ul>0,</ul></li> <li><ul>"message":</ul><ul>"Ok",</ul></li> <li><ul>"result":</ul><ul>true</ul></li> } </li> </ul> </div> Где, <strong><code>data.id</code></strong> - номер операции в системе Qostiq; <strong><code>data.payee_address</code></strong> - адрес на который создана выплата; <strong><code>data.payee_currency</code></strong> - валюта получения выплаты; <strong><code>data.payee_receive</code></strong> - сумма к получению клиентом, в валюте платежного направления - <code>payway</code>; <strong><code>data.shop_currency</code></strong> - валюта списания с магазина по выплате; <strong><code>data.shop_payment_id</code></strong> - номер выплаты на стороне магазина; <strong><code>data.shop_write_off</code></strong> - сумма списания с баланса магазина в валюте <code>shop_currency</code>; <strong><code>data.status</code></strong> - текущий статус операции. <b>Внимание!</b> Запрос статуса выплаты необходимо совершать не чаще чем раз в минуту. ### Запрос статуса выплаты [POST] + Request ```json ```json { "shop_id": 6, "now": 1655815845, "withdraw_id": 15, "sign": "175365f50e85fa717be6cb5dc3e456b09c5d3e2e6ee7046286ef31019f87ff59" } + Response 200 () ```json ```json { "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] <div id="wdstatus_crypto"> </div> <table><tr><th>Status</th> <th>Значение</th> <th>Описание</th> <th>Финальный?</th></tr> <tr><td>1</td> <td><code>New</code></td> <td>Выплата создана, ожидает обработки</td> <td><strong>Нет,</strong> делать запрос статуса</td></tr> <tr><td>2</td> <td><code>Waiting</code></td> <td>Выплата создана, ожидает обработки</td> <td><strong>Нет,</strong> делать запрос статуса</td></tr> <tr><td>3</td> <td><code>Success</code></td> <td>Выплата успешно выполнена</td> <td><strong>Да,</strong> средства списаны с магазина</td></tr> <tr><td>4</td> <td><code>Rejected</code></td> <td>Выплата отклонена</td> <td><strong>Да,</strong> средства не списаны с магазина</td></tr> <tr><td>5</td> <td><code>ProcessingError</code></td> <td>Ошибка при выплате</td> <td><strong>Нет,</strong> делать запрос статуса</td></tr></table> ### Запрос статуса выплаты [POST] + Request ```json { "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 } # Group Криптовалютный баланс магазина ### Запрос криптовалютного баланса магазина [/crypto/shop_balance] <strong>URL:</strong> <code>https://core.qostiq.com/crypto/shop_balance</code> <strong>Метод:</strong> <code>POST</code> <strong>Обязательные параметры:</strong> <code>now, shop_id</code> <strong>Пример Запроса:</strong> <div> <ul> <li> { <li> <ul>"now"</ul>:<ul>1655821138</ul> </li> <li> <ul>"shop_id"</ul>:<ul>6</ul> </li> <li> <ul>"sign"</ul>:<ul>f2c67bc4f3cf7afdf9b08573de36d42b1fc1984d48187ef560d6163beeb907e7</ul> </li> } </li> </ul> </div> Где, <table><tr><th>Параметр</th> <th>Описание</th> <th>Формат</th> <th>Пример</th></tr> <tr><td><code>now</code></td> <td>время запроса, в формате unixtimestamp</td> <td>Integer</td> <td>1655821138</td></tr> <tr><td><code>shop_id</code></td> <td>идентификатор магазина в системе Qostiq</td> <td>Integer</td> <td>6</td></tr> <tr><td><code>sign</code></td> <td>подпись, см. п. <a href="#sign">Правила формирования подписи для операций с криптовалютой (sign)</a></td> <td>String</td> <td>"f2c67bc4f3cf7afdf9b08573de36d42b1fc1984d48187ef560d6163beeb907e7"</td></tr></table> <strong>Пример ответа:</strong> <div> <ul> <li> { <li>`"data"`:`{`</li> <li>`"balances"`:`[{` </li> <li><ul>"available"</ul>:<ul>"9.8",</ul></li> <li><ul>"currency"</ul>:<ul>"USDT",</ul> </li> <li><ul>"frozen"</ul>:<ul>"0.0",</ul> </li> <li><ul>"hold"</ul>:<ul>"0.0"</ul> </li> <li>`}, {`</li> <li><ul>"available"</ul>:<ul>"0.0000134",</ul></li> <li><ul>"currency"</ul>:<ul>"BNB",</ul> </li> <li><ul>"frozen"</ul>:<ul>"0.000103",</ul> </li> <li><ul>"hold"</ul>:<ul>"0.0010475903"</ul> </li> <li>`}],`</li> <li><ul>"shop_id"</ul>:<ul>6</ul> </li> <li><ul>},</ul></li> <li><ul>"error_code":</ul><ul>0,</ul></li> <li><ul>"message":</ul><ul>"Ok",</ul></li> <li><ul>"result":</ul><ul>true</ul></li> } </li> </ul> </div> Где, <strong><code>data.balances</code></strong> - массив данных по валютам на магазине в котором: <strong><code>data.balances.available</code></strong> - доступный для выплат баланс; <strong><code>data.balances.currency</code></strong> - валюта баланса; <strong><code>data.balances.frozen</code></strong> - замороженные средства на балансе, например, под созданную выплату, которая находится в обработке; <strong><code>data.balances.hold</code></strong> - временно удержанные средства. ### Запрос баланса магазина [POST] + Request ```json { "shop_id": 6, "now": 1655821138, "sign": "f2c67bc4f3cf7afdf9b08573de36d42b1fc1984d48187ef560d6163beeb907e7" } Response 200 () { "data": { "balances": [ { "available": "9.8", "currency": "USDT", "frozen": "0.0", "hold": "0.0" } ```, ```json { "available": "0.0000134", "currency": "BNB", "frozen": "0.000103", "hold": "0.0010475903" }], "shop_id": 6 }, "error_code": 0, "message": "Ok", "result": true } # Group Указание суммы операции ### Таблица точности сумм [/amount] <div id="amount"> </div> В таблице ниже указано рекомендуемое количество знаков после точки в параметрах <code>amount</code> и <code>shop_amount</code> при создании операций. <table><tbody> <tr><th>Блокчейн</th> <th>Валюта</th> <th><code>Payway</code></th> <th>К-во знаков</th></tr> <tr><td rowspan="1">Bitcoin</td> <td>BTC</td> <td><code>btc_btc</code></td> <td>8</td></tr> <tr><td rowspan="1">Litecoin</td> <td>LTC</td> <td><code>ltc_ltc</code></td> <td>8</td></tr> <tr><td rowspan="3">Polygon</td> <td>MATIC</td> <td><code>matic_polygon</code></td> <td>18</td></tr> <tr><td>USDT</td> <td><code>usdt_polygon</code></td> <td>6</td></tr> <tr><td>BUSD</td> <td><code>busd_polygon</code></td> <td>18</td></tr> <tr><td rowspan="2">TRON</td> <td>TRX</td> <td><code>trx_trc20</code></td> <td>6</td></tr> <tr><td>USDT</td> <td><code>usdt_trc20</code></td> <td>6</td></tr> <tr><td rowspan="2">Ethereum</td> <td>ETH</td> <td><code>eth_erc20</code></td> <td>18</td></tr> <tr><td>USDT</td> <td><code>usdt_erc20</code></td> <td>6</td></tr> <tr><td rowspan="2">Binance Smart Chain</td> <td>BNB</td> <td><code>bnb_bep20</code></td> <td>18</td></tr> <tr><td>USDT</td> <td><code>usdt_bep20</code></td> <td>18</td></tr> </tbody></table> <b>Внимание!</b> Не все десятичные числа можно точно представить с помощью двоичной системы исчисления. Для работы с суммами рекомендуется использовать десятичные типы данных (например: тип decimal.Decimal в Python-е). При указании значения параметра <code>amount</code> с большей точностью - система Qostiq вернет в ответе округленное значение суммы списания/получения. ### Пример запроса с округлением суммы [POST] + Request ```json { "amount": 0.100000889, "amount_type": "ps_amount", "payway": "usdt_erc20", "shop_currency": "USDT", "shop_id": 6, "now": 1659081383, "sign": "e60d8f25564f7191cc170557a34102228307b0b267eeba7ee0cc5732bbb2f235" } Response 200 () { "data": { "payee_currency": "USDT", "payee_receive": "0.100001", "shop_currency": "USDT", "shop_write_off": "0.10300103" } ```, "error_code": 0, "message": "Ok", "result": true } ## Group Контакты При возникновении вопросов, Вы всегда можете обратиться в нашу службу поддержки support@qostiq.com ``` ```

История изменений API:
Работа через страницу оплаты PAY
Логотипы Qostiq
Group Операции с кошельком Qostiq
Group Функционал Qostiq Wallet по подписке
Group Создание платежа
Когда суммы могут измениться?
Group Создание выплаты
Group Прочие методы по магазину
Group Криптовалютные платежи с персонального кошелька Qostiq
Group Криптовалютные выплаты на персональный кошелек Qostiq
Group Криптовалютные платежи
Group Криптовалютные выплаты

Status	Значение	Описание	Финальный?
1	`Waiting`	Счет создан, ожидает оплаты	Нет
2	`Success` - значение приходит в уведомлении	Счет оплачен	Да,средства зачислены на баланс магазина
3	`Rejected` - значение приходит в уведомлении	Клиент отменил счет	Да, средства не зачислены на баланс магазина
4	`Expired`	Срок возможной оплаты счета исчерпан	Да, средства не зачислены на баланс магазина

Параметр	Описание	Формат	Пример
`amount`	сумма выплаты	String или number, количество знаков после запятой смотрите детальней в пункте "Указание суммы операции"	"1.00000001" или 1.00000001
`amount_type`	указывает на тип суммы `amount`, возможны значения: receive_amount – сумма к получению на кошелек в валюте `payer_currency`, writeoff_amount - сумма к списанию с баланса магазина в валюте `shop_currency`	String	"receive_amount" или "writeoff_amount"
`now`	время запроса, в формате unixtimestamp	Integer	1691400155
`payer_currency`	валюта получения средств на кошелек клиента	String	"TRX"
`shop_currency`	валюта списания средств с баланса магазина	String	"TRX "
`shop_id`	идентификатор магазина в системе Qostiq	Integer	6
`sign`	подпись, см. п. Правила формирования подписи для операций с криптовалютой (sign)	String	"e77dc50d3e4bc3b307924aaefeab1887d38e1aa0d73ba17a2bdad99893b984e6"

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

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

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

Параметр	Описание	Формат	Пример
`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"

Параметр	Описание	Формат	Обязательный параметр?	Пример
`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"

История изменений API:​

Создание магазина​

Настройка безопасности​

Правила формирования подписи​

Работа через страницу оплаты PAY​

Общая информация по PAY​

Выставление счета для оплаты через PAY​

Общая информация по странице PAY (Crypto)​

Выставление счета для оплаты через PAY страницу (Crypto)​

Логотипы Qostiq​

Group Операции с кошельком Qostiq​

Выставление счетов Bill [/bill/create]​

Выставить счет Qostiq [POST]​

Выставление счетов Bill v.2 с возможностью оплаты на свободную сумму [/bill/create/v2]​

Выставить счет Qostiq [POST]​

Запрос статуса Bill [/bill/shop_order_status]​

Статус операций Bill [/bill/status]​

Запрос статуса Bill при неуникальном shop_order_id [POST]​

Предварительный расчет выплаты на кошелек: Transfer [/transfer/try]​

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

Вывод средств на кошелек: Transfer [/transfer/create]​

Перевести средства с баланса магазина [POST]​

Вывод средств на кошелек: Transfer [/transfer/create]​

Перевести средства с баланса магазина [POST]​

Запрос статуса Transfer [/transfer/shop_payment_status]​

Запросить статус transfer [POST]​

Group Функционал Qostiq Wallet по подписке​

Запрос на создание подписки [/auth_token/request]​

Пример запроса на создание подписки [POST]​

Уведомление активации и отмене подписки [/auth_token/callback]​

Уведомление об отмене подписки [POST]​

Создание фиатного платежа по подписке [/bill/recurrent]​

Создание фиатного платежа по подписке [POST]​

Создание криптовалютного платежа по подписке [/crypto/bill/recurrent]​

Запрос на создание криптовалютного платежа по подписке [POST]​

Запрос на отмену подписки [/auth_token/revoke]​

Запрос на отмену подписки [POST]​

Запрос статуса фиатного платежа по подписке [/bill/shop_order_status]​

Запрос статуса фиатного платежа по подписке [POST]​

Запрос статуса криптовалютного платежа по подписке [/crypto/bill/shop_order_status]​

Запрос статуса криптовалютного платежа по подписке [POST]​

Статус платежей по подписке [/bill/status]​

Запрос статуса Bill при неуникальном shop_order_id [POST]​

Ошибки при использовании функционала по подписке [/error]​

Запрос c ошибкой в ответе [POST]​

Group Создание платежа​

Общие рекомендации по работе с API выставления счетов для оплаты​

Предварительный расчет инвойса [/invoice/try]​

Предварительный расчет инвойса [POST]​

Выставление счета [/invoice/create]​

Когда суммы могут измениться?​

Как обрабатывать ответы:​

Случай 1: Сумма не изменилась(is_overwritten: false)​

Случай 2: Сумма изменилась(is_overwritten: true)​

Выставление счета - invoice [POST]​

Возможные ошибки [/invoice/errors]​

Пример получения ошибки [POST]​

Оффлайн методы оплаты [/invoice/offline]​

Пример запроса на оплату Оффлайн способом [POST]​

Уведомление после оплаты [/invoice/callback]​

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

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

Запрос статуса [/invoice_check]​

Запросить статус счета [POST]​

Статус операций Invoice [/invoice/allstatuses]​

Запросить статус счета [POST]​

Group Создание выплаты​

Предварительный расчет выплаты [/withdraw/try]​

Запросить расчет выплаты[POST]​

Проверка аккаунта [/check_account]​

Запросить проверку[POST]​

Создание вывода средств [/withdraw/create]​

Вывести средства с магазина [POST]​

Запрос статуса по withdraw_id [/withdraw/status]​

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

Запрос статуса по shop_payment_id [/withdraw/shop_payment_status]​

Запросить статус выплаты по транзакции [POST]​

Уведомление по выплате [/withdraw/callback]​

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

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

История изменений API:

Создание магазина

Настройка безопасности

Правила формирования подписи

Работа через страницу оплаты PAY

Общая информация по PAY

Выставление счета для оплаты через PAY

Общая информация по странице PAY (Crypto)

Выставление счета для оплаты через PAY страницу (Crypto)

Логотипы Qostiq

Group Операции с кошельком Qostiq

Выставление счетов Bill [/bill/create]

Выставить счет Qostiq [POST]

Выставление счетов Bill v.2 с возможностью оплаты на свободную сумму [/bill/create/v2]

Выставить счет Qostiq [POST]

Запрос статуса Bill [/bill/shop_order_status]

Статус операций Bill [/bill/status]

Запрос статуса Bill при неуникальном shop_order_id [POST]

Предварительный расчет выплаты на кошелек: Transfer [/transfer/try]

Предварительный расчет выплаты [POST]

Вывод средств на кошелек: Transfer [/transfer/create]

Перевести средства с баланса магазина [POST]

Вывод средств на кошелек: Transfer [/transfer/create]

Перевести средства с баланса магазина [POST]

Запрос статуса Transfer [/transfer/shop_payment_status]

Запросить статус transfer [POST]

Group Функционал Qostiq Wallet по подписке

Запрос на создание подписки [/auth_token/request]

Пример запроса на создание подписки [POST]

Уведомление активации и отмене подписки [/auth_token/callback]

Уведомление об отмене подписки [POST]

Создание фиатного платежа по подписке [/bill/recurrent]

Создание фиатного платежа по подписке [POST]

Создание криптовалютного платежа по подписке [/crypto/bill/recurrent]

Запрос на создание криптовалютного платежа по подписке [POST]

Запрос на отмену подписки [/auth_token/revoke]

Запрос на отмену подписки [POST]

Запрос статуса фиатного платежа по подписке [/bill/shop_order_status]

Запрос статуса фиатного платежа по подписке [POST]

Запрос статуса криптовалютного платежа по подписке [/crypto/bill/shop_order_status]

Запрос статуса криптовалютного платежа по подписке [POST]

Статус платежей по подписке [/bill/status]

Запрос статуса Bill при неуникальном shop_order_id [POST]

Ошибки при использовании функционала по подписке [/error]

Запрос c ошибкой в ответе [POST]

Group Создание платежа

Общие рекомендации по работе с API выставления счетов для оплаты

Предварительный расчет инвойса [/invoice/try]

Предварительный расчет инвойса [POST]

Выставление счета [/invoice/create]

Когда суммы могут измениться?

Как обрабатывать ответы:

Случай 1: Сумма не изменилась(is_overwritten: false)

Случай 2: Сумма изменилась(is_overwritten: true)

Выставление счета - invoice [POST]

Возможные ошибки [/invoice/errors]

Пример получения ошибки [POST]

Оффлайн методы оплаты [/invoice/offline]

Пример запроса на оплату Оффлайн способом [POST]

Уведомление после оплаты [/invoice/callback]

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

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

Запрос статуса [/invoice_check]

Запросить статус счета [POST]

Статус операций Invoice [/invoice/allstatuses]

Запросить статус счета [POST]

Group Создание выплаты

Предварительный расчет выплаты [/withdraw/try]

Запросить расчет выплаты[POST]

Проверка аккаунта [/check_account]

Запросить проверку[POST]

Создание вывода средств [/withdraw/create]

Вывести средства с магазина [POST]

Запрос статуса по withdraw_id [/withdraw/status]

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

Запрос статуса по shop_payment_id [/withdraw/shop_payment_status]

Запросить статус выплаты по транзакции [POST]

Уведомление по выплате [/withdraw/callback]

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

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