Общая информация

Принцип работы

Программный интерфейс API построен по принципам REST и использует JSON для передачи данных
При отправке запросов необходимо отправлять HTTP заголовок Content-Type=application/json
Тайм-аут на получение ответа от API: 1 минута

Для запросов с телом необходимо передавать заголовок:

Content-Type: application/json

Окружения

Production

https://api.wata.pro/api/h2h/

Sandbox

https://api-sandbox.wata.pro/api/h2h/

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

Для доступа к API используется Bearer аутентификация на основе JWT токена (далее access token). Токен необходимо передавать в каждом требующем аутентификации запросе в HTTP заголовке Authorization

Токен передается в каждом защищенном запросе в HTTP-заголовке:

Authorization: Bearer <access_token>

Access token можно получить в личном кабинете мерчанта:

Получите приглашение от вашего личного менеджера по email
Перейдите по ссылке из письма, чтобы задать пароль
После создания пароля авторизуйтесь в личном кабинете мерчанта (https://merchant.wata.pro/login)
В разделе «Терминалы» нажмите на плашку с терминалом
Справа откроется панель с настройками, в ней нужно создать токены. Всего можно создать от 1 до 5 токенов. Там же возможно удалить ненужные токены
Придумайте название и выберите время жизни токена. Время жизни access token составляет от 1 до 12 месяцев
После истечения этого времени запросы к API начнут возвращать 401 HTTP статус код. Позаботьтесь о создании напоминания, чтобы заблаговременно перевыпустить access token в личном кабинете и заменить у себя в системе.

Личный кабинет

Важно:

Храните access token в безопасном месте

WATA не хранит access token в открытом виде

Восстановить существующий token нельзя

При необходимости необходимо сгенерировать новый token

Выбирайте осознанно срок жизни access token — от 1 до 12 месяцев

После истечения срока действия API будет возвращать HTTP 401.

Допускается подключение только с согласованных адресов

Тестирование

Для тестирования используется тестовая среда:

https://api-sandbox.wata.pro/api/h2h/

Тестовый личный кабинет:

https://merchant-sandbox.wata.pro/

Тестовая среда работает отдельно от боевой. Чтобы получить доступ в тестовый личный кабинет и терминал, обратитесь к своему менеджеру. Он запросит для вас настройки песочницы и выдаст отдельный логин и пароль. Боевые учётные данные для входа в тестовую среду не подходят.
Процесс получения Access token для тестирования аналогичен процессу аутентификации в боевой среде

Карты для тестирования

Тип	Номер карты	Результат оплаты
Карта МИР без 3DS	`2200 0000 2222 2222`	Success
Карта МИР без 3DS	`2203 0000 0000 0043`	Declined
Карта МИР с 3DS	`2200 0000 0000 0004`	Success
Карта МИР с 3DS	`2202 2022 0220 2200`	Declined
Карта VISA без 3DS	`4000 0000 0000 3055`	Success
Карта VISA без 3DS	`4111 1111 1111 1111`	Declined
Карта VISA с 3DS	`4242 4242 4242 4242`	Success
Карта VISA с 3DS	`4012 8888 8888 1881`	Declined

Ограничение частоты запросов

Для стабильной работы сервиса и защиты API от polling-нагрузки введено ограничение частоты GET-запросов к API. Для получения статуса, ориентируйтесь на гарантированные webhook уведомления со сроком доставки до 32 часов.

Ограничиваются только следующие запросы

GET /api/h2h/links
GET /api/h2h/links/{id}
GET /api/h2h/v2/transactions
GET /api/h2h/transactions/{id}
GET /api/h2h/finance/balance
GET /api/h2h/subscriptions
GET /api/h2h/subscriptions/{id}

Все остальные методы (POST, PUT и т.д.) и эндпоинты — без ограничений

Размер лимита

1 GET-запрос раз в 45 секунд
Лимит считается отдельно для каждого клиента и каждого объекта

Как определяется объект

Links
• /links/{id} → лимит на конкретный id
• /links?OrderId=… → лимит на указанный OrderId
• /links → общий лимит

Transactions
• /transactions/{id} → лимит на конкретную транзакцию
• /v2/transactions?OrderId=… → лимит на указанный OrderId
• /v2/transactions → общий лимит

Subscriptions
• /subscriptions/{id} → лимит на конкретную подписку
• /subscriptions?OrderId=… → лимит на указанный OrderId
• /subscriptions → общий лимит

Finance
• /finance/balance?Date=… → лимит на указанную дату
• /finance/balance → общий лимит

Что происходит при превышении

Возвращается HTTP 429 (Too Many Requests)
В ответе указывается, через сколько секунд можно повторить запрос

Рекомендация

Для получения обновлений используйте webhooks. Polling-запросы предназначены только для редкой проверки состояния или fallback сценария

HTTP-статусы

Код	Значение	Описание
200	OK	Запрос успешно обработан
400	Некорректный запрос	Данные в запросе некорректны. Проверьте запрос, исправьте данные и повторите отправку
401	Запрос не авторизован	Не передан access-token или передан access-token с истекшим сроком действия, обновите access-token
403	Доступ запрещен	У вас нет доступа в запрашиваемый эндпоинт
404	Not Found	объект с указанным идентификатором не найден
429	Превышен лимит запросов	Попробуйте отправить запрос через указанный в ответе интервал времени
500	Ошибка сервера	Обратитесь пожалуйста в техподдержку с описанием проблемы и указанием тела запроса
503	Сервис временно не может обработать запрос, повторите попытку позднее

B случае получения 400-го кода возвращается ответ с детализацией ошибки в теле ответа.

Пример ответа с детализацией ошибки:

Response 400

{
  "error": {
    "code": "Payment:TER_3007",
    "message": "Канал платежа Subscription не доступен для данного терминала",
    "details": null,
    "data": {
      "transactionSource": "Subscription"
    },
    "validationErrors": null
  }
}

Коды ошибок

Код	Описание
Payment:PL_1001	Некорректная сумма платежной ссылки (сумма слишком маленькая или слишком большая)
Payment:PL_1002	Некорректная валюта платежной ссылки (создание ссылок в этой валюте запрещено)
Payment:PL_1004	Некорректная сумма при создании платёжной ссылки
Payment:PL_1008	Использование многоразовых платёжных ссылок запрещено для подписок
Payment:CRY_1001	Ошибка шифрования карточных данных
Payment:TRA_1001	Некорректный формат карточных данных при создании транзакции
Payment:TRA_1002	Некорректный номер карты при создании транзакции
Payment:TRA_1003	Некорректный срок действия карты при создании транзакции
Payment:TRA_1004	Некорректное значение CVC/CVV при создании транзакции
Payment:TRA_1005	Некорректная сумма при создании транзакции
Payment:TRA_1006	Некорректная валюта. Проверьте, что указанная валюта доступна на терминале
Payment:TRA_1007	Указан некорректный статус транзакции. Может возникнуть при создании возврата платежа
Payment:TRA_1010	Держатель карты обязателен для заполнения
Payment:TRA_1011	Email плательщика обязателен для заполнения
Payment:TRA_1012	Тип платежной системы карты не поддерживается
Payment:TRA_1013	Данный способ оплаты не поддерживается (например, попытка оплаты по СБП, когда этот способ не включен у терминала)
Payment:TRA_1016	Отрицательная выручка не настроена на терминале
Payment:TRA_1019	Не получен ожидаемый ответ для вебхука предоплаты
Payment:TRA_1024	Выбрана неподдерживаемая крипто-валюта
Payment:TRA_1025	Указана неподдерживаемая крипто-сеть для крипто-валюты
Payment:TRA_1101	Некорректная сумма возврата
Payment:TRA_1102	Недостаточно средств на балансе терминала для возврата
Payment:TRA_1103	Пока есть незавершенные возвраты по данной транзакции, невозможно создать еще один возврат
Payment:TRA_1105	Баланс терминала для выбранной валюты недоступен
Payment:TRA_1108	Возврат невозможен
Payment:TRA_1109	Возврат невозможен из-за активного процесса чарджбэка. После перевода диспута в финальный статус, можно повторить операцию возврата
Payment:TRA_2001	Данный тип карты не поддерживается шлюзом
Payment:TRA_2002	Недостаточно средств
Payment:TRA_2004	Подозрение на мошенничество
Payment:TRA_2005	Хеш не совпадает с присланным значением
Payment:TRA_2006	Отказ эмитента проводить онлайн-операцию
Payment:TRA_2007	Отказ эмитента по причине утраты карты
Payment:TRA_2008	Отказ банка эмитента без объяснения причин
Payment:TRA_2009	Отказ сети проводить операцию или неправильный CVV-код
Payment:TRA_2010	Карта не предназначена для онлайн-платежей
Payment:TRA_2011	Эмитент не найден
Payment:TRA_2012	Отказ по желанию держателя карты
Payment:TRA_2013	Ошибка на стороне эквайера — неверно сформирована транзакция
Payment:TRA_2014	Неизвестный эмитент карты
Payment:TRA_2015	Карта не предназначена для платежей
Payment:TRA_2017	Карта украдена
Payment:TRA_2018	Карта просрочена или неверно указан срок действия
Payment:TRA_2020	Ограничение на карте
Payment:TRA_2021	Транзакция не разрешена по карте
Payment:TRA_2022	Превышена сумма по карте
Payment:TRA_2023	Карта заблокирована из-за нарушений безопасности
Payment:TRA_2024	Превышен лимит операций по карте
Payment:TRA_2025	Выбранный способ оплаты в данный момент недоступен
Payment:TRA_2999	Невозможно провести платеж
Payment:TER_3001	Для терминала отключена возможность принимать платежи. Обратитесь к менеджеру за разъяснениями
Payment:TER_3006	Указанный канал платежа не допустим для типа продукта терминала. Например, рекурренты не доступны на терминале с типом Звезды
Payment:TER_3007	Канал платежа не доступен для данного терминала. Например, подписки не разрешены на терминале
Payment:TER_3014	Операция не разрешена для типа продукта терминала
Payment:TER_3015	Нет доступа к терминалу. Обратитесь в техподдержку
Payment:TER_3020	Канал платежа Подписки не доступен при включенной комиссии на покупателе. Если на терминале включена настройка переноса части комиссии на покупателя, невозможно создание рекуррентных платежей
Payment:MER_1004	Мерчант заблокирован. Обратитесь к вашему менеджеру
Payment:SUB_1001	Указан некорректный статус подписки
Payment:SUB_1003	Некорректная сумма подписки

Принцип работы​

Окружения​

Production​

Sandbox​

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

Тестирование​

Карты для тестирования​

Ограничение частоты запросов​

HTTP-статусы​

Коды ошибок​

Техническая документация​