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

Для тестирования можно использовать карты:
HTTP статус коды ответов
В случае ошибки при обработке запроса API возвращает HTTP статус код, отличный от 200-го.
Также в случае получения 400-го кода возвращается ответ с детализацией ошибки.
Пример ответа с детализацией ошибки
Response 400
{
   "error":{
      "code":null,
      "message":"Ваш запрос недействителен!",
      "details":"При проверке были обнаружены следующие ошибки - 'Amount' должно быть заполнено.",
      "data":{
         
      },
      "validationErrors":[
         {
            "message":"'Amount' должно быть заполнено.",
            "members":[
               "amount"
            ]
         }
      ]
   }
}
Коды ошибок
Словарь терминов
Платежные ссылки
Создание платежной ссылки
Используйте этот метод для сценария, когда платежная форма находится на стороне 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>
Пример ответа на получение транзакции по UUID
Response 200
{
  "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 уведомления
Проверка подписи
При регистрации можно указать URL адрес, куда будут приходить webhook уведомления при оплате транзакции плательщиком (как успешной, так и не успешной). На webhook уведомление необходимо ответить 200ым HTTP статус кодом. В случае если система WATA не получает этот код, она будет пытаться досылать эти уведомления с увеличивающимся интервалом в течение последующих 16 часов. Таймаут на ожидание ответа от сервера мерчанта составляет 1 минуту.

Для того чтобы быть уверенным, что webhook уведомление пришло от системы WATA в заголовке X-Signature приходит цифровая RSA подпись отправленного JSON. Для проверки подписи необходимо использовать хеш-функцию SHA512 и публичный ключ (PKCS1), который можно получить по адресу https://api.wata.pro/api/h2h/public-key (смотрите раздел Получение публичного ключа для проверки подписи). В качестве сообщения необходимо использовать raw JSON полученного webhook.
Пример проверки подписи на 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-----"
}
Параметры webhook уведомления
Пример уведомления
Content-Type: application/json
X-Signature: <signature>
{
   "transactionType": "CardCrypto",
   "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,
}
Виджет
Всплывающая и встраиваемая платежная форма оплаты на сайте без редиректа на платежную форму 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();
Параметры виджета
Чекаут
Независимая форма для ввода карточных данных, которая представляется как элемент веб-сайта. Мерчант имеет возможность самостоятельно и независимо от платёжной платформы 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();