Сценарии работы с сервисом

Аутентификация

Для аутентификации при отправке большинства запросов в заголовке запроса должен быть передан аутентификационный атрибут Authorization, содержащий значение accessToken (токен безопасности). Список запросов, для которых необходима аутентификация, представлен в разделе Координаты подключения к сервису. Упрощённо процедура получения токена безопасности выглядит следующим образом.

1. Продавец (приложение) выполняет поиск клиента по номеру телефона.
2. Если клиент найден, платёжный шлюз возвращает его идентификатор (uuid).
3. Продавец делает запрос на получение кода доступа (accessCode), используя название продавца (merchantLogin) и полученный идентификатор клиента (uuid).
4. Платёжный шлюз возвращает код доступа (accessCode) и отправляет на телефон клиента SMS-сообщение с номера 900, содержащее одноразовый пароль (otp).

Время жизни кода безопасности - 60 секунд. Если за это время клиент не введёт одноразовый пароль, запрос необходимо будет повторить.

5. Клиент вводит одноразовый пароль в форму и подтверждает ввод.
6. Продавец отправляет в платёжный шлюз значение одноразового пароля (otp) и код доступа (accessCode).
7. Платёжный шлюза возвращает токен безопасности (accessToken), который следует использовать в заголовке запросов на операции со связками.

Время жизни токена безопасности (accessToken) составляет 2592000 секунду, т. е. 30 дней.

Время жизни данного параметра также можно настроить и изменить по согласованию с Банком.

Токен безопасности возвращается в виде JSON-документа. Полученный токен безопасности является симметричным секретом приложения, поэтому разработчик приложения должен предпринять меры по его защите: хранить токен в зашифрованном виде, предоставлять доступ к нему только после авторизации пользователя в приложении. Одно приложение может получить только один токен безопасности для одного пользователя. Повторная авторизация (с тем же значением идентификатора пользователя) аннулирует выданные ранее разрешения.

Ниже процедура получения токена безопасности (accessToken) представлена со ссылками на необходимые запросы.

Номер шага	Описание	Адрес обращения	Входные данные	Выходные данные для использования на следующих шагах	Ссылка на подробное описание запроса
Предусловия: отсутствуют
Шаг 1	Обращение к для проверки наличия клиента, с указанным номером телефона, в системе.	/api/clients/find	phone	client/uuid requestId status	Запрос на поиск клиента
Шаг 2	Получение кода доступа.	/api/auth/otp	merchantLogin uuid	accessCode requestId status	Запрос кода доступа
Шаг 3	Получение токена безопасности.	/api/auth/token	accessCode otp	accessToken requestId status	Запрос токена безопасности

Оплата - сбор карточных данных на стороне продавца, оплата 3DS

Номер шага	Описание	Адрес обращения	Входные данные	Выходные данные для использования на следующих шагах	Ссылка на подробное описание запроса
Предусловия: продавец аутентифицировался (см. раздел Аутентификация).
Шаг 1	Начало проведения процедуры оплаты	/api/payment/start	transactionNumber source/card/pan source/card/expiryDate source/card/cardholderName source/card/cvc amount/transactionAmount amount/transactionFee amount/currency	transactionNumber mdOrder info redirectUrl paReq requestId status	Начало платежа
Шаг 2	Отображение клиенту сообщения info.
Шаг 3	Перенаправление клиента на полученный redirectUrl (ACS банка эмитента) с указанием paReq. 1. Браузер клиента запрашивает у ACS форму аутентификации пользователя. 2. ACS отправляет в браузер клиента эту форму. 3. Клиент заполняет форму и отправляет в ACS. 4. ACS обрабатывает заполненную форму и передаёт браузеру redirect на URL возврата. Вместе с этим в URL передаются зашифрованные параметры результата аутентификации.
Шаг 4	Получение ответа от ACS с paRes.
Шаг 5	Завершение проведения процедуры оплаты.	/api/payment/finish	mdOrder transactionNumber paRes	mdOrder requestId status	Завершение платежа
Шаг 6	Продавец запрашивает результат проведения.	/api/find	transactionNumber или mdOrder	mdOrder mdOrderStatus transactionNumber transactionType transactionDate source/maskedPan source/binding amount/transactionAmount amount/transactionFee amount/currency requestId status	Запрос сведений о результате операции

Оплата - использование сохранённой ранее связки, карта 3DS

Номер шага	Описание	Адрес обращения	Входные данные	Выходные данные для использования на следующих шагах	Ссылка на подробное описание запроса
Предусловия: Продавец аутентифицировался (подробнее см. раздел Аутентификация). У клиента в профиле сохранена минимум одна карта. Клиент выбрал сохранённую карту в интерфейсе приложения.
Шаг 1	Начало проведения процедуры оплаты	/api/payment/start	`transactionNumber` `source/binding` `amount/transactionAmount` `amount/transactionFee` `amount/currency`	`transactionNumber` `mdOrder` `info` `redirectUrl` `paReq` `requestId` `status`	Начало платежа
Шаг 2	Отображение клиенту сообщения info.
Шаг 3	Перенаправление клиента на полученный redirectUrl (ACS банка эмитента) с указанием `pa_req`. 1. Браузер клиента запрашивает у ACS форму авторизации пользователя. 2. ACS отправляет в браузер клиента эту форму. 3. Клиент заполняет форму и отправляет её в ACS. 4. ACS обрабатывает заполненную форму и передаёт браузеру `redirect` на URL возврата. Вместе с этим URL передаются зашифрованные параметры результата аутентификации.
Шаг 4	Получение ответа от ACS с `paRes`.
Шаг 5	Завершение проведения процедуры оплаты.	/api/payment/finish	`mdOrder` `transactionNumber` `paRes`	`mdOrder` `requestId` `status`	Завершение платежа
Шаг 6	Продавец запрашивает результат проведения.	/api/find	`transactionNumber` или `mdOrder`	`mdOrder` `mdOrderStatus` `transactionNumber` `transactionType` `transactionDate` `source/maskedPan` `amount/transactionAmount` `amount/transactionFee` `amount/currency` `requestId` `status`	Запрос сведений о результате операции

Оплата - использование сохранённой ранее связки, карта SSL

Номер шага	Описание	Адрес обращения	Входные данные	Выходные данные для использования на следующих шагах	Ссылка на подробное описание запроса
Предусловия: Продавец аутентифицировался и получил токен безопасности (подробнее см. раздел Аутентификация). У клиента в профиле сохранена минимум одна карта.
Шаг 1	Начало проведения процедуры оплаты.	/api/payment/start	`transactionNumber` `source/binding` `amount/transactionAmount` `amount/transactionFee` `amount/currency`	`transactionNumber` `mdOrder` `requestId` `status`	Начало платежа
Шаг 2	Завершение оплаты с указанием `mdOrder` полученным на Шаге 1.	/api/payment/finish	`mdOrder` `transactionNumber`	`transactionNumber` `mdOrder` `requestId` `status`	Завершение платежа
Шаг 3	Продавец запрашивает результат проведения.	/api/find	`transactionNumber` или `mdOrder`	`mdOrder` `mdOrderStatus` `transactionNumber` `transactionType` `transactionDate` `source/maskedPan` `amount/transactionAmount` `amount/transactionFee` `amount/currency` `requestId` `status`	Запрос сведений о результате операции

Перевод - сбор карточных данных на стороне продавца, карта 3DS

Номер шага	Описание	Адрес обращения	Входные данные	Выходные данные для использования на следующих шагах	Ссылка на подробное описание запроса
Предусловия: Продавец аутентифицировался (подробнее см. раздел Аутентификация). У клиента выпущена виртуальная карта (см. раздел Создание предоплаченной виртуальной карты).
Шаг 1	Начало проведения процедуры перевода.	/api/transfer/start	`transactionNumber` `source/card/pan` `source/card/expiryDate` `source/card/cardholderName` `source/card/cvc` `amount/transactionAmount` `amount/transactionFee` `amount/currency`	`transactionNumber` `mdOrder` `info` `redirectUrl` `paReq` `requestId` `status`	Начало перевода
Шаг 2	Отображение клиенту сообщения `info`.
Шаг 3	Перенаправление клиента на полученный `redirectUrl` (ACS банка эмитента) с указанием `paReq`. 1. Браузер клиента запрашивает у ACS форму аутентификации пользователя. 2. ACS отправляет в браузер клиента эту форму. 3. Клиент заполняет форму и отправляет в ACS. 4. ACS обрабатывает заполненную форму и передаёт браузеру `redirec`t на URL возврата. Вместе с этим в URL передаются зашифрованные параметры результата аутентификации.
Шаг 4	Получение ответа от ACS с `paRes`.
Шаг 5	Завершение проведения процедуры перевода.	/api/payment/finish	`mdOrder` `transactionNumber` `paRes`	`mdOrder` `requestId` `status`	Завершение перевода
Шаг 6	Продавец запрашивает результат проведения.	/api/find	`transactionNumber` или `mdOrder`	`mdOrder` `mdOrderStatus` `transactionNumber` `transactionType` `transactionDate` `source/maskedPan` `source/binding` `amount/transactionAmount` `amount/transactionFee` `amount/currency` `requestId` `status`	Запрос сведений о результате операции

Перевод - сбор карточных данных на стороне продавца, карта SSL

Номер шага	Описание	Адрес обращения	Входные данные	Выходные данные для использования на следующих шагах	Ссылка на подробное описание запроса
Предусловия: Продавец аутентифицировался (подробнее см. раздел Аутентификация). У клиента выпущена виртуальная карта (см. раздел Создание предоплаченной виртуальной карты).
Шаг 1	Начало проведения процедуры перевода.	/api/transfer/start	`transactionNumber` `source/card/pan` `source/card/expiryDate` `source/card/cardholderName` `source/card/cvc` `amount/transactionAmount` `amount/transactionFee` `amount/currency`	`transactionNumber` `mdOrder` `requestId` `status`	Начало перевода
Шаг 2	Завершение оплаты с указанием `mdOrder` полученным на Шаге 1.	/api/transfer/finish	`mdOrder` `transactionNumber`	N/A	Завершение перевода
Шаг 3	Продавец запрашивает результат проведения.	/api/find	`transactionNumber` или `mdOrder`	`mdOrder` `mdOrderStatus` `transactionNumber` `transactionType` `transactionDate` `source/maskedPan` `amount/transactionAmount` `amount/transactionFee` `amount/currency` `requestId` `status`	Запрос сведений о результате операции

Перевод - Использованием сохранённой ранее связки, карта 3DS

Номер шага	Описание	Адрес обращения	Входные данные	Выходные данные для использования на следующих шагах	Ссылка на подробное описание запроса
Предусловия: Продавец аутентифицировался и получен токен безопасности (подробнее см. раздел Аутентификация). У клиента в профиле сохранена минимум одна карта. Выпущена виртуальная карта (подробнее см. Выпуск виртуальной карты).
Шаг 1	Начало проведения процедуры перевода.	/api/transfer/start	`transactionNumber` `source/binding` `target/binding` `amount/transactionAmount` `amount/transactionFee` `amount/currency`	`transactionNumber` `mdOrder` `info` `redirectUrl` `paReq` `requestId` `status`	Начало перевода
Шаг 2	Отображение клиенту сообщения `info`.
Шаг 3	Перенаправление клиента на полученный `redirectUrl` (ACS банка эмитента) с указанием `pa_req`. 1. Браузер клиента запрашивает у ACS форму авторизации пользователя. 2. ACS отправляет в браузер клиента эту форму. 3. Клиент заполняет форму и отправляет её в ACS. 4. ACS обрабатывает заполненную форму и передаёт браузеру `redirect` на URL возврата. Вместе с этим URL передаются зашифрованные параметры результата аутентификации.
Шаг 4	Получение ответа от ACS с `paRes`
Шаг 5	Завершение проведения процедуры перевода.	/api/transfer/finish	`mdOrder` `transactionNumber` `paRes`	`mdOrder` `requestId` `status`	Завершение перевода
Шаг 6	Продавец запрашивает результат проведения перевода.	/api/find	`transactionNumber` или `mdOrder`	`mdOrder` `mdOrderStatus` `transactionNumber` `transactionType` `transactionDate` `source/maskedPan` `target/maskedPan` `amount/transactionAmount` `amount/transactionFee` `amount/currency` `requestId` `status`	Запрос сведений о результате операции

Перевод - использование сохранённой ранее связки, карта SSL

Номер шага	Описание	Адрес обращения	Входные данные	Выходные данные для использования на следующих шагах	Ссылка на подробное описание запроса
Предусловия: Продавец аутентифицировался и получен токен безопасности (подробнее см. раздел Аутентификация). У клиента в профиле сохранена минимум одна карта. Выпущена виртуальная карта (подробнее см. Выпуск виртуальной карты).
Шаг 1	Начало проведения процедуры перевода.	/api/transfer/start	`transactionNumber` `source/binding` `target/binding` `amount/transactionAmount` `amount/transactionFee` `amount/currency`	`transactionNumber` `mdOrder` `requestId` `status`	Начало перевода
Шаг 2	Завершение перевода с указанием `mdOrder` полученным на Шаге 1.	/api/transfer/finish	`mdOrder` `transactionNumber`	N/A	Завершение перевода
Шаг 3	Продавец запрашивает результат проведения перевода.	/api/find	`transactionNumber` или `mdOrder`	`mdOrder` `mdOrderStatus` `transactionNumber` `transactionType` `transactionDate` `source/maskedPan` `target/maskedPan` `amount/transactionAmount` `amount/transactionFee` `amount/currency` `requestId` `status`	Запрос сведений о результате операции

Выпуск виртуальной карты

Номер шага	Описание	Адрес обращения	Входные данные	Выходные данные для использования на следующих шагах	Ссылка на подробное описание запроса
Предусловия: Продавец аутентифицировался и получен токен безопасности (подробнее см. раздел Аутентификация). У клиента в профиле сохранена минимум одна карта.
Шаг 1	Запрос на создание карты	/api/vcard/create	`transactionNumber`	`transactionNumber` `binding/uuid` `binding/createdDate` `binding/paymentType` `binding/paymentSystem` `card/maskedPan` `card/extendedInfo` `requestId` `status`	Выпуск виртуальной карты
Шаг 2	Начало проведения процедуры перевода на выпущенную карту. В качестве `target/binding` указывается `binding/uuid`, полученный на Шаге 1.	/api/transfer/start	`transactionNumber` `source/binding` `target/binding` `amount/transactionAmount` `amount/transactionFee` `amount/currency`	`ransactionNumber` `mdOrder` `info` `redirectUrl` `paReq` `requestId` `status`	Начало перевода
Шаг 3	Отображение клиенту сообщения `info`, полученного на Шаге 2.
Шаг 4	Перенаправление клиента на полученный `redirectUrl` (ACS банка эмитента) с указанием `paReq`. 1. Браузер клиента запрашивает у ACS форму авторизации пользователя. 2. ACS отправляет в браузер клиента эту форму. 3. Клиент заполняет форму и отправляет её в ACS. 4. ACS обрабатывает заполненную форму и передаёт браузеру `redirect` на URL возврата. Вместе с этим URL передаются зашифрованные параметры результата авторизации.
Шаг 5	Получение ответа от ACS с `paRes`
Шаг 6	Завершение проведения процедуры перевода	/api/transfer/finish	`mdOrder` `transactionNumber` `paRes`	`mdOrder` `requestId` `status`	Завершение перевода
Шаг 7	Продавец запрашивает результат проведения.	/api/find	`transactionNumber` или `mdOrder`	`mdOrder` `mdOrderStatus` `transactionNumber` `transactionType` `transactionDate` `source/maskedPan` `target/maskedPan` `amount/transactionAmount` `amount/transactionFee` `amount/currency` `requestId` `status`	Запрос сведений о результате операции
Шаг 8	Запрос на изменение имени связки. В качестве `binding/uuid` указывается `binding/uuid`, полученный на Шаге 1.	/api/change	`transactionNumber` `binding/uuid` `binding/mnemonic`	`transactionNumber` `requestId` `status`	Изменение отображаемого названия карты

Получение списка проведённых операций

Номер шага	Описание	Адрес обращения	Входные данные	Выходные данные для использования на следующих шагах	Ссылка на подробное описание запроса
Предусловия: Продавец аутентифицировался и получен токен безопасности (подробнее см. раздел Аутентификация).
Шаг 1	Запрос на изменение	/api/transactions/	`dateFrom` `dateTo` `responseType` `local`	`transactions` `mdOrder` `transactionNumber` `transactionDate` `transactionType` `transactionWay` `amount` `transactionAmount` `currency` `partner` `merchantLogin` `merchantInfo` `requestId` `status`	Получение списка проведённых операций

Получение сведений о проведённой операции

Номер шага	Описание	Адрес обращения	Входные данные	Выходные данные для использования на следующих шагах	Ссылка на подробное описание запроса
Предусловия: Продавец аутентифицировался и получен токен безопасности (подробнее см. раздел Аутентификация). Произведена операция оплаты или перевода.
Шаг 1	Запрос на изменение	/api/transactions/find	`mdOrder` `transactionNumber`	`mdOrder` `mdOrderStatus` `transactionNumber` `transactionType` `transactionWay` `transactionDate` `transactionDetails` `source` `card` `maskedPan` `binding` `target` `card` `maskedPan` `binding` `amount` `transactionAmount` `transactionFee` `currency` `requestId` `status`	Запрос сведений о результате операции

Изменение отображаемого имени связки

Номер шага	Описание	Адрес обращения	Входные данные	Выходные данные для использования на следующих шагах	Ссылка на подробное описание запроса
Предусловия: Продавец аутентифицировался и получен токен безопасности (подробнее см. раздел Аутентификация). У клиента в профиле сохранена минимум одна карта. Клиент выбрал сохранённую карту в интерфейсе приложения.
Шаг 1	Запрос на изменение.	/api/change	`transactionNumber` `binding/uuid` `binding/mnemonic`	`transactionNumber` `requestId` `status`	Изменение отображаемого имени связки

Удаление связки

Номер шага	Описание	Адрес обращения	Входные данные	Выходные данные для использования на следующих шагах	Ссылка на подробное описание запроса
Предусловия: Продавец аутентифицировался и получен токен безопасности (подробнее см. раздел Аутентификация). У клиента в профиле сохранена минимум одна карта. Клиент выбрал сохранённую карту в интерфейсе приложения.
Шаг 1	Запрос на удаление	/api/delete	`transactionNumber` `type` `uuid`	`transactionNumber` `requestId` `status`	Удаление связки

Инструменты страницы