Общая информация
Принцип работы
  • Программный интерфейс построен по принципам 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/pai/h2h/
  • Тестовый ЛК: https://api.wata.pro/pai/h2h/
  • Процесс получения 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>
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 уведомления
Проверка подписи
При регистрации можно указать 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",
   "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,
}
Платежный виджет
Всплывающая и встраиваемая платежная форма оплаты на сайте без редиректа на платежную форму 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();