Создание платежа
Общие рекомендации по работе с 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)
{
"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 | идентификатор магазина в системе 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 < расчётного значения |
Пример ошибки при выставлении инвойса:
{
"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
| Код ошибки | Описание |
|---|---|
| 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)
{
"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 | идентификатор магазина в системе Qostiq | Integer | 1 |
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 | Значение | Описание | Финальный? |
|---|---|---|---|
| 1 | Created | Создан запрос на платеж | Нет |
| 2 | Waiting | Платеж находится в стадии ожидания действий пользователя | Нет |
| 3 | PsCreatingError | Ошибка создания платежа на стороне платежной системы | Нет |
| 4 | Success | Оплата успешно выполнена | Да |
| 5 | CallbackError | Ошибка получения уведомления об оплате со стороны платежной системы | Нет |
| 6 | Rejected | Отклонен на стороне платежной системы | Да |
| 7 | Refunded | Сумма счета возвращена плательщику платежной системой | Да |
| 8 | Hold | Средства по оплате счета удержаны (холдирование) платежной системой | Нет |
| 9 | IntRefunded | Сумма счета возвращена плательщику системой Qostiq | Да |
| 10 | Captured | Средства по оплате счета заблокированы платежной системой | Нет |
Внимание! Статус 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
}