Общая информация
Принцип работы
  • Программный интерфейс построен по принципам 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>
{
  "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",
  "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",
  "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",
      "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
}
Транзакции
Создание транзакции картой
Используйте этот метод для сценария, когда платежная форма находится на стороне мерчанта. На платежной форме рекомендуется подключить скрипт https://static.wata.pro/checkout.js для валидации и создания криптограммы и заполнения объекта данных о браузере плательщика.

Параметры запроса
Параметры deviceData
Параметры ответа
Параметры threeDsData
В зависимости от значений, пришедших в этом объекте, необходимо либо отправить браузер плательщика по значению url (если в параметре method пришло значение GET), либо на странице мерчанта сформировать скрытую html форму с параметрами из объекта parameters и сделать авто отправку ее на адрес url, методом method (если в параметре method пришло значение отличное от GET). В объекте parameters могут быть различные значения, рекомендуется в цикле создать элемент input для каждого из них.
Пример HTML формы
<html> 
<head> 
<title></title> 
</head> 
<body onload="setTimeout(document.forms['form'].submit(), 10000)"> 
<form name='form' action='{url}' method='{method}'> 
<input type='hidden' name='creq' value='{creq}'> 
<input type='hidden' name='threeDSSessionData' value='{threeDsSessionData}'> 
</form> 
</body> 
</html>
Пример запроса на создание транзакции картой
POST https://api.wata.pro/api/h2h/payments/card-crypto
Content-Type: application/json
Authorization: Bearer <access-token>
{
   "amount":100,
   "currency":"RUB",
   "description":"string",
   "orderId":"string",
   "deviceData":{
      "browserAcceptHeader":"text/html,application/xml",
      "browserLanguage":"ru",
      "browserJavaEnabled":true,
      "browserJavaScriptEnabled":true,
      "browserColorDepth":24,
      "browserScreenHeight":1080,
      "browserScreenWidth":1920,
      "challengeWindowWidth":1080,
      "challengeWindowHeight":1920,
      "browserTz":3,
      "browserTzName":"UTC+3",
      "browserUserAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36"
   },
   "ip":"185.215.60.77",
   "returnUrl":"https://merchant.site/result",
   "cardCrypto":"string"
   "email":"merchant@wata.pro"
}
Пример ответа на создание транзакции картой
Response 200
{
   "transactionId":"3a16a4f0-27b0-09d1-16da-ba8d5c63eae3",
   "transactionStatus": "Pending",
   "threeDsData": {
      "url": "https://acs.site",
      "method": "POST",
      "parameters": {
            "creq": "string",
            "threeDSSessionData": "string",
      }
   }
}
Создание транзакции через СБП
Используйте этот метод для сценария, когда кнопка создание платежа через СБП находится на стороне мерчанта. На форме рекомендуется подключить скрипт https://static.wata.pro/checkout.js для заполнения объекта данных о браузере плательщика.

Параметры запроса
Параметры deviceData
Параметры ответа
Пример запроса на создание транзакции через СБП
POST https://api.wata.pro/api/h2h/payments/sbp
Content-Type: application/json
Authorization: Bearer <access-token>
{
   "amount":100,
   "description":"string",
   "orderId":"string",
   "deviceData":{
      "browserAcceptHeader":"text/html,application/xml",
      "browserLanguage":"ru",
      "browserJavaEnabled":true,
      "browserJavaScriptEnabled":true,
      "browserColorDepth":24,
      "browserScreenHeight":1080,
      "browserScreenWidth":1920,
      "challengeWindowWidth":1080,
      "challengeWindowHeight":1920,
      "browserTz":3,
      "browserTzName":"UTC+3",
      "browserUserAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36"
   },
   "ip":"185.215.60.77",
   "returnUrl":"https://merchant.site/result"
}
Пример ответа на создание транзакции через СБП
Response 200
{
   "transactionId":"3a16a4f0-27b0-09d1-16da-ba8d5c63eae3",
   "transactionStatus":"Pending",
   " sbpLink ":"string"
}
Получение транзакции по 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 может прийти с одного из двух IP адресов — 62.84.126.140 или 51.250.106.150.

Для того чтобы быть уверенным, что 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",
   "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
}
Чекаут
Криптограмма
Чекаут — скрипт, который прописывается на вашем сайте, проверяет карточные данные и составляет из них криптограмму для оплаты через 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();