Основные положения
Сервис предназначен для отказа от платежа. Сервис может применяться в тех случаях, когда заказ инициирован, но не будет оплачен, при этом необходимо завершить его до истечения тайм-аута. Например, покупатель передумал или хочет изменить заказ, а на стороне предприятия при изменении корзины номер заказа остается неизменным.
В процессе отказа осуществляется изменение статуса созданного заказа с In Process на Declined, со стороны предприятия можно инициировать оплату нового заказа с тем же номером OrderNumber.
Заказ будет завершен со статусом Declined в том случае, если на момент вызова сервиса оплата только начата (например, покупатель еще не ввел данные карты), и еще не отправлена в процессинг транзакция авторизации, в противном случае сервис вернет ошибку (такие заказы следует отменять с помощью сервиса для отмены заказа).
Описание сервиса
Для обращения к веб-сервису необходимо отправить запрос (методом POST с content-type application/json) на сервер ASSIST по адресу: https://<server-name>/api/v1/order/cancel.cfm.
Входные параметры сервиса:
Параметр | Обязательный | Принимаемые значения | Значение по умолчанию | Описание |
Merchant_ID | Да | Число | Идентификатор предприятия в системе АПК Ассист | |
OrderNumber | Да | 128 символов | Номер заказа в системе расчетов предприятия. |
В запросе необходимо передать HTTP-заголовок Authorization:
Bearer <token>, где <token> — токен доступа.
Для получения токена доступа необходимо использовать сервис https://<server-name>/api/v1/auth/login.cfm с указанием audience="POS" и components="ws/cancelbynumber".
Для получения токена с возможностью отказа от платежа у пользователя должны быть права на отказ от платежа (Web Services -> Отмена по номеру заказа). Если прав недостаточно, то при попытке получить токены с audience="POS" будет получен ответ:
{"faultcode":"159","faultstring":"no scopes"}
Пример запроса
POST https://<server-name>/api/v1/order/cancel.cfm headers: [Authorization: Bearer eyJraWQiOiIwYWZlZTE0Mi1hMGFmLTQ0MTAtYWJjY...65s0sKKV1TefvGecmFbCqizljU4toyROW54f0Y, Content-type: application/json] Body: { "merchant_id": "123456", "ordernumber": "dd2" }
Выходные параметры
При успешном изменении статуса заказа сервис вернет новый статус заказа со значением Declined:
{"cancel": {"orderstate": "Declined"}}
В остальных случаях сервис вернет соответствующие ошибки:
- при попытке отменить заказ в статусе, отличном от статуса "In Process":
{"fault": {"faultcode": 15,"faultstring": 146}}
- при попытке вызвать сервис без права "Отмена по номеру заказа" у пользователя:
{"fault": {"faultcode": 2,"faultstring": 0}}
- при попытке отменить несуществующий заказ:
{"fault": {"faultcode": 10,"faultstring": 201}}
Получение токенов доступа
Сервис предназначен для получения токенов доступа. Если на момент запроса уже имеются активные токены доступа, то они будут возвращены в ответе. Сам JWT-токен будет обновлен, так как он включает новую дату выдачи.
Для обращения к веб-сервису необходимо отправить запрос (методом POST с content-type application/json) на сервер ASSIST по адресу: https://<SERVER-NAME>/api/v1/auth/login.cfm.
Входные параметры сервиса:
Параметр | Обязательный | Принимаемые значения | Значение по умолчанию | Описание |
login | Да | Строка | Логин пользователя | |
password | Да | Строка | Пароль пользователя | |
audience | Да | Строка | Область применения токена | |
components | Да | Строка | Компоненты доступа по токену |
Выходные параметры:
Название | Значение |
access_token | Токен доступа, используется для доступа к сервисам |
refresh_token | Токен обновления, используется для обновления токена доступа |
Пример запроса
POST https://<SERVER-NAME>/api/v1/auth/login.cfm headers: [Content-type: application/json] content: {"Login":"***","Password":"***","audience":"POS", "components":"ws/cancelbynumber"}
Пример ответа
{ "access_token":"eyJraWQiOiIwYWZlZTE...HydFlTU", "refresh_token":"eyJraWQiOiIwYWZlZT...nKTY9M" }
Обновление токена доступа
Для обращения к веб-сервису необходимо отправить запрос (методом POST с content-type application/json) на сервер ASSIST по адресу: https://<SERVER-NAME>/api/v1/auth/refresh.cfm
Входные параметры сервиса:
Параметр | Обязательный | Принимаемые значения | Значение по умолчанию | Описание |
refresh_token | Да | Строка | Токен обновления |
Выходные параметры:
Название | Значение |
access_token | Токен доступа, используется для доступа к сервисам |
refresh_token | Токен обновления, используется для обновления токена доступа |