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

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

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

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

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

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

  3. После проверки try отправляется запрос на выставление счет invoice, с указанием обязательных параметров и дополнительной информации в add_ons_config (если она является обязательной для указанного платежного направления);

  4. В ответе возвращается информация с выставленным счетом и данными для отправки указанным методом на указанный URL, для совершения оплаты;

  5. После совершения оплаты, система 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идентификатор магазина в системе QostiqInteger5
amountсумма выставленного счетаNumber (Не больше 2х знаков после точки)1, 1.0, 1.00 или "1.00"
currencyвалюта выставленного счетаInteger980 - Украинская гривна, 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)
{
"currency": "980",
"sign": "912b985f18959620bb981485132016b58fc344361a51a24eda27687613141f7f",
"payway": "card_uah",
"amount": "12.34",
"shop_id": 112,
"shop_order_id": 4128
}
  • Response 200 ()
{
"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идентификатор магазина в системе QostiqInteger5
amountсумма выставленного счетаNumber (Не больше 2х знаков после точки)1, 1.0, 1.00 или "1.00"
currencyвалюта выставленного счетаInteger980 - Украинская гривна, 840 - Доллар США, 978 - Евро
paywayплатежное направление, для которого производится предварительный расчетString"card_uah" (можно уточнить у менеджера или в личном кабинете)
signподписьString"a7f5bcbb774cea9d9886cbb3ce2f8731359e356a7d759437b4e9e31da1152109"
shop_order_idномер счета на стороне Вашего сервисаString"h8fj38dkh-hf8k-4f8d-9c8c-jd8dh38dksn92"

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

ПараметрОписаниеФорматПример
descriptionописание выставленного счета (не обязательный параметр)String"test bill"
failed_urlURL, на который будет перенаправлен плательщик, после не успешной оплаты счетаString"https://qostiq.com/failed"
success_urlURL, на который будет перенаправлен плательщик, после успешной оплаты счетаString"https://qostiq.com/success"
callback_urlURL адрес на который будет отправляться уведомление об успешной оплатеString"https://qostiq.com/callback_url_kvt"
callback_rejected_urlURL адрес на который будет отправляться уведомление о неуспешной оплате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
}

Где,

ПараметрОписание
datasource для отправки методом method параметров из data
methodметод отправки data на source, формат: POST, GET
urlURL на который необходимо отправить 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 < расчётного значения

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

{
"data": null,
"message": "Payway (id=3) is not found",
"error_code": 1,
"result": false
}

Где

ПараметрОписание
messageописание ошибки
error_codeкод ошибки

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

  • Request (application/json)
{
"currency": "980",
"payway": "card_uah",
"amount": "12.34",
"shop_id": 112,
"shop_order_id": 4129,
"description": "Test invoice",
"sign": "8fb2cafda4da9de1f1c00787dd5d22e6a8094256d0e47b633783f652624b81d4"
}
  • Response 200 ()
{
"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

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

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

  • Request (application/json)
{
"amount": "120000.00",
"currency": 980,
"payway": "card_uah",
"shop_id": 112,
"shop_order_id": 4129,
"description": "Test invoice",
"sign": "8fb2cafda4da9de1f1c00787dd5d22e6a8094256d0e47b633783f652624b81d4"
}
  • Response 200 ()
{
"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)
{
"amount": 100,
"currency": 980,
"payway": "vodafone_uah",
"phone": "9827908437",
"shop_id": "112",
"shop_order_id": "Invoice#61586603",
"sign": "56789cc6d34ebc6e064daf416911baa9ae3aac9ca269e3566b13236cc554e1fb"
}
  • Response 200 ()
{
"data": {
"data": {
"en": "<h4>Уважаемый клиент!</h4> <p>Ваш запрос успешно принят. Вам отправлено СМС с подробной инструкцией для завершения оплаты.</p>",
"ru": "<h4>Уважаемый клиент!</h4> <p>Ваш запрос успешно принят. Вам отправлено СМС с подробной инструкцией для завершения оплаты.</p>"
},
"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)
{
"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 ()
{
"response_data": "OK",
"shop": 112,
"transfer": null,
"withdraw": null
}

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

  • Request (application/x-www-form-urlencoded)
{
"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 ()
{
"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идентификатор магазина в системе QostiqInteger1
shop_order_idномер счета на стороне Вашего сервисаString"123456789"
signподписьString"32b2c32caa8adecf89c6dfa72ffca3a0506f33febfe3aaab090cdbfbd0e8b953"

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

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

Где,

ПараметрОписание
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)
{
"now": "2018-06-15 09:58:01.01",
"shop_id": 1,
"shop_order_id": "123456789",
"sign": "32b2c32caa8adecf89c6dfa72ffca3a0506f33febfe3aaab090cdbfbd0e8b953"
}
  • Response 200 ()
{
"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ЗначениеОписаниеФинальный?
1CreatedСоздан запрос на платежНет
2WaitingПлатеж находится в стадии ожидания действий пользователяНет
3PsCreatingErrorОшибка создания платежа на стороне платежной системыНет
4SuccessОплата успешно выполненаДа
5CallbackErrorОшибка получения уведомления об оплате со стороны платежной системыНет
6RejectedОтклонен на стороне платежной системыДа
7RefundedСумма счета возвращена плательщику платежной системойДа
8HoldСредства по оплате счета удержаны (холдирование) платежной системойНет
9IntRefundedСумма счета возвращена плательщику системой QostiqДа
10CapturedСредства по оплате счета заблокированы платежной системойНет

Внимание! Статус Rejected может быть сменен на Success.

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

  • Request (application/json)
{
"now": "2018-06-15 09:58:01.01",
"shop_id": 1,
"shop_order_id": "123456789",
"sign": "32b2c32caa8adecf89c6dfa72ffca3a0506f33febfe3aaab090cdbfbd0e8b953"
}
  • Response 200 ()
{
"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
}