Общая информация
Принцип работы
  • Программный интерфейс построен по принципам REST, на основе спецификации JSON-API. При отправке запросов необходимо отправлять HTTP заголовок Content-Type=application/json
  • Тайм-аут на получение ответа от API: 1 минута
Главная
Аутентификация
Для доступа к API используется Bearer аутентификация на основе JWT токена. JWT токен (access token) необходимо передавать в каждом требующем аутентификации запросе в HTTP заголовке Authorization
Access token можно получить в личном кабинете мерчанта:

  1. Получите приглашение от вашего личного менеджера по Email
  2. Перейдите по ссылке из письма, чтобы задать пароль
  3. После создания пароля авторизуйтесь в личном кабинете мерчанта (https://merchant.wata.pro/login)
  4. В разделе "Терминалы" нажмите на плашку с боевым терминалом
  5. Справа откроется панель с настройками, в ней нужно создать токены. Всего можно создать от 1 до 5 токенов
  6. Придумайте название и выберите время жизни токена. Время жизни access token составляет от 1 до 12 месяцев
  7. После истечения этого времени запросы к API начнут возвращать 401 HTTP статус код
На стороне системы WATA не хранится access token, поэтому его невозможно восстановить. Возможно только сгенерировать access token заново, поэтому после генерации токена рекомендуем хранить его в безопасном месте
Тестирование
  • Для тестирования используется тестовая среда: https://api-sandbox.wata.pro/api/h2h/
  • Тестовая среда работает отдельно от боевой. Чтобы получить доступ в тестовый личный кабинет и терминал, обратитесь к своему менеджеру. Он запросит для вас настройки песочницы и выдаст отдельный логин и пароль. Боевые учётные данные для входа в тестовую среду не подходят.
  • Процесс получения Access token для тестирования аналогичен процессу аутентификации в боевой среде
Для тестирования можно использовать карты:
HTTP статус коды ответов
В случае ошибки при обработке запроса API возвращает HTTP статус код, отличный от 200-го
Также в случае получения 400-го кода возвращается ответ с детализацией ошибки
Пример ответа с детализацией ошибки
Response 400
{
   "error":{
      "code":null,
      "message":"Ваш запрос недействителен!",
      "details":"При проверке были обнаружены следующие ошибки - 'Amount' должно быть заполнено.",
      "data":{
         
      },
      "validationErrors":[
         {
            "message":"'Amount' должно быть заполнено.",
            "members":[
               "amount"
            ]
         }
      ]
   }
}
Ограничение частоты запросов
Для стабильной работы сервиса и защиты API от polling-нагрузки введено ограничение частоты запросов к API.

Какие запросы ограничиваются

Только следующие запросы:

• GET /api/h2h/links
• GET /api/h2h/links/{id}
• GET /api/h2h/transactions
• GET /api/h2h/transactions/{id}

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

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

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

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

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

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

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

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

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

Для получения обновлений используйте webhooks.
Polling-запросы предназначены только для редкой проверки состояния или fallback сценария
Коды ошибок
Словарь терминов
Платежные ссылки
Создание платежной ссылки
Параметры запроса
Используйте этот метод для сценария, когда платежная форма находится на стороне WATA. На платежной форме WATA могут находиться несколько методов оплаты, например, оплата картой и через СБП, в зависимости от выданного терминала. Платежная ссылка одноразовая и становится недействительной после первой успешной оплаты
Параметры ответа
Пример запроса на создание платежной ссылки
POST https://api.wata.pro/api/h2h/links
Content-Type: application/json
Authorization: Bearer <access-token>
{
  "type": "ManyTime",
  "amount": 1188.00,
  "currency": "RUB",
  "description": "string",
  "orderId": "string",
  "successRedirectUrl": "string",
  "failRedirectUrl": "string",
  "expirationDateTime": "2024-15-03T12:09:33.390Z"
}
Response 200
Пример ответа на создание платежной ссылки
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "ManyTime",
  "amount": 1188.00,
  "currency": "RUB",
  "status": "Opened",
  "url": "string",
  "terminalName": "string",
  "terminalPublicId": "3fa85f22-2108-1749-a7gj-9c134g55hkl0",
  "creationTime": "2024-12-03T12:09:33.390Z",
  "orderId": "string",
  "description": "string",
  "successRedirectUrl": "string",
  "failRedirectUrl": "string",
  "expirationDateTime": "2024-15-03T12:09:33.390Z"
}
Параметры запроса
Получение платежной ссылки по UUID
Пример запроса на создание платежной ссылки
GET https://api.wata.pro/api/h2h/links/3fa85f64-5717-4562-b3fc-2c963f66afa6
Content-Type: application/json
Authorization: Bearer <access-token>
Response 200
Пример ответа на создание платежной ссылки
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "ManyTime",
  "amount": 1188.00,
  "currency": "RUB",
  "status": "Opened",
  "url": "string",
  "terminalName": "string",
  "terminalPublicId": "3fa85f22-2108-1749-a7gj-9c134g55hkl0",
  "creationTime": "2024-12-03T12:09:33.390Z",
  "orderId": "string",
  "description": "string",
  "successRedirectUrl": "string",
  "failRedirectUrl": "string",
  "expirationDateTime": "2024-15-03T12:09:33.390Z"
}
Параметры запроса
Поиск платежных ссылок
Параметры ответа
Пример запроса на получение платежной ссылки
GET https://api.wata.pro/api/h2h/links/?amountFrom=10&currencies=RUB&statuses=Opened&sorting=OrderId&skipCount=5&maxResultCount=5
Content-Type: application/json
Authorization: Bearer <access-token>
Response 200
Пример ответа на получение платежной ссылки
{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "ManyTime",
      "amount": 1188.00,
      "currency": "RUB",
      "status": "Opened",
      "url": "string",
      "terminalName": "string",
      "terminalPublicId": "3fa85f22-2108-1749-a7gj-9c134g55hkl0",
      "creationTime": "2024-12-06T16:47:29.106Z",
      "orderId": "string"
    }
  ],
  "totalCount": 0
}
Транзакции
Получение транзакции по UUID
Параметры запроса
Параметры ответа
Пример запроса получения транзакции по UUID
GET https://api.wata.pro/api/h2h/transactions/3a16a4f0-27b0-09d1-16da-ba8d5c63eae3
Content-Type: application/json
Authorization: Bearer <access-token>
Response 200
Пример ответа на получение транзакции по UUID
{
  "terminalName": "string",
  "terminalPublicId": "3a16a4dd-8c83-fa4d-897a-3b334ed0ebed",
  "type": "CardCrypto",
  "amount": 1188.00,
  "currency": "RUB",
  "status": "Paid",
  "errorCode": null,
  "errorDescription": null,
  "orderId": "string",
  "orderDescription": "string",
  "creationTime": "2024-12-04T17:41:33.744768Z",
  "paymentTime": "2024-12-04T17:41:44.434598Z",
  "totalCommission": 10,
  "sbpLink": null,
  "paymentLinkId": null,
  "id": "3a16a4f0-27b0-09d1-16da-ba8d5c63eae3"
}
Параметры запроса
Поиск транзакций
Параметры ответа
Пример запроса на поиск транзакции
GET https://api.wata.pro/api/h2h/transactions/?amountFrom=10&currencies=RUB&statuses=Paid&sorting=OrderId&skipCount=0&maxResultCount=5
Content-Type: application/json
Authorization: Bearer <access-token>
Response 200
Пример ответа на поиск транзакции
{
  "totalCount": 1,
  "items": [
    {
      "terminalName": "string",
      "terminalPublicId": "3a16a4dd-8c83-fa4d-897a-3b334ed0ebed",
      "type": "CardCrypto",
      "amount": 1188.00,
      "currency": "RUB",
      "status": "Paid",
      "errorCode": null,
      "errorDescription": null,
      "orderId": "string",
      "orderDescription": "string",
      "creationTime": "2024-12-05T10:32:07.739314Z",
      "paymentTime": "2024-12-05T10:32:07.739314Z ",
      "totalCommission": 10,
      "sbpLink": null,
      "paymentLinkId": null,
      "id": "3a16a4f0-27b0-09d1-16da-ba8d5c63eae3",

    }
  ]
}
Статусы транзакций
Webhook уведомления
Общая логика работы
Работа с Webhook-уведомлениями — это ключевой этап интеграции, который позволяет вашей системе оперативно реагировать на изменения статуса платежа в реальном времени.
При регистрации в системе необходимо указать URL, на который будут поступать уведомления о статусе транзакций (успешных и неуспешных). 
Типы уведомлений
Webhook-уведомления могут быть трех типов

  • Предоплата (до отправки платежа в банк): позволяет проверить готовность заказа перед списанием средств.
  • Постоплата (по факту оплаты): информирует либо об успешном завершении оплаты заказа, либо об ошибке в оплате.
  • Возврат: информирует о том, что средства либо были возвращены плательщику, либо об ошибке возврата средств. 
Правила обработки и таймауты
Ваш сервер обязан вернуть HTTP статус 200 OK в ответ на каждое уведомление. Если ответ не получен или отличен от 200:
  • Предоплатный Webhook: транзакция считается несогласованной и автоматически отклоняется (запрос в банк не отправляется). Таймаут ожидания ответа от вашего сервера составляет 10 сек
  • Постоплатный и возвратный Webhook: Система WATA будет совершать повторные попытки отправки с увеличивающимся интервалом в течение следующих 32 часов. Таймаут ожидания ответа от вашего сервера составляет 1 мин.
Параметры webhook уведомления
Безопасность и проверка подписи
Чтобы гарантировать, что уведомление отправлено системой WATA, каждое сообщение содержит заголовок X-Signature с цифровой RSA-подписью.

Алгоритм проверки:
  1. Получите публичный ключ: Используйте актуальный ключ (формат PKCS1), доступный по адресу: https://api.wata.pro/api/h2h/public-key.
  2. Подготовьте данные: В качестве сообщения используйте raw JSON (необработанное тело запроса), полученный в Webhook.
  3. Верифицируйте: Используйте хеш-функцию SHA512 для проверки соответствия подписи из заголовка X-Signature и тела сообщения.
Пример проверки подписи на PHP
<?php

class SignatureVerificationService {
    public static function verify($rawWebhookJson, $signature, $publicKey) {
        $publicSignature = openssl_get_publickey($publicKey);
        $signatureBytes = base64_decode($signature);

        $result = openssl_verify($rawWebhookJson, $signatureBytes, $publicSignature, OPENSSL_ALGO_SHA512);
        openssl_free_key($publicSignature);

        return $result === 1;
    }
}
Пример проверки подписи на Java
import java.security.PublicKey;
import java.security.Signature;
import java.util.Base64;

import static java.nio.charset.StandardCharsets.UTF_8;

public class SignatureVerificationService {
    public static boolean verify(String rawWebhookJson, String signature, PublicKey publicKey) throws Exception {
        Signature publicSignature = Signature.getInstance("SHA512withRSA");
        publicSignature.initVerify(publicKey);
        publicSignature.update(rawWebhookJson.getBytes(UTF_8));

        byte[] signatureBytes = Base64.getDecoder().decode(signature);

        return publicSignature.verify(signatureBytes);
    }
}
Параметры ответа
Получение публичного ключа для проверки подписи
Пример запроса на получение публичного ключа для проверки подписи
GET https://api.wata.pro/api/h2h/public-key 
Content-Type: application/json
Response 200
Пример ответа на получение публичного ключа для проверки подписи
{
  "value": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoL3WIP92OShyu4Y+ecbS\nZJQyU2AW7gbg8X3KqX7dkctQL54kcxvpMySR8UMjZOCSzLuly2BFHP1pNVMPF304\nuIVpRtHtwEw3k3qE259L/7xEJHSzfehHuMlfSng7Lh/HxLW93douDCwohJvAISwF\ncXlqmNo/eJfBu9kQNlclQXFMYLHOtotZbsMM/oAJJvks7bgnN5o9RXMx8SG5rfq/\naK+BZAlEC83HTpnVrv0wpjmeleSPDSiOkWIY6BBTcg1bpH162en9XasJ/xnHLBFY\nkQSjFQw8nN17CFpd5Hkb0QpABgSEVStvaeLHF5XrWi3B/x5v8sUKsEgUnOJ7LnlH\nHQIDAQAB\n-----END PUBLIC KEY-----"
}
Пример уведомления
Content-Type: application/json
X-Signature: <signature>
{
   "transactionType": "CardCrypto", 
   "kind": "Payment",
   "id": "3a1cf611-abc6-8d30-c4cd-521c9f6eeeb0",
   "transactionId": "3a16a4f0-27b0-09d1-16da-ba8d5c63eae3",
   "transactionStatus": "Paid",
   "terminalPublicId": "3b16a2f1-dead-4e5d-abff-90865d1e13b1"
   "errorCode": null,
   "errorDescription": null,
   "terminalName": "string",
   "amount": 1188.00,
   "currency": "RUB",
   "orderId": "string",
   "orderDescription": "string",
   "paymentTime": "2024-12-04T17:41:44.434598Z",
   "commission": 10,
   "email": null,
   "paymentLinkId": null,
}
Платежный виджет
Всплывающая и встраиваемая платежная форма оплаты на сайте без редиректа на платежную форму WATA адаптирована под любые браузеры и мобильные устройства и не уводит клиентов из проекта
Всплывающая платежная форма без редиректа
Преимущества
  • Встраивайте в любое место на сайте или вызывайте в модальном окне

  • Обеспечивайте возможность принимать оплату на сайте, не уводя покупателя на другие страницы

  • Управляйте языковой локализацией и цветовой темой виджета

  • Увеличивайте конверсию для покупок в вашем интерфейсе

  • Экономьте время на разработке платежной формы
Разместите данный скрипт у себя на странице
Установка 
<script src="https://static.wata.pro/widget.js"></script>
Инициализация виджета
const options = {
    publicId: '31fdcb7c-49ae-48a0-a01a-432e833089d8',
    amount: 123,
    currency: 'RUB',
};
const widget = new window.PaymentWidget(options);
Пример вызова встроенного виджета
Встраивается на любой странице вашего проекта
<div id="embedded-widget"></div>
const widget = new window.PaymentWidget(options);
const container = document.getElementById('embedded-widget');

widget.mount(container);
Пример вызова виджета в модальном окне
Вызывается в модальном окне поверх содержимого страницы
<button id="modal-trigger">Перейти к оплате</button>
const widget = new window.PaymentWidget(options);
const modalBtn = document.getElementById('modal-trigger');

modalBtn.onclick = () => widget.open();
Параметры виджета
Checkout-скрипт
Независимая форма для ввода карточных данных, которая представляется как элемент веб-сайта. Мерчант имеет возможность самостоятельно и независимо от платёжной платформы WATA обрабатывать транзакции и контролировать данные карт
  • Создавайте уникальную платежную форму в вашем дизайне на любом этапе продажи

  • Выбирайте дополнительные платежные методы H2H (СБП, Т-пей)

  • Увеличивайте конверсию для быстрых покупок в вашем интерфейсе без сторонних форм

  • Анализируйте данные о платежных операциях клиентов на вашей стороне

  • Экономьте время на разработке платежной формы

  • Защищайте данные платежных карт ваших клиентов с помощью криптограммы
Преимущества
Чекаут — скрипт, который прописывается на вашем сайте, проверяет карточные данные и составляет из них криптограмму для оплаты через API WATA. При соблюдении описанных ниже требований карточные данные к вам не попадают, но ваш сервер всё равно влияет на их безопасность.
Криптограмма
Пример криптограммы
eyJUeXBlIjoiQ2xvdWRDYXJkIiwibWV0YURhdGEiOnsiUGF5bWVudFVybCI6Imh0dHBzOi8vZGV2ZWxvcGVycy5jbG91ZHBheW1lbnRzLnJ1LyIsIlJlZmVycmVyVXJsIjoiaHR0cHM6Ly9kZXZlbG9wZXJzLmNsb3VkcGF5bWVudHMucnUvIn0sIkJyb3dzZXJJbmZvQmFzZTY0IjoiZXlKQlkyTmxjSFJJWldGa1pYSWlPaUlxTHlvaUxDSktZWFpoUlc1aFlteGxaQ0k2Wm1Gc2MyVXNJa3BoZG1GVFkzSnBjSFJGYm1GaWJHVmtJanAwY25WbExDSk1ZVzVuZFdGblpTSTZJbkoxTFZKVklpd2lRMjlzYjNKRVpYQjBhQ0k2SWpNd0lpd2lTR1ZwWjJoMElqb2lNVEExTUNJc0lsZHBaSFJvSWpvaU1UWTRNQ0lzSWxScGJXVmFiMjVsSWpvaUxUUXlNQ0lzSWxWelpYSkJaMlZ1ZENJNklrMXZlbWxzYkdFdk5TNHdJQ2hOWVdOcGJuUnZjMmc3SUVsdWRHVnNJRTFoWXlCUFV5QllJREV3WHpFMVh6Y3BJRUZ3Y0d4bFYyVmlTMmwwTHpVek55NHpOaUFvUzBoVVRVd3NJR3hwYTJVZ1IyVmphMjhwSUVOb2NtOXRaUzh4TXpNdU1DNHdMakFnVTJGbVlYSnBMelV6Tnk0ek5pSjkiLCJGb3JtYXQiOjEsIkNhcmRJbmZvIjp7IkZpcnN0U2l4RGlnaXRzIjoiNDI0MjQyIiwiTGFzdEZvdXJEaWdpdHMiOiI0MjQyIiwiRXhwRGF0ZVllYXIiOiIyNSIsIkV4cERhdGVNb250aCI6IjAxIn0sIktleVZlcnNpb24iOiIxMyIsIlZhbHVlIjoidVZnQlpndDNUZ3FRWkM3aXZaekhiZWIvUWw2RkFpWVlZVHhZakVlbm9UL3VXOUFFRE01cjYycml0RlpzOWx5ZXZPTC81WE90RnFWQ01aTFVjRXVqNDhnclRyUEFXVUg5ekN6SlppejAweEV2MU1lcmNpM3hmR1pSdXNxS2Y2bVdDRzBjUEkxUDZHVzlCNmo3RXkvWXMrNHNiQ1NvSlJIaHVXcTVERTU5Yk1kZHh1eUJqMjluM0NBRWlwQ0I1Ty9QMk1rZmh4MGd4aHZCVjNaNTVGaW15NXZqZlk4ZkZnQW9SdTZUdXIvNk1wUEw3MkhNYVBlR29iUGN0MExvZGorZm5hVVBCcEZ0V3RBVVhMb285NWtYT0hKQmxFbWRzZXA5Mkw5Y3d0QXdwRzF3MlNnbk9LT3R6dHplNFB4NkJIQXZINndKQ1VQZzIrMUpzWjRxMUl5dzhnPT0ifQ==
  • Форма должна работать по HTTPS-соединению с валидным SSL-сертификатом

  • На полях не должно быть атрибута «name» — это предотвращает попадание карточных данных на сервер при отправке формы

  • Поле для ввода номера карты на форме должно поддерживать ввод до 16 цифр

  • Криптограмма должна формироваться только оригинальным скриптом чекаут, загруженным с адресов системы

  • Криптограмму нельзя хранить после оплаты и использовать повторно
Требования
Разместите данный скрипт на платежной форме мерчанта и используйте его методы для того, чтобы провалидировать данные карты, сформировать криптограмму с карточными данными и собрать данные об устройстве плательщика
Установка
Разместите ссылку на скрипт в конце страницы
<script src="https://static.wata.pro/checkout.js"></script>
Инициализация скрипта
const сheckout = window.WataCheckout();
Пример карточных данных для шифрования
const cardData = {
    number: "4242424242424242",
    expirationMonth: 12,
    expirationYear: 28,
    cvv: '333',
    cardHolderName:'IVAN IVANOV',
};
Валидация карточных данных
const errors = сheckout.validate(cardData)
Объект с ошибками валидации в случае их наличия
type ValidatonErrors = {
    data?: string;
    number?: string;
    expirationMonth?: string;
    expirationYear?: string;
    cvv?: string;
}
Коды ошибок валидации
Шифрование карточных данных
const encryptedData = await сheckout.encrypt(cardData);
Получение данных об устройстве плательщика
const deviceData = сheckout.getDeviceData();