Криптовалютные платежи с персонального кошелька 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 секунд.

Если 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
    }
    ```