Click-API – Запросы
Описание взаимодействия
Взаимодействие осуществляется через API-интерфейс, расположенный на сервере Поставщика. API-интерфейс полностью должен соответствовать требованиям данного документа. Созданный платеж в системе CLICK передается по протоколу HTTP (HTTPS) методом POST API- интерфейсу Поставщика услуг. Поставщик предоставляет системе CLICK URL-адреса для взаимодействия с API-интерфейсом. Взаимодействие разделено на два этапа:
1. Prepare
2. Complete
Описание этапов проведения оплаты:
Подготовка и проверка платежа (Prepare). Action = 0.
Параметры запроса:
| # | Наименование параметра | Тип данных | Описание |
|---|---|---|---|
| 1 | click_trans_id | bigint | Номер транзакции (итерации) в системе CLICK, т.е. попытки провести платеж. |
| 2 | service_id | int | ID сервиса |
| 3 | click_paydoc_id | bigint | Номер платежа в системе CLICK. Отображается в СМС у клиента при оплате. |
| 4 | merchant_trans_id | varchar | ID заказа(для Интернет магазинов)/лицевого счета/логина в биллинге поставщика |
| 5 | amount | float | Сумма оплаты (в сумах) |
| 6 | action | int | Выполняемое действие. Для Prepare — 0 |
| 7 | error | int | Код статуса завершения платежа. 0 – успешно. В случае ошибки возвращается код ошибки. |
| 8 | error_note | varchar | Описание кода завершения платежа. |
| 9 | sign_time | varchar | Дата платежа. Формат «YYYY-MM-DD HH:mm:ss» |
| 10 | sign_string | varchar | Проверочная строка, подтверждающая подлинность отправляемого запроса. ХЭШ MD5 из следующих параметров:
md5( click_trans_id + service_id + SECRET_KEY* + merchant_trans_id + amount + action + sign_time) SECRET_KEY – уникальная строка, выдаваемая Поставщику при подключении. |
Параметры ответа:
| # | Наименование параметра | Тип данных | Описание |
|---|---|---|---|
| 1 | click_trans_id | bigint | ID платежа в системе CLICK |
| 2 | merchant_trans_id | varchar | ID заказа(для Интернет магазинов)/лицевого счета/логина в биллинге поставщика |
| 3 | merchant_prepare_id | int | ID платежа в биллинг системе поставщика для подтверждения |
| 4 | error | int | Код статуса запроса. 0 – успешно. В случае ошибки возвращается код ошибки |
| 5 | error_note | varchar | Описание кода завершения платежа. |
Данным запросом система CLICK по параметрам платежа (merchant_trans_id, amount) проверяет:
a. Наличие сформированного заказа/логина/номера лиц.счета в биллинг системе Поставщика, его актуальность, а также возможность Поставщиком отпустить указанный в заказе товар или услугу.
Примечание. Для интернет-магазина, при получении запроса поставщик по указанному номеру заказа должен зарезервировать соответствующий товар, для предотвращения «перехвата» его другим и покупки одного и того же товара несколькими покупателями.
b. Актуальность суммы заказа или оплаты.
На данный запрос Поставщик должен вернуть состояние заказа/логина/номера лиц.счета:
a. Заказ/логин/номера лиц.счета и сумма актуальны. Ожидает оплаты.
При получении данного статуса со стороны системы CLICK будет отправлен запрос Complete.
b. Заказ/логин/номер лиц.счета неактуален (отменен). При данном ответе со стороны CLICK будет отправлен запрос Complete c признаком отмены платежа.
Примечание. При получении отрицательного ответа от Поставщика в случае если уже средства со счета Пользователя были списаны (запрос давался повторно, если на предыдущий запрос Complete система CLICK не дождалась ответа и не знает о состоянии заказа.), то система CLICK, будет давать запрос Complete с признаком подтверждения платежа. Если средства не списаны, то CLICK также аннулирует платеж.
c. Заказ ранее был подтвержден. При данном ответе со стороны системы CLICK будет завершен платеж. Запрос Complete повторно направлен не будет.
Примечание. Поставщик должен в своей биллинг системе поставить защиту от повторного проведения платежа, ранее уже подтвержденного, с одним и тем же click_trans_id.
Завершение платежа (Complete). Action = 1.
Параметры запроса:
| # | Наименование параметра | Тип данных | Описание |
|---|---|---|---|
| 1 | click_trans_id | bigint | ID платежа в системе CLICK |
| 2 | service_id | int | ID сервиса |
| 3 | click_paydoc_id | bigint | Номер платежа в системе CLICK. Отображается в СМС у клиента при оплате. |
| 4 | merchant_trans_id | varchar | ID заказа(для Интернет магазинов)/лицевого счета/логина в биллинге поставщика |
| 5 | merchant_prepare_id | int | ID платежа в биллинг системе поставщика для подтверждения, полученный при запросе «Prepare» |
| 6 | amount | float | Сумма оплаты (в сумах) |
| 7 | action | int | Выполняемое действие. Для Complete — 1 |
| 8 | error | int | Код статуса завершения платежа. 0 – успешно. В случае ошибки возвращается код ошибки. |
| 9 | error_note | varchar | Описание кода завершения платежа. |
| 10 | sign_time | varchar | Дата платежа. Формат «YYYY-MM-DD HH:mm:ss» |
| 11 | sign_string | varchar | Проверочная строка, подтверждающая подлинность отправляемого запроса. ХЭШ MD5 из следующих параметров:
md5( click_trans_id + service_id + SECRET_KEY* + merchant_trans_id + merchant_prepare_id + amount + action + sign_time ) SECRET_KEY – уникальная строка, выдаваемая Поставщику при подключении. |
Параметры ответа:
| # | Наименование параметра | Тип данных | Описание |
|---|---|---|---|
| 1 | click_trans_id | bigint | ID платежа в системе CLICK |
| 2 | merchant_trans_id | varchar | ID заказа(для Интернет магазинов)/лицевого счета/логина в биллинге поставщика |
| 3 | merchant_confirm_id | int | ID транзакции завершения платежа в биллинг системе (может быть NULL) |
| 4 | error | int | Код статуса запроса. 0 – успешно. В случае ошибки возвращается код ошибки. |
| 5 | error_note | varchar | Описание кода завершения платежа. |
Данный запрос завершает процесс он-лайн оплаты. При получении от Поставщика услуг положительного ответа на запрос Prepare система CLICK проверяет возможность оплаты заказа Пользователем. В зависимости от успешности списания средств, запрос Complete содержит параметр error со следующими значениями:
1. «0» – Успешно. Посылается при успешном списании средств. При этом Поставщик должен отпустить товар или оказать оплаченную услугу.
2. «<=-1» – Отмена. Посылается при ошибке списания средств или при других ошибках, возвращается код ошибки. При этом Поставщик должен снять бронь (при имении таковой) с товаров, а так же вернуть ответ с кодом -9 (см. таблицу ответов). При отмене со стороны CLICK будет так же отправлено описание ошибки.
Примечание.
При успешном ответе на запрос Prepare и успешном списании средств с карты, ответ на запрос Complete не может быть ошибочным (кроме случаев, когда платеж уже ранее был подтвержден error = -4 или идет повторная попытка подтвердить ранее отмененного платежа error = -9). При получении ошибочного ответа от поставщика, после нескольких попыток, платеж зависнет для ручного разбирательства со стороны Службы технической поддержки CLICK.
При необходимости, если возникла ошибка предоставления услуг/продажи товара после успешного списания средств с карты и во время выполнения запроса Complete, то Биллинг поставщика отвечает на запрос Complete «успешно» и отправляет запрос на «отмену платежа» (см. документацию CLICK-API-MERCHANT пункт 3. Payment_cancel)