Перейти к основному содержимому

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

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

  1. Запрос /auth_token/request для создания подписки. В ответе на запрос создания подписки вернется URL адрес на который необходимо выполнить редирект клиента для подтверждения им подписки.
  2. После подтверждения подписки клиентом на указанный в настройках магазина URL будет выслан уникальный token который будет использоваться в дальнейших запросах.
  3. Запрос на выполнения действия разрешенного для указаного token (например запрос списания фиатных средств /bill/recurrent).
  4. При необходимости отключения подписки подписки и деактивации токена - необхдимо выполнить запрос /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": "test_external_id",
    "now": 1691584193,
    "scopes": ["bill_recurrent"],
    "shop_id": 6,
    "sign": "912b985f18959620bb981485132016b58fc344361a51a24eda27687613141f7f"
}

Где,

ПараметрОписаниеФорматПример
external_idномер или название подписки (видны клиенту)String"test_external_id"
nowвремя запросаInteger1691584193
scopesтип подпискиArray["bill_recurrent"] - значение для получения токена на платежи по подписке
shop_idидентификатор магазина в системе QostiqInteger6
signподписьString"912b985f18959620bb981485132016b58fc344361a51a24eda27687613141f7f"
  • Пример ответа:
{
    "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)
{
    "external_id": "external_id",
    "now": 1691584193,
    "scopes": [
        "bill_recurrent"
    ],
    "shop_id": 6,
    "sign": "912b985f18959620bb981485132016b58fc344361a51a24eda27687613141f7f"
}
  • Response 201 (application/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 токенам.

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

  • Пример уведомления об активации подписки:
{
    "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)
{
    "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

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

  • Пример запроса:
{
    "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валюта выставленного счетаInteger840 - Доллар США, 980 - Украинская гривна, 978 - Евро, 398 - Казахстанский тенге
shop_idидентификатор магазина в системе QostiqInteger6
nowвремя запросаInteger1691584193
tokenтокен подписки полученый в ответе на запрос создания подписки.String"f1cebac7-e05b-4c94-bb26-a222b976cb2d"
scopesтип подпискиArray["bill_recurrent"] - значение для получения токена на платежи по подписке
shop_order_idномер счета на стороне Вашего сервисаString"123456789"
signподписьString"912b985f18959620bb981485132016b58fc344361a51a24eda27687613141f7f"
  • Пример ответа:
{
    "data": {
        "id": 2177,
        "status": 2
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

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

ПараметрОписание
idуникальный id платежа в рамках фиатных платежей с кошелька Qostiq
statusстатус платежа, где значение 2 — платеж успешен

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

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

  • Request (application/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)
{
    "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

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

  • Пример запроса:
{
    "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идентификатор магазина в системе QostiqInteger6
nowвремя запросаInteger1691669000
tokenтокен подписки полученый в ответе на запрос создания подписки.String"f1cebac7-e05b-4c94-bb26-a222b976cb2d"
scopesтип подпискиArray["bill_recurrent"] - значение для получения токена на платежи по подписке
shop_order_idномер счета на стороне Вашего сервисаString"test payment"
signподписьString"ac3503d0b2e21c4716c96fbd58f32da678cf0a179a34bdf60ce5f36016efa2a2"
  • Пример ответа:
{
    "data": {
        "id": 1579,
        "status": 2
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

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

ПараметрОписание
idуникальный id платежа в рамках криптовалютных платежей с кошелька Qostiq
statusстатус платежа, где значение 2 — платеж успешен

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

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

  • Request (application/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)
{
    "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

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

  • Пример запроса:
{
    "shop_id": 6,
    "token": "44c6703d-9f98-434d-936f-9e6784976c98",
    "now": 1691671996,
    "sign": "8f15f065b07f6a2150277d57e125f3133ae4f9cab31f3529aaa8d6daa97b0c1d"
}

Где:

ПараметрОписаниеФорматПример
shop_idидентификатор магазина в системе QostiqInteger6
nowвремя запросаInteger1691671996
tokenтокен подписки полученый в ответе на запрос создания подписки.String"44c6703d-9f98-434d-936f-9e6784976c98"
signподписьString"ac3503d0b2e21c4716c96fbd58f32da678cf0a179a34bdf60ce5f36016efa2a2"
  • Пример ответа, при успешном закрытии подписки в ответе вернется токен подписки:
{
    "data": {
        "token": "44c6703d-9f98-434d-936f-9e6784976c98"
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}
  • Если подписка уже отменена будет получена ошибка:
{
    "data": null,
    "error_code": 10,
    "message": "Auth token (44c6703d-9f98-434d-936f-9e6784976c98) not found",
    "result": false
}

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

  • Request (application/json)
{
    "shop_id": 6,
    "token": "44c6703d-9f98-434d-936f-9e6784976c98",
    "now": 1691671996,
    "sign": "8f15f065b07f6a2150277d57e125f3133ae4f9cab31f3529aaa8d6daa97b0c1d"
}
  • Response 200 (application/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идентификатор магазина в системе QostiqInteger1092
shop_order_idномер счета на стороне Вашего сервисаString"234234232323"
signподписьString"b9b838e0b1baedcf7dd60711b1afab246c3496b5cc3433df0c5a2e2d07fea976"

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

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

Где,

ПараметрОписание
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 секунд.

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

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

  • Request (application/json)
{
    "now": "2021-05-01 16:56:25.009469",
    "shop_id": "1092",
    "shop_order_id": "234234232323",
    "sign": "ad7fbe8df102bc70e28deddba8b45bb3f4e6cafdaa69ad1ecc0e8b1d4e770575"
}
  • Response 200 ()
{
    "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время запроса, в формате unixtimestampInteger1691676646
shop_idидентификатор магазина в системе QostiqInteger6
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 секунд.

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

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

  • Request
{
    "now": 1691676646,
    "shop_id": 6,
    "shop_order_id": "test payment",
    "sign": "97a8d477e41d7e61af1a65ac9c662d1b28064aa4248a4eebb641deb5524e37f1"
}
  • Response 200 ()
{
    "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НазваниеОписаниеФинальный?
1WaitingПлатеж находится в стадии ожидания действий пользователяНет
2PaidПлатеж оплачен клиентомДа
3CanceledПлатеж отменен клиентомДа
4ExpiredИстёк срок жизни счётаДа

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

  • Request (application/json)
{
    "now": "2021-05-01 16:56:25.009469",
    "shop_id": "112",
    "shop_order_id": "123billtest",
    "sign": "6fb934f7e00d205cb5ebb62117d9b74029d84c2ffc7c87fe5b38ac5196fecf02"
}
  • Response 200 ()
{
    "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_codemessageОписание
/bill/recurrent /crypto/bill/recurrent /auth_token/revoke10Auth token ({token}) not foundТокен не существует или неактивный
/bill/recurrent /crypto/bill/recurrent9Insufficient payer (id=6) balanceНедостаточно средств для списания на кошельке клиента
/bill/recurrent /crypto/bill/recurrent44Limit exceedsПревышен установленый клиентом лимит на оплату по подписке

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

  • Request
{
    "amount":"1",
    "currency":840,
    "shop_id": 6,
    "token": "0b2808dc-3b6e-48d0-ac9b-64e31b756182",
    "now": 1692098067,
    "shop_order_id":"test payment",
    "sign": "8a461f70b3a8d4f5e2668f9de4ad17c8d1759f891333caf03ae9f50d5015618d"
}
  • Response 200 ()
{
    "data": null,
    "error_code": 44,
    "message": "Limit exceeds",
    "result": false
}