API EN

General Information

How It Works

The API follows REST principles and is based on the JSON:API specification. All requests must include the HTTP header Content-Type: application/json.
The base URL for the production environment is: https://api.wata.pro/api/h2h/
The API response timeout is set to 1 minute/

Authentication
The API uses Bearer authentication based on a JWT token. The access token must be included in the Authorization HTTP header for every request that requires authentication.

You can get an access token in the merchant dashboard:

Receive an invitation from your account manager via email.
Follow the link in the email to set your password.
After setting the password, log in to the merchant dashboard: https://merchant.wata.pro/login
In the Terminals section, click on the card with your production terminal.
A settings panel will open on the right – use it to create tokens. You can create from 1 to 5 tokens.
Choose a name and set the token’s lifetime. The access token can be valid from 1 to 12 months.
After this period, API requests will start returning a 401 Unauthorized HTTP status code.

WATA does not store access tokens, so they cannot be recovered. A new access token must be generated. We recommend storing the token in a secure place right after generation.

Testing

Use the sandbox environment for testing: https://api-sandbox.wata.pro/api/h2h.
The sandbox merchant dashboard is available at: https://merchant-sandbox.wata.pro/login.
The process of obtaining an access token for testing is the same as the authentication process in the production environment.

You can use the following test cards:

HTTP Status Codes
If an error occurs while processing a request, the API returns an HTTP status code other than 200.

When a 400 Bad Request is returned, the response may include detailed error information.

Example: Detailed error response

Response 400

{
   "error":{
      "code":null,
      "message":"Your request is invalid!",
      "details":"The following validation errors were found – 'Amount' is required.",
      "data":{
         
      },
      "validationErrors":[
         {
            "message":"'Amount' is required.",
            "members":[
               "amount"
            ]
         }
      ]
   }
}

Error Codes

Glossary of Terms

Acquiring;A technology that enables businesses to accept online payments using bank cards, SBP, T-Pay and other methods Merchant;A client who has connected to the WATA payment system Transaction;A payment record in the system containing a unique identifier (UUID), amount, order number, description, and status Transaction UUID;A unique identifier assigned to each transaction in the system Transaction Status;The result of payment processing. It can be successful (payment completed), declined (an error code was received), or pending (no response yet from the system) Error Code;A unique identifier returned after a failed payment, explaining the reason for the failure in human-readable form Terminal;A merchant’s project that is assigned a payment gateway with specific payment methods Gateway;An H2H integration with a bank or PSP (Payment Service Provider), which includes its own rate and rolling reserve used to connect a terminal for the merchant Rate;The acquiring cost of a transaction — either a percentage of the amount or a fixed fee, depending on the gateway’s terms H2H (Host-to-Host) Integration;An API-based integration with a bank or PSP that allows merchants to accept payments with their own commission setup Commission;A markup percentage set on the terminal, charged for providing acquiring services to the merchant Turnover;The total amount of successful transactions processed within a specific time period Revenue;The difference between turnover and the acquiring fee paid by the merchant (turnover - WATA commission) Balance;The accumulated revenue before an autosettlement (automated payout) is executed Payment Form;The client-facing interface used to complete a payment with the selected payment method Payment Method;A way for customers to pay for goods or services (Cards, SBP, T-Pay and others) Autosettlements;The process of automatic payouts to merchants based on the T+N schedule, where T is the transaction date and N is the number of days until payout T+N;A payout scheme where rubles are converted to USDT and paid out depending on the conversion day Merchant Dashboard;The personal account interface where merchants manage their transactions, terminals, payment links, and payouts Webhook;A URL endpoint used to receive transaction notifications Success page;The URL to which users are redirected after a successful payment on the merchant’s system Fail page;The URL to which users are redirected after a failed payment on the merchant’s system Payment Link;A unique link generated via API or the dashboard that allows a client to complete a payment Payment API;A set of methods allowing merchants to integrate the payment form into their own systems or use their own UI Access token;A key used to integrate a merchant’s website or bot with the payment API. It is required for authentication and authorization when sending requests Secret Key;A unique key used to ensure secure interaction with the API

Payment Links

Creating a Payment Link
Use this method when the payment form is hosted on WATA’s side. The WATA payment form may include multiple payment methods, depending on the terminal issued. Each payment link is single-use and becomes invalid after the first successful payment.

Request Parameters

Response Parameters

Example: Creating a Payment Link

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"
}

Example: Response to Payment Link Creation

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 Payment Link by UUID

Request Parameters

Response Parameters

Example: Get Payment Link by UUID

GET https://api.wata.pro/api/h2h/links/3fa85f64-5717-4562-b3fc-2c963f66afa6
Content-Type: application/json
Authorization: Bearer <access-token>

Example: Response to Get Payment Link by UUID

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"
}

Search Payment Links

Request Parameters

Response Parameters

Example: Search Payment Links Request

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>

Example: Search Payment Links Response

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
}

Transactions

Get Transaction by UUID

Request Parameters

Response Parameters

Example: Get Transaction by UUID Request

GET https://api.wata.pro/api/h2h/transactions/3a16a4f0-27b0-09d1-16da-ba8d5c63eae3
Content-Type: application/json
Authorization: Bearer <access-token>

Example: Get Transaction by UUID Response

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"
}

Search Transactions

Request Parameters

Response Parameters

Example: Search Transactions Request

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>

Example: Search Transactions Response

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"
    }
  ]
}

Transaction Statuses

Webhook Notifications

Signature Verification
When registering, you can specify a URL to receive webhook notifications when a transaction is completed by the payer (both successful and failed). The webhook must be responded to with an HTTP status code 200. If the WATA system does not receive this code, it will keep retrying the notification with increasing intervals over the next 16 hours. The timeout for waiting on a response from the merchant's server is 1 minute. A webhook may be sent from one of two IP addresses — 62.84.126.140 or 51.250.106.150.

To ensure that the webhook notification was sent by the WATA system, the X-Signature header includes a digital RSA signature of the sent JSON. To verify the signature, use the SHA512 hash function and the public key (PKCS1), which can be obtained at https://api.wata.pro/api/h2h/public-key (see the section "Retrieving the Public Key for Signature Verification"). Use the raw JSON of the received webhook as the message.

Example: Signature verification in 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;
    }
}

Example: Signature Verification in 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);
    }
}

Retrieving the Public Key for Signature Verification

Response Parameters

Example: Request to Retrieve the Public Key for Signature Verification

GET https://api.wata.pro/api/h2h/public-key 
Content-Type: application/json

Example: Response to Retrieve the Public Key for Signature Verification

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 Notification Parameters

Example: Webhook Notification

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
}