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

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

• Программный интерфейс построен по принципам REST, на основе спецификации JSON-API.
• При отправке запросов необходимо отправлять 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 можно получить в личном кабинете мерчанта:

1. Получите приглашение от вашего личного менеджера по email
2. Перейдите по ссылке из письма, чтобы задать пароль
3. После создания пароля авторизуйтесь в личном кабинете мерчанта (https://merchant.wata.pro/login)
4. В разделе «Терминалы» нажмите на плашку с терминалом
5. Справа откроется панель с настройками, в ней нужно создать токены. Всего можно создать от 1 до 5 токенов. Там же возможно удалить ненужные токены
6. Придумайте название и выберите время жизни токена. Время жизни access token составляет от 1 до 12 месяцев
7. После истечения этого времени запросы к 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

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

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

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

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

Links
• /links/{id} → лимит на конкретный id
• /links → общий лимит

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

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

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

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

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

---

HTTP-статусы

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

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

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

Response 400

{
   "error":{
      "code":null,
      "message":"Ваш запрос недействителен!",
      "details":"При проверке были обнаружены следующие ошибки - 'Amount' должно быть заполнено.",
      "data":{
         
      },
      "validationErrors":[
         {
            "message":"'Amount' должно быть заполнено.",
            "members":[
               "amount"
            ]
         }
      ]
   }
}

---

Коды ошибок

Код	Описание
Payment:PL_1001	Некорректная сумма платежной ссылки (сумма слишком маленькая или слишком большая)
Payment:PL_1002	Некорректная валюта платежной ссылки (создание ссылок в этой валюте запрещено)
Payment:PL_1003	Платежная ссылка недоступна либо уже оплачена
Payment:CRY_1001	Ошибка шифрования карточных данных
Payment:TRA_1001	Некорректный формат карточных данных при создании транзакции
Payment:TRA_1002	Некорректный номер карты при создании транзакции
Payment:TRA_1003	Некорректный срок действия карты при создании транзакции
Payment:TRA_1004	Некорректное значение CVV при создании транзакции
Payment:TRA_1005	Некорректная сумма при создании транзакции
Payment:TRA_1006	Некорректная валюта {currency}
Payment:TRA_1010	Держатель карты обязателен для заполнения
Payment:TRA_1011	Email плательщика обязателен для заполнения
Payment:TRA_1012	Тип платежной системы карты не поддерживается
Payment:TRA_1013	Данный способ оплаты не поддерживается (например, попытка оплаты по СБП, когда этот способ не включен у терминала)
Payment:TRA_1016	Отрицательная выручка не настроена на терминале
Payment:TRA_1019	Не получен ожидаемый ответ для вебхука предоплаты
Payment:TRA_1101	Некорректная сумма возврата
Payment:TRA_1102	Недостаточно средств на балансе терминала для возврата
Payment:TRA_1103	Пока есть незавершенные возвраты по данной транзакции, невозможно создать еще один возврат
Payment:TRA_2001	Данный тип карты не поддерживается шлюзом
Payment:TRA_2002	Недостаточно средств
Payment:TRA_2004	Подозрение на мошенничество
Payment:TRA_2006	Отказ эмитента проводить онлайн-операцию
Payment:TRA_2007	Карта потеряна
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_2019	Неверный PIN-код
Payment:TRA_2020	Ограничение на карте
Payment:TRA_2021	Транзакция не разрешена по карте
Payment:TRA_2022	Превышена сумма по карте
Payment:TRA_2023	Карта заблокирована из-за нарушений безопасности
Payment:TRA_2024	Превышен лимит операций по карте
Payment:TRA_2999	Невозможно провести платеж

---

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

• API Reference
• Создание платежной ссылки
• Получение платежной ссылки
• Поиск платежных ссылок
• Получение транзакции
• Поиск транзакций
• Создание возврата
• Получение публичного ключа