REST API v1 · Production Ready

Документация XevoPay API

XevoPay — высокоскоростной криптоэквайринг на базе TON (The Open Network). Сервис позволяет принимать платежи в USDT (TON Jetton), TON и GRAM с моментальным выставлением инвойсов, автоматической сверкой блокчейна и надежной защитой покупателей от фрода.

0% за входящие платежи

Прием платежей бесплатен. Фиксированная комиссия всего 1.0% берется исключительно при выводе средств.

48ч Safe-Hold защита

Повышает доверие покупателей: средства резервируются на 48 часов, защищая от скамеров и чарджбэков.

Готово для Telegram

Идеально встраивается в Telegram-боты, WebApp и каналы с оплатой в 1 клик через Tonkeeper или @wallet.

Быстрый старт за 3 шага

1

Создайте проект в личном кабинете

Зайдите в Кабинет мерчанта, нажмите «Добавить проект», укажите ваш сайт или Telegram-бота и подтвердите владение.

2

Получите API-ключ и Secret

Во вкладке «Интеграция & API» скопируйте api_key (публичный) и api_secret (для подписи вебхуков).

3

Отправьте запрос на создание инвойса

Получите ссылку payment_url и перенаправьте клиента на оплату в адаптивный чекаут.

Базовый URL API: https://dashboard.xevopay.ru/api/v1

Аутентификация запросов

Для взаимодействия с API вы можете использовать заголовок X-API-Key с ключом вашего проекта, либо Authorization: Bearer <token> при авторизации через учетную запись.

Пример заголовков HTTP:

Content-Type: application/json
X-API-Key: pk_live_9b4e72c810f3a9e10d2c
# Или заголовок Bearer JWT токена
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI...

Создание счета на оплату

POST /api/v1/invoices

Генерирует новый инвойс и уникальный блокчейн-адрес в сети TON. Возвращает прямую ссылку на стилизованный чекаут pay.xevopay.ru/checkout?id=....

curl -X POST https://dashboard.xevopay.ru/api/v1/invoices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_YOUR_KEY" \
  -d '{
    "projectId": "proj_809244",
    "amount": 25.00,
    "currency": "USDT",
    "orderId": "order_77491",
    "description": "Подписка Telegram Premium 1 мес",
    "successUrl": "https://myshop.com/success",
    "cancelUrl": "https://myshop.com/cancel"
  }'

import requests

payload = {
    "projectId": "proj_809244",
    "amount": 25.00,
    "currency": "USDT",
    "orderId": "order_77491",
    "description": "Подписка Telegram Premium 1 мес",
    "successUrl": "https://myshop.com/success",
    "cancelUrl": "https://myshop.com/cancel"
}

headers = {
    "Content-Type": "application/json",
    "X-API-Key": "pk_live_YOUR_KEY"
}

response = requests.post("https://dashboard.xevopay.ru/api/v1/invoices", json=payload, headers=headers)
data = response.json()

if data.get("success"):
    print("Ссылка на чекаут:", data["invoice"]["payment_url"])
else:
    print("Ошибка:", data.get("error"))

const axios = require('axios');

async function createInvoice() {
  const { data } = await axios.post('https://dashboard.xevopay.ru/api/v1/invoices', {
    projectId: 'proj_809244',
    amount: 25.00,
    currency: 'USDT',
    orderId: 'order_77491',
    description: 'Подписка Telegram Premium 1 мес',
    successUrl: 'https://myshop.com/success',
    cancelUrl: 'https://myshop.com/cancel'
  }, {
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'pk_live_YOUR_KEY'
    }
  });

  if (data.success) {
    console.log('Оплата по ссылке:', data.invoice.payment_url);
    return data.invoice;
  }
}

createInvoice();

<?php
$payload = json_encode([
    'projectId'   => 'proj_809244',
    'amount'      => 25.00,
    'currency'    => 'USDT',
    'orderId'     => 'order_77491',
    'description' => 'Подписка Telegram Premium 1 мес',
    'successUrl'  => 'https://myshop.com/success',
    'cancelUrl'   => 'https://myshop.com/cancel'
]);

$ch = curl_init('https://dashboard.xevopay.ru/api/v1/invoices');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: pk_live_YOUR_KEY'
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
if (!empty($data['success'])) {
    header('Location: ' . $data['invoice']['payment_url']);
    exit;
}
?>

Параметры тела запроса:

Поле	Тип	Обязательное	Описание
projectId	string	Да	ID подтвержденного проекта мерчанта
amount	number	Да	Сумма платежа (мин. 0.01)
currency	string	Опционально	Валюта: `USDT` (по умолчанию), `TON` или `GRAM`
orderId	string	Опционально	Внутренний ID заказа в вашей базе данных для сверки
description	string	Опционально	Название товара или услуги, отображаемое на чекауте
successUrl	string	Опционально	URL редиректа после успешной оплаты

Пример успешного ответа (201 Created):

{
  "success": true,
  "invoice": {
    "id": "inv_948194",
    "project_id": "proj_809244",
    "amount": "25.00000000",
    "currency": "USDT",
    "order_id": "order_77491",
    "description": "Подписка Telegram Premium 1 мес",
    "wallet_address": "UQDKUyT37YQ9Yv-Fe2E1q9J7_3us9Mt_-aG7xSEl6EMk5saT",
    "status": "pending",
    "payment_url": "https://pay.xevopay.ru/checkout?id=inv_948194",
    "expires_at": "2026-09-22T15:25:00.000Z",
    "created_at": "2026-09-22T14:25:00.000Z"
  }
}

Проверка статуса счета

GET /api/v1/invoices/:id

Позволяет получить актуальный статус счета в реальном времени. Статус обновляется автоматически фоновым сканером TON при подтверждении транзакции.

Пример запроса:

curl -X GET https://dashboard.xevopay.ru/api/v1/invoices/inv_948194 \
  -H "X-API-Key: pk_live_YOUR_KEY"

pending Ожидает оплаты покупателем

paid Оплачен в блокчейне TON, средства в холде

expired Время оплаты (1 час) истекло

disputed Открыт спор покупателем в течение 48ч

Вебхуки (Instant Webhooks)

Как только транзакция поступает в блокчейн TON и подтверждается сетью, XevoPay моментально отправляет HTTP POST запрос на указанный вами webhook_url.

Безопасность: Всегда проверяйте подпись X-Xevo-Signature. Она гарантирует, что вебхук отправлен именно сервером XevoPay, а не злоумышленником.

Пример проверки HMAC-SHA256 подписи:

const crypto = require('crypto');
const express = require('express');
const app = express();

app.post('/webhook/xevopay', express.raw({ type: 'application/json' }), (req, res) => {
  const secret = 'sec_live_YOUR_SECRET';
  const receivedSig = req.headers['x-xevo-signature'];
  const rawBody = req.body.toString('utf8');

  // Вычисляем ожидаемый HMAC-SHA256
  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  if (receivedSig !== expectedSig) {
    console.error('Неверная подпись вебхука!');
    return res.status(400).send('Invalid signature');
  }

  const payload = JSON.parse(rawBody);
  console.log('Событие XevoPay:', payload.event);

  if (payload.event === 'invoice.paid') {
    const invoice = payload.invoice;
    console.log(`Заказ ${invoice.order_id} успешно оплачен на сумму ${invoice.amount} ${invoice.currency}`);
    // Здесь активируйте подписку или выдайте цифровой товар клиенту
  }

  res.status(200).send('OK');
});

app.listen(8080);

import hmac
import hashlib
from fastapi import FastAPI, Request, HTTPException, Header

app = FastAPI()
API_SECRET = "sec_live_YOUR_SECRET"

@app.post("/webhook/xevopay")
async def handle_webhook(request: Request, x_xevo_signature: str = Header(None)):
    raw_body = await request.body()
    
    # Проверка подписи HMAC-SHA256
    expected_sig = hmac.new(
        API_SECRET.encode('utf-8'),
        raw_body,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(x_xevo_signature or "", expected_sig):
        raise HTTPException(status_code=400, detail="Invalid signature")

    payload = await request.json()
    if payload.get("event") == "invoice.paid":
        inv = payload.get("invoice", {})
        print(f"Заказ {inv.get('order_id')} успешно оплачен: {inv.get('amount')} {inv.get('currency')}")
        # Выдаем товар или начисляем баланс пользователю

    return {"status": "ok"}

<?php
$secret = 'sec_live_YOUR_SECRET';
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_XEVO_SIGNATURE'] ?? '';

$expected = hash_hmac('sha256', $rawBody, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(400);
    exit('Invalid signature');
}

$payload = json_decode($rawBody, true);
if ($payload['event'] === 'invoice.paid') {
    $inv = $payload['invoice'];
    // Заказ $inv['order_id'] оплачен
    // Обновите статус в вашей базе данных MySQL/Postgres
}

http_response_code(200);
echo 'OK';
?>

Интеграция в Telegram-ботов

Python aiogram 3.x

XevoPay спроектирован для бесшовной работы с Telegram. Вы можете отправлять инвойс прямо в чат кнопкой InlineKeyboardButton(url=payment_url) — при нажатии у пользователя открывается нативный чекаут с автоматическим переходом в Tonkeeper или @wallet.

bot.py · Пример отправки кнопки оплаты

import aiohttp
from aiogram import Bot, Dispatcher, types
from aiogram.filters import Command
from aiogram.types import InlineKeyboardMarkup, InlineKeyboardButton

BOT_TOKEN = "YOUR_TELEGRAM_BOT_TOKEN"
XEVOPAY_API_KEY = "pk_live_YOUR_KEY"
PROJECT_ID = "proj_809244"

bot = Bot(token=BOT_TOKEN)
dp = Dispatcher()

async def create_xevo_invoice(amount: float, order_id: str, desc: str) -> str:
    url = "https://dashboard.xevopay.ru/api/v1/invoices"
    payload = {
        "projectId": PROJECT_ID,
        "amount": amount,
        "currency": "USDT",
        "orderId": order_id,
        "description": desc
    }
    headers = {"X-API-Key": XEVOPAY_API_KEY}
    
    async with aiohttp.ClientSession() as session:
        async with session.post(url, json=payload, headers=headers) as resp:
            data = await resp.json()
            return data["invoice"]["payment_url"]

@dp.message(Command("buy"))
async def cmd_buy(message: types.Message):
    # Создаем инвойс на 10.00 USDT
    payment_url = await create_xevo_invoice(
        amount=10.00,
        order_id=f"user_{message.from_user.id}_plan",
        desc="Доступ в закрытый VIP канал"
    )

    keyboard = InlineKeyboardMarkup(inline_keyboard=[
        [InlineKeyboardButton(text="💳 Оплатить 10 USDT (TON)", url=payment_url)]
    ])

    await message.answer(
        "✨ Оформление подписки\n\n"
        "Сумма к оплате: 10.00 USDT в сети TON\n"
        "Нажмите кнопку ниже для безопасной оплаты:",
        reply_markup=keyboard,
        parse_mode="HTML"
    )

if __name__ == "__main__":
    dp.run_polling(bot)

48-часовой Safe-Hold и споры

Для защиты экосистемы от мошенников платформа XevoPay использует механизм временного удержания:

Каждый поступивший платеж находится на балансе в статусе Холда (48 часов).
По истечении 48 часов средства автоматически переходят в статус Доступно к выводу.
Если покупатель не получил товар, он может подать апелляцию в чекауте. При открытии спора средства временно замораживаются до разрешения администратором XevoPay.
При разрешении спора в пользу мерчанта инвойс автоматически размораживается. При возврате покупателю средства возвращаются на кошелек плательщика.

Коды ответов и ошибок API

HTTP Код	Значение	Возможная причина и решение
200 OK / 201 Created	Успешный запрос	Запрос выполнен корректно, инвойс сгенерирован.
400 Bad Request	Ошибка валидации	Не передан обязательный параметр или сумма меньше 0.01.
401 Unauthorized	Не авторизован	Отсутствует или недействителен заголовок X-API-Key или Bearer токен.
403 Forbidden	Доступ запрещен	Проект еще не подтвержден или заблокирован модератором.
404 Not Found	Объект не найден	Указанный ID инвойса или проекта не существует в базе.
500 Server Error	Внутренняя ошибка	Сбой блокчейн-ноды TON. Обратитесь в техподдержку @xevopay_support.