Общая информация
Принцип работы
  • Программный интерфейс построен по принципам REST, на основе спецификации JSON-API. При отправке запросов необходимо отправлять HTTP заголовок Content-Type=application/json
  • Базовый адрес продуктивного окружения: https://api.wata.pro/api/h2h/
  • Тайм-аут на получение ответа от API: 1 минута
Главная
Словарь терминов
Аутентификация
Для доступа к API используется Bearer аутентификация на основе 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 статус код. Позаботьтесь о создании напоминания, чтобы заблаговременно перевыпустить access token в личном кабинете и заменить у себя в системе.
На стороне системы 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-нагрузки введено ограничение частоты GET-запросов к API. Для получения статуса, ориентируйтесь на гарантированные webhook уведомления со сроком доставки до 32 часов.

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

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

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

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

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

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

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

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

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

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

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

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

Для получения обновлений используйте webhooks.
Polling-запросы предназначены только для редкой проверки состояния или fallback сценария
Коды ошибок
Платежные ссылки
Создание платежной ссылки
POST /api/h2h/links/
Параметры запроса
Наиболее востребованный сценарий, более простой для интеграции мерчантом. Платежная форма находится на стороне WATA, открывается в отдельном окне или в iframe на сайте или в приложении мерчанта. На платежной форме WATA могут находиться несколько методов оплаты, например оплата картой и через СБП, в зависимости от выданного терминала. Платежная ссылка может быть одноразовой, становится недействительной после первой успешной оплаты, или многоразовой, становится недействительной по истечении заданного времени.

Не рекомендуется реализовывать логику обработки платежей по идентификатору платёжной ссылки. Платежная ссылка временный объект, она не сохраняется после истечения срока жизни (expirationDateTime). Для обработки платежа опираетесь на «orderId» — идентификатор заказа в вашей системе.

Выбор терминала, для которого создается платежная ссылка, происходит по access token в заголовке запроса
Параметры ответа
Пример запроса на создание платежной ссылки
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"
}
Параметры запроса
GET /api/h2h/links/{id}
Получение платежной ссылки по 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 /api/h2h/links/?{conditions}

По запросу происходит поиск платежных ссылок, удовлетворяющих определенным условиям. Например, сумма платежа от 1000.01 до 2999.99 в RUB дата создания с 01.02.2027 по 02.03.2027

Платежная ссылка хранится в системе WATA только до истечения срока жизни (expirationDateTime).
Параметры запроса
Поиск платежных ссылок
Параметры ответа
Пример запроса на получение платежной ссылки
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
GET /api/h2h/transactions/{transactionId}

Транзакция возникает только после того, как клиент заполнил платежную форму и нажал кнопку "Оплатить". После этого создается транзакция через обращение в шлюз.
Параметры запроса
Параметры ответа
Пример запроса получения транзакции по 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
{
  "id": "3a16a4f0-27b0-09d1-16da-ba8d5c63eae3",
  "terminalName": "string",
  "terminalPublicId": "3a16a4dd-8c83-fa4d-897a-3b334ed0ebed",
  "type": "CardCrypto",
  "kind": "Payment",
  "originalTransactionId": null,
  "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": "string",
  "payerData": {
  "payerId": "79001234567"
  }
}
GET /api/h2h/transactions/?{conditions}

Если по платежной ссылке не была произведена попытка оплаты, то транзакция не будет найдена. Несколько транзакций может быть найдено в случае, когда оплата не удалась, например, из-за нехватки денег на карте клиента, и он предпринял ещё одну попытку оплаты. Также для многоразовых платежных ссылок будет находиться весь пул транзакций.
Параметры запроса
Поиск транзакций
Параметры ответа
Пример запроса на поиск транзакции
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
Пример ответа на поиск транзакции
{
  "id": "3a16a4f0-27b0-09d1-16da-ba8d5c63eae3",
  "terminalName": "string",
  "terminalPublicId": "3a16a4dd-8c83-fa4d-897a-3b334ed0ebed",
  "type": "CardCrypto",
  "kind": "Payment",
  "originalTransactionId": null,
  "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": "string",
  "payerData": {
  "payerId": "79001234567"
  }
}
Статусы транзакций
Возврат
Создание возврата
POST /api/h2h/transactions/refunds

Метод выполняет полный или частичный возврат средств по успешной платежной транзакции. Возврат доступен только по транзакциям со статусом Paid, принадлежащим тому же терминалу, от имени которого выполняется запрос. У терминала должен быть установлен тип продукта «Эквайринг», для других типов, например «Цифровые товары + Эквайринг», возвраты отключены. Возврат возможен в случае, если у мерчанта достаточно на это средств. Уход "в минус" возможен только через техподдержку.
Параметры запроса
Параметры ответа
Пример запроса на создание возврата
POST https://api.wata.pro/api/h2h/transactions/refunds

Content-Type: application/json

Authorization: Bearer <access-token>



{
  
    "originalTransactionId": "3fa85f64-5717-4562-b3a6-756040000000",
  
    "amount": 100.01

}
Response 200
Пример ответа на создание возврата
{
  
   "transactionId": "b8c19d45-1234-4123-a5b6-890123456789",
 
   "originalTransactionId": "3fa85f64-5717-4562-b3a6-756040000000",
   "transactionStatus": "Pending",
  
   "kind": "Refund",
  
   "errorCode": null,
  
   "errorDescription": null

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

  • Предоплата (до отправки платежа в банк): позволяет проверить готовность заказа перед списанием средств.
  • Постоплата (по факту оплаты): информирует либо об успешном завершении оплаты заказа, либо об ошибке в оплате.
  • Возврат: информирует о том, что средства либо были возвращены плательщику, либо об ошибке возврата средств. 
Правила обработки и таймауты
Ваш сервер обязан вернуть HTTP статус 200 OK в ответ на каждое уведомление. Если ответ не получен или отличен от 200:
  • Предоплатный Webhook: транзакция считается несогласованной и автоматически отклоняется (запрос в банк не отправляется). Таймаут ожидания ответа от вашего сервера составляет 10 сек

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

Алгоритм проверки:
  1. Получите публичный ключ: Используйте актуальный ключ (формат PKCS1), доступный по адресу: 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();