API для магазинов

Обзор

Merchant API позволяет вашему боту или сайту принимать оплату через OroPay и платить людям с баланса магазина. Покупатель платит из своего кошелька OroPay в Telegram или переводом на адрес с любого кошелька и биржи — без нашего бота; деньги приходят на баланс владельца магазина.

• Счета — выставить счёт, отправить покупателя на нашу страницу оплаты checkoutUrl (или в бота по payUrl), узнать об оплате вебхуком или запросом. Оплата на адрес в 13 сетях и тестовый режим без настоящих денег.
• Выплаты — баланс, чеки, переводы по Telegram ID и возвраты по счетам. Выключены по умолчанию.
• Подписки — тарифы с автоматическим списанием раз в период.

Базовый адрес

https://oropay.app/api/merchant

У счетов старые пути без версии (/api/merchant/invoice, /api/merchant/invoices), у выплат, возвратов и подписок — с версией: /api/merchant/v1/…. Работают оба набора.

Формат

• Тело запроса — JSON с заголовком Content-Type: application/json. Без этого заголовка тело не будет прочитано.
• Ответ — всегда JSON. Успех: "ok": true и данные. Ошибка: "ok": false, текст в error, а у методов /v1/… ещё и стабильный code (см. Ошибки).
• Суммы — строками ("1.5"), чтобы не терять точность. Даты — ISO 8601 в UTC.
• В теле методов /v1/… поля можно писать и в snake_case (spend_id), и в camelCase (spendId).
• Неизвестный путь под /api/merchant/v1/ отвечает 404 с code: "METHOD_NOT_FOUND".

Авторизация и ключи

Приложение магазина создаётся в мини-приложении OroPay, раздел «Магазин». До 10 приложений на аккаунт. При создании показываются два значения — каждое один раз:

Как передавать ключ

Только в заголовке Authorization по схеме Bearer. В адресе или теле ключ не принимается.

Authorization: Bearer cxc_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

Пишете на Python через стандартный urllib? Укажите свой заголовок User-Agent, например User-Agent: MyShop/1.0: запросы с заголовком по умолчанию Python-urllib/… отклоняет защита сайта (ответ 403, «error code: 1010»). С requests, Node.js, curl и другими библиотеками ничего указывать не нужно.

• Ключ и секрет перевыпускаются по отдельности. Новый ключ начинает действовать сразу, старый перестаёт работать немедленно — даже для запросов выплат, которые уже в пути (приложение перечитывается под замком перед списанием).
• После перевыпуска секрета все уведомления подписываются новым секретом.
• Перевыпуск ключа и секрета, смена адреса вебхука, режима комиссии и включение приложения подтверждаются PIN-кодом (если он установлен). Владелец получает сообщение в Telegram о каждом перевыпуске и смене адреса вебхука.
• После перевыпуска ключа «Выплаты по API» выключаются: разрешение, выданное старому ключу, на новый не переходит. Включите их снова в кабинете — с PIN-кодом.
• Выключенное владельцем приложение отвечает на любой ключ как на неизвестный — 401.

Права ключа

У ключа есть набор прав. Новый ключ получает только invoices. Права меняет владелец в кабинете приложения.

Не хватает права — 403 с code: "SCOPE_REQUIRED". Ключ совсем без прав сохранить нельзя.

Формат ошибок

Методы /api/merchant/v1/… (выплаты, возвраты, подписки) возвращают стабильный машинный код — стройте логику на code, текст error предназначен человеку и может меняться. Иногда в ответе есть дополнительные поля (например, остаток лимита).

{
  "ok": false,
  "code": "DAILY_LIMIT_EXCEEDED",
  "error": "Суточный лимит выплат $500.00 исчерпан (считается по всем магазинам владельца): ушло ≈ $498.10, запрошено ≈ $5.00",
  "limitUsd": 500,
  "spentUsd": 498.1,
  "leftUsd": 1.9
}

Старые методы счетов (/api/merchant/invoice…) возвращают только текст: {"ok": false, "error": "…"}. Исключение — 403 SCOPE_REQUIRED, у него есть code. Полный список кодов — в разделе Коды ошибок.

Частота запросов

Окно — одна минута. В ответах есть стандартные заголовки RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset. Получив 429, подождите и повторите запрос с тем же ключом операции.

Идемпотентность

Сеть теряет ответы, и ваш код обязательно повторит запрос. Чтобы повтор не создал второй счёт и не заплатил дважды, у операций есть ключи. Отдельного заголовка вроде Idempotency-Key нет — ключ передаётся полем тела.

• spend_id, refund_id, plan_id — от 1 до 64 печатных ASCII-символов без пробелов. spend_id общий для чеков и переводов и уникален в пределах приложения. orderId — до 128 символов (длиннее — обрезается).
• За уникальностью следит база (уникальный индекс), а запись о выплате создаётся в той же транзакции, что и списание. Два одновременных запроса с одним ключом не спишут дважды.
• Отмена счёта, чека и подписки идемпотентна сама по себе: повторная отмена уже отменённого — не ошибка.

Библиотеки и примеры

Готовые библиотеки для Node.js и Python и примеры ботов и сайта: принять крипту в Telegram-боте или на сайте — за 10 минут. Без зависимостей, с проверкой подписи вебхука и всеми методами API.

Установка

npm i oropay        # скоро в npm

pip install oropay  # скоро в PyPI

Скачать одним файлом

Что внутри: все методы API — счета, оплата на адрес, выплаты, возвраты, подписки; verifyWebhook / verify_webhook; ошибки с полями status и code. Ответы — ровно поля API, суммы строками. Поле qr у оплаты на адрес библиотека отдаёт полным адресом.

Бот за 10 минут

1. Ключи. В боте OroPay: «Магазин» → создать приложение → ключ API (cxc_…) и секрет вебхука, оба показываются один раз. Токен бота — у @BotFather.
2. Пример. Скачайте examples.zip, откройте aiogram3-shop (Python) или grammy-shop (Node.js), скопируйте .env.example в .env и впишите токен, ключ и секрет.
3. Запуск. pip install -r requirements.txt и python bot.py — или npm install и npm start.
4. Проверка. В боте /buy → «Оплатить (тест)» → на странице оплаты «Оплатить (тест)» → «Я оплатил» → бот присылает товар. Деньги не списываются — это тестовый режим.
5. Вебхук и бой. Поднимите туннель (cloudflared tunnel --url http://localhost:8080) и впишите его адрес в PUBLIC_URL — товар будет приходить сам. Затем OROPAY_TEST_MODE=0 — и бот принимает настоящие платежи.

Суть бота — сокращённо (полная версия с кнопкой «Я оплатил» и защитой от двойной выдачи — в архиве):

import asyncio, os, re, time
from aiogram import Bot, Dispatcher
from aiogram.filters import Command
from aiogram.types import InlineKeyboardButton as Btn, InlineKeyboardMarkup
from aiohttp import web
from oropay import OroPay, verify_webhook, WebhookVerificationError

oropay = OroPay(api_key=os.environ["OROPAY_API_KEY"])
bot, dp = Bot(os.environ["BOT_TOKEN"]), Dispatcher()
TEST = os.getenv("OROPAY_TEST_MODE", "1") != "0"  # 1 — тестовые счета, без денег

@dp.message(Command("buy"))
async def buy(message):
    invoice = await asyncio.to_thread(  # клиент синхронный — в отдельном потоке
        oropay.create_invoice, "5.00", currency="USD",
        order_id=f"tg{message.chat.id}-{int(time.time() * 1000)}",  # покупатель — в orderId
        description="Гайд", test=TEST,
        callback_url=os.environ["PUBLIC_URL"] + "/oropay/webhook",
    )
    rows = [] if TEST else [[Btn(text="Оплатить в Telegram", url=invoice["payUrl"])]]
    rows.append([Btn(text="Любой кошелёк", url=invoice["checkoutUrl"])])  # тест — только здесь
    await message.answer(f"К оплате {invoice['charged']} {invoice['currency']}",
                         reply_markup=InlineKeyboardMarkup(inline_keyboard=rows))

async def webhook(request):
    try:
        event = verify_webhook(await request.read(), request.headers, os.environ["OROPAY_WEBHOOK_SECRET"])
    except WebhookVerificationError:
        return web.Response(status=401)
    inv = event.get("invoice") or {}
    if event["event"] == "invoice.paid" and (TEST or not inv["test"]):
        chat_id = int(re.match(r"tg(-?\d+)-", inv["orderId"]).group(1))
        await bot.send_message(chat_id, "Спасибо! Ваш товар: …")  # выдайте один раз — по inv["code"]
    return web.Response(text="ok")

async def main():
    app = web.Application()
    app.router.add_post("/oropay/webhook", webhook)
    runner = web.AppRunner(app)
    await runner.setup()
    await web.TCPSite(runner, "0.0.0.0", 8080).start()
    await dp.start_polling(bot)

asyncio.run(main())

import { createServer } from "node:http";
import { Bot, InlineKeyboard } from "grammy";
import { OroPay, verifyWebhook } from "oropay";

const oropay = new OroPay({ apiKey: process.env.OROPAY_API_KEY });
const bot = new Bot(process.env.BOT_TOKEN);
const TEST = process.env.OROPAY_TEST_MODE !== "0"; // 1 — тестовые счета, без денег

bot.command("buy", async (ctx) => {
  const invoice = await oropay.createInvoice({
    amount: "5.00", currency: "USD",
    orderId: `tg${ctx.chat.id}-${Date.now()}`, // покупатель — в orderId
    description: "Гайд", test: TEST,
    callbackUrl: `${process.env.PUBLIC_URL}/oropay/webhook`,
  });
  const kb = new InlineKeyboard();
  if (!TEST) kb.url("Оплатить в Telegram", invoice.payUrl).row();
  kb.url("Любой кошелёк", invoice.checkoutUrl); // тест — только здесь
  await ctx.reply(`К оплате ${invoice.charged} ${invoice.currency}`, { reply_markup: kb });
});

createServer(async (req, res) => {
  const chunks = [];
  for await (const chunk of req) chunks.push(chunk);
  let event;
  try {
    event = verifyWebhook(Buffer.concat(chunks), req.headers, process.env.OROPAY_WEBHOOK_SECRET);
  } catch {
    return res.writeHead(401).end();
  }
  const inv = event.invoice;
  if (event.event === "invoice.paid" && (TEST || !inv.test)) {
    const chatId = Number(/^tg(-?\d+)-/.exec(inv.orderId)[1]);
    await bot.api.sendMessage(chatId, "Спасибо! Ваш товар: …"); // выдайте один раз — по inv.code
  }
  res.writeHead(200).end("ok");
}).listen(8080);

bot.start();

Проверка подписи с библиотекой

verifyWebhook(rawBody, headers, secret) в Node.js и verify_webhook(raw_body, headers, secret) в Python делают всё из раздела Проверка подписи: HMAC-SHA256 от timestamp + "\n" + тело секретом вебхука, сравнение с постоянным временем, отказ при метке времени дальше 5 минут. Возвращают разобранное событие, при любой ошибке бросают WebhookVerificationError с полем reason. В PHP библиотека не нужна — хватает трёх строк.

import express from "express";
import { verifyWebhook } from "oropay";

const app = express();
// Тело — сырое: подпись считается по байтам, а не по разобранному JSON.
app.post("/oropay/webhook", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = verifyWebhook(req.body, req.headers, process.env.OROPAY_WEBHOOK_SECRET);
  } catch (e) {
    return res.sendStatus(401); // e.reason: INVALID_SIGNATURE, STALE_TIMESTAMP…
  }
  if (event.event === "invoice.paid" && !event.invoice.test) {
    // Выдать заказ event.invoice.orderId, если он ещё не выдан.
  }
  res.sendStatus(200);
});

import os
from aiohttp import web
from oropay import verify_webhook, WebhookVerificationError

SECRET = os.environ["OROPAY_WEBHOOK_SECRET"]

async def oropay_webhook(request):
    raw = await request.read()  # сырые байты; Flask — request.get_data(), Django — request.body
    try:
        event = verify_webhook(raw, request.headers, SECRET)
    except WebhookVerificationError as e:
        return web.Response(status=401)  # e.reason: INVALID_SIGNATURE, STALE_TIMESTAMP…
    if event["event"] == "invoice.paid" and not event["invoice"]["test"]:
        pass  # выдать заказ event["invoice"]["orderId"], если он ещё не выдан
    return web.Response(text="ok")

<?php
$secret = getenv('OROPAY_WEBHOOK_SECRET');   // секрет вебхука, не ключ API
$raw = file_get_contents('php://input');     // сырое тело — до json_decode
$ts  = $_SERVER['HTTP_X_CXC_TIMESTAMP'] ?? '';
$sig = strtolower($_SERVER['HTTP_X_CXC_SIGNATURE'] ?? '');

// Метка — миллисекунды Unix, не старше 5 минут; подпись — сравнение с постоянным временем.
if (!preg_match('/^\d{10,16}$/', $ts) || abs(microtime(true) * 1000 - (float) $ts) > 300000
    || !hash_equals(hash_hmac('sha256', $ts . "\n" . $raw, $secret), $sig)) {
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true);
if ($event['event'] === 'invoice.paid' && !$event['invoice']['test']) {
    // выдать заказ $event['invoice']['orderId'], если он ещё не выдан
}
echo 'ok';

Методы библиотек

Названия в Node.js — camelCase, в Python — snake_case; параметры тела библиотека сама отправляет в виде из этой документации (spendId → spend_id).

Неуспешный вызов бросает OroPayError: status — HTTP-статус (0 — нет ответа), code — код из раздела Коды ошибок (у старых методов счетов — пусто), message и data — всё тело ответа. Автоповторов нет: повторяйте запрос сами, с тем же orderId / spend_id / refund_id.

Счета

Счёт — это сумма в фиатной валюте (USD, EUR, RUB, UAH), которую покупатель оплачивает любой своей монетой.

1. Выставьте счёт — POST /api/merchant/invoice. В ответе ссылка payUrl.
2. Отправьте покупателя платить. С сайта — на checkoutUrl: наша страница с суммой, QR-кодом для телефона и кнопкой «Оплатить в Telegram»; после оплаты вернём покупателя на ваш returnUrl. Из бота или чата — кнопкой на payUrl, ссылку на бота вида https://t.me/OroPayBot?start=pay_PR…. Бот покажет счёт; покупатель выберет монету и заплатит со своего баланса OroPay. На странице оплаты можно и перевести на адрес с любого кошелька.
3. Узнайте об оплате — вебхуком invoice.paid или запросом GET /api/merchant/invoice/{code}.
4. Выдайте заказ. Деньги уже на балансе владельца магазина.

Комиссия и зачисление

Стартовое предложение: новым магазинам — 0% комиссии первые 30 дней с создания первого магазина, по промокоду (вводится в кабинете или командой /promo в боте) — 60 дней. В этот период в счетах feePercent = "0", feeAmount = "0", а charged равен amount при любом feeMode.

Комиссия — 0.75% от суммы заказа. Кто её платит, задаёт feeMode (по умолчанию — настройка приложения):

• Курс считается в момент оплаты: покупатель платит charged, пересчитанный в выбранную монету. Это количество — paidAmount в paidToken.
• На баланс магазина зачисляется та же монета: paidAmount × (charged − feeAmount) / charged, с округлением вниз до точности монеты. Дальше курс монеты — ваш: мы её не конвертируем.
• Суммы отдаются без округления до центов: комиссия с $5 — "0.0625". Минимальной комиссии нет.
• Счёт живёт 1 час (expiresAt), после этого оплатить его нельзя. С баланса OroPay недоплаты и переплаты не бывает; при оплате на адрес — см. правило 99% там.

Объект счёта

curl -X POST https://oropay.app/api/merchant/invoice \
  -H "Authorization: Bearer $OROPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":"100.00","currency":"USD","orderId":"order-1024","description":"Подписка Pro, 1 месяц","feeMode":"BUYER"}'

const res = await fetch("https://oropay.app/api/merchant/invoice", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OROPAY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "amount": "100.00",
    "currency": "USD",
    "orderId": "order-1024",
    "description": "Подписка Pro, 1 месяц",
    "feeMode": "BUYER"
  }),
});
const data = await res.json();
if (!data.ok) throw new Error(data.code ?? data.error);

import os, requests

r = requests.post(
    "https://oropay.app/api/merchant/invoice",
    headers={"Authorization": f"Bearer {os.environ['OROPAY_KEY']}"},
    json={
        "amount": "100.00",
        "currency": "USD",
        "orderId": "order-1024",
        "description": "Подписка Pro, 1 месяц",
        "feeMode": "BUYER",
    },
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "invoice": {
    "code": "PRbtixbbdeoy",
    "status": "PENDING",
    "orderId": "order-1024",
    "description": "Подписка Pro, 1 месяц",
    "amount": "100.00",
    "charged": "100.75",
    "currency": "USD",
    "feeMode": "BUYER",
    "feePercent": "0.75",
    "feeAmount": "0.75",
    "paidToken": null,
    "paidChain": null,
    "paidAmount": null,
    "createdAt": "2026-09-25T12:00:00.000Z",
    "expiresAt": "2026-09-25T13:00:00.000Z",
    "paidAt": null,
    "payUrl": "https://t.me/OroPayBot?start=pay_PRbtixbbdeoy",
    "checkoutUrl": "https://oropay.app/pay/PRbtixbbdeoy",
    "returnUrl": "https://shop.example/order/1001"
  }
}

curl https://oropay.app/api/merchant/invoice/PRbtixbbdeoy \
  -H "Authorization: Bearer $OROPAY_KEY"

const res = await fetch("https://oropay.app/api/merchant/invoice/PRbtixbbdeoy", {
  headers: {
    Authorization: `Bearer ${process.env.OROPAY_KEY}`,
  },
});
const data = await res.json();
if (!data.ok) throw new Error(data.code ?? data.error);

import os, requests

r = requests.get(
    "https://oropay.app/api/merchant/invoice/PRbtixbbdeoy",
    headers={"Authorization": f"Bearer {os.environ['OROPAY_KEY']}"},
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "invoice": {
    "code": "PRbtixbbdeoy",
    "status": "PAID",
    "orderId": "order-1024",
    "amount": "100.00",
    "charged": "100.75",
    "currency": "USD",
    "paidToken": "USDT",
    "paidChain": "TRON",
    "paidAmount": "101.2601",
    "paidAt": "2026-09-25T12:07:41.512Z",
    "payUrl": "https://t.me/OroPayBot?start=pay_PRbtixbbdeoy",
    "checkoutUrl": "https://oropay.app/pay/PRbtixbbdeoy",
    "returnUrl": "https://shop.example/order/1001"
  }
}

curl -X POST https://oropay.app/api/merchant/invoice/PRbtixbbdeoy/cancel \
  -H "Authorization: Bearer $OROPAY_KEY"

const res = await fetch("https://oropay.app/api/merchant/invoice/PRbtixbbdeoy/cancel", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OROPAY_KEY}`,
  },
});
const data = await res.json();
if (!data.ok) throw new Error(data.code ?? data.error);

import os, requests

r = requests.post(
    "https://oropay.app/api/merchant/invoice/PRbtixbbdeoy/cancel",
    headers={"Authorization": f"Bearer {os.environ['OROPAY_KEY']}"},
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "invoice": { "code": "PRbtixbbdeoy", "status": "CANCELLED", "…": "…" }
}

curl "https://oropay.app/api/merchant/invoices?status=PAID&limit=50" \
  -H "Authorization: Bearer $OROPAY_KEY"

const res = await fetch("https://oropay.app/api/merchant/invoices?status=PAID&limit=50", {
  headers: {
    Authorization: `Bearer ${process.env.OROPAY_KEY}`,
  },
});
const data = await res.json();
if (!data.ok) throw new Error(data.code ?? data.error);

import os, requests

r = requests.get(
    "https://oropay.app/api/merchant/invoices",
    headers={"Authorization": f"Bearer {os.environ['OROPAY_KEY']}"},
    params={
        "status": "PAID",
        "limit": "50",
    },
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "invoices": [
    { "code": "PRbtixbbdeoy", "status": "PAID", "…": "…" }
  ],
  "nextCursor": "PRhmfmqcwn2b"
}

Вебхуки

Мы отправляем POST с JSON на ваш адрес. Вебхук не обязателен: без адреса уведомлений просто не будет, и статус можно спрашивать запросом.

Требования к адресу

• Только https://, до 512 символов, имя хоста, а не IPv6-адрес.
• Запрещены localhost, *.local, *.internal и внутренние диапазоны (10.x, 127.x, 169.254.x, 172.16–31.x, 192.168.x, 100.64/10 и т. п.). Перед каждой отправкой имя разрешается в DNS, и если оно указывает на внутренний адрес, уведомление не отправляется.
• Перенаправления не выполняются: ответ 3xx считается неудачей.

Заголовки

Тело invoice.paid

{
  "event": "invoice.paid",
  "invoice": {
    "code": "PRbtixbbdeoy",
    "status": "PAID",
    "orderId": "order-1024",
    "description": "Подписка Pro, 1 месяц",
    "amount": "100.00",
    "charged": "100.75",
    "currency": "USD",
    "feeMode": "BUYER",
    "feePercent": "0.75",
    "feeAmount": "0.75",
    "paidToken": "USDT",
    "paidChain": "TRON",
    "paidAmount": "101.2601",
    "createdAt": "2026-09-25T12:00:00.000Z",
    "expiresAt": "2026-09-25T13:00:00.000Z",
    "paidAt": "2026-09-25T12:07:41.512Z",
    "payUrl": "https://t.me/OroPayBot?start=pay_PRbtixbbdeoy",
    "checkoutUrl": "https://oropay.app/pay/PRbtixbbdeoy",
    "returnUrl": "https://shop.example/order/1001"
  }
}

Тело invoice.refunded

{
  "event": "invoice.refunded",
  "refund": {
    "id": "311",
    "refundId": "order-1024-r1",
    "invoiceCode": "PRbtixbbdeoy",
    "asset": "USDT",
    "network": "TRON",
    "amount": "40",
    "reason": "Товар закончился",
    "createdAt": "2026-09-25T14:00:00.000Z"
  },
  "refundedTotal": "40",
  "refundable": "61.2601",
  "invoice": { "code": "PRbtixbbdeoy", "status": "PAID", "…": "…" }
}

Проверка подписи

Подпись — HMAC-SHA256 в hex от строки timestamp + "\n" + тело, где timestamp — значение x-cxc-timestamp, а тело — сырые байты запроса как пришли. Ключ HMAC — секрет вебхука приложения (не ключ API). Способ одинаковый для всех событий.

1. Прочитайте тело сырыми байтами — до разбора JSON. Разобранный и собранный заново JSON даст другую подпись.
2. Посчитайте HMAC и сравните с x-cxc-signature функцией с постоянным временем.
3. Проверьте время. Отвергайте уведомление, если x-cxc-timestamp отличается от ваших часов больше чем на 5 минут (в любую сторону). Подпись доказывает, что уведомление наше, но не что оно свежее: без проверки времени перехваченный запрос можно прислать вам повторно через день. Метка ставится заново у каждой попытки доставки, поэтому повторы после сбоя проверку проходят. Держите часы сервера синхронизированными (NTP).
4. Не сошлось — ответьте ошибкой и ничего не делайте. Сошлось — обработайте и ответьте 2xx.

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.OROPAY_WEBHOOK_SECRET;
const MAX_AGE_MS = 5 * 60 * 1000; // старше 5 минут — отвергаем

// Тело нужно сырым: подпись считается по байтам, а не по разобранному JSON.
app.post("/oropay/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const body = req.body.toString("utf8");
  const ts = req.get("x-cxc-timestamp") || "";
  // Время: метка — миллисекунды Unix. Нет метки или она дальше 5 минут — отказ.
  if (!/^\d{10,16}$/.test(ts) || Math.abs(Date.now() - Number(ts)) > MAX_AGE_MS) {
    return res.sendStatus(401);
  }
  const expected = crypto.createHmac("sha256", SECRET).update(`${ts}\n${body}`).digest();
  const got = Buffer.from(req.get("x-cxc-signature") || "", "hex");
  if (got.length !== expected.length || !crypto.timingSafeEqual(got, expected)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(body);
  if (event.event === "invoice.paid") {
    // Выдать заказ event.invoice.orderId, если он ещё не выдан.
  }
  res.sendStatus(200);
});

import hashlib, hmac, json, os, time
from flask import Flask, request

app = Flask(__name__)
SECRET = os.environ["OROPAY_WEBHOOK_SECRET"].encode()
MAX_AGE_MS = 5 * 60 * 1000  # старше 5 минут — отвергаем

@app.post("/oropay/webhook")
def oropay_webhook():
    body = request.get_data()  # сырые байты, до разбора JSON
    ts = request.headers.get("x-cxc-timestamp", "")
    # Время: метка — миллисекунды Unix. Нет метки или она дальше 5 минут — отказ.
    if not ts.isdigit() or abs(time.time() * 1000 - int(ts)) > MAX_AGE_MS:
        return "", 401
    expected = hmac.new(SECRET, ts.encode() + b"\n" + body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("x-cxc-signature", "")):
        return "", 401
    event = json.loads(body)
    if event["event"] == "invoice.paid":
        pass  # выдать заказ event["invoice"]["orderId"], если он ещё не выдан
    return "", 200

Доставка и повторы

• Первая попытка — сразу после события. Успех — только ответ 2xx за 15 секунд. Тело вашего ответа не читается.
• Неудача (другой код, таймаут, обрыв, 3xx) — повтор с нарастающей паузой: 1, 2, 4, 8, 16, 32 минуты, дальше раз в час. Всего до 12 попыток — примерно 6 часов. Проверка очереди идёт раз в минуту.
• Каждая попытка приходит с новым x-cxc-timestamp и новой подписью.
• Вебхуки о подписках и возвратах доставляются по тем же правилам.

Тестовый вебхук

В кабинете магазина (вкладка «Ключи», рядом с адресом вебхука) есть кнопка «Отправить тестовый вебхук». Мы отправляем на адрес из настроек приложения событие test — тем же путём, что и настоящие: та же подпись x-cxc-signature секретом вебхука, та же проверка адреса (внутренние адреса запрещены), без перенаправлений, таймаут 15 секунд. В кабинете сразу видно, что ответил ваш сервер: код, время, первые 500 символов ответа или ошибку.

{
  "event": "test",
  "test": true,
  "id": "test_9a8b7c6d5e4f",
  "app": { "id": "17", "name": "Кофейня на Садовой" },
  "createdAt": "2026-09-26T09:50:00.000Z",
  "message": "Тестовое событие из кабинета. Проверьте подпись и ответьте 2xx; денег за ним нет."
}

Как отличить тест от настоящего события

• В теле "event": "test" и "test": true; в заголовках — x-cxc-event: test и x-cxc-test: 1.
• Нет ни счёта, ни заголовка x-cxc-invoice: за тестом не стоит никаких денег. Ничего не выдавайте — просто проверьте подпись и ответьте 2xx.
• Тест не повторяется при неудаче и не попадает в очередь повторов.
• Не чаще 10 тестов в минуту на владельца (по всем его магазинам).

Выплаты

С баланса магазина можно платить людям: чеками (ссылка, по которой деньги забирает любой пользователь Telegram) и переводами по Telegram ID. Это пригодится, например, боту, который платит за выполненные задания. Баланс магазина — это баланс владельца, тот же, куда приходят оплаты счетов.

Как включить

1. Установите PIN-код в настройках OroPay — без него выплаты не включаются (ошибка PIN_NOT_SET).
2. В мини-приложении откройте «Магазин» → приложение → «Выплаты и возвраты».
3. Включите «Выплаты по API» и подтвердите PIN-кодом. Ключу автоматически добавится право payouts.
4. Задайте суточный лимит и лимит одной выплаты.

Выплата по API проходит, только если одновременно: у ключа есть право payouts, выключатель «Выплаты по API» включён, средства владельца не заморожены и не идёт восстановление PIN-кода. Иначе — 403 PAYOUTS_DISABLED или 403 OWNER_FROZEN. Возвраты по счетам тоже требуют включённого выключателя «Выплаты по API» (право payouts для них не нужно) — иначе 403 REFUNDS_DISABLED.

Лимиты

• Доллары считаются по курсу монеты в момент выплаты. Нет курса — 503 RATE_UNAVAILABLE, выплата не делается.
• Лимиты проверяются под замком владельца внутри той же транзакции, что и списание: одновременные запросы не проскочат лимит вместе.
• Отмена чека возвращает остаток на баланс, но суточный лимит не восстанавливает.
• Текущие значения и остаток на сегодня — в балансе.

curl https://oropay.app/api/merchant/v1/balance \
  -H "Authorization: Bearer $OROPAY_KEY"

const res = await fetch("https://oropay.app/api/merchant/v1/balance", {
  headers: {
    Authorization: `Bearer ${process.env.OROPAY_KEY}`,
  },
});
const data = await res.json();
if (!data.ok) throw new Error(data.code ?? data.error);

import os, requests

r = requests.get(
    "https://oropay.app/api/merchant/v1/balance",
    headers={"Authorization": f"Bearer {os.environ['OROPAY_KEY']}"},
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "balances": [
    { "asset": "USDT", "network": "TRON", "available": "152.4" },
    { "asset": "GRAM", "network": "TON", "available": "20" }
  ],
  "payouts": {
    "enabled": true,
    "scopes": ["invoices", "payouts"],
    "dailyLimitUsd": 500,
    "dailySpentUsd": 37.5,
    "dailyLeftUsd": 462.5,
    "maxPayoutUsd": 100
  }
}

curl -X POST https://oropay.app/api/merchant/v1/cheques \
  -H "Authorization: Bearer $OROPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spend_id":"task-8812","asset":"USDT","amount":"0.5","activations":20,"description":"За подписку на канал","expires_in_days":7}'

const res = await fetch("https://oropay.app/api/merchant/v1/cheques", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OROPAY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "spend_id": "task-8812",
    "asset": "USDT",
    "amount": "0.5",
    "activations": 20,
    "description": "За подписку на канал",
    "expires_in_days": 7
  }),
});
const data = await res.json();
if (!data.ok) throw new Error(data.code ?? data.error);

import os, requests

r = requests.post(
    "https://oropay.app/api/merchant/v1/cheques",
    headers={"Authorization": f"Bearer {os.environ['OROPAY_KEY']}"},
    json={
        "spend_id": "task-8812",
        "asset": "USDT",
        "amount": "0.5",
        "activations": 20,
        "description": "За подписку на канал",
        "expires_in_days": 7,
    },
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "repeated": false,
  "cheque": {
    "id": "48213",
    "code": "CQk2m9x0a1b3c",
    "spendId": "task-8812",
    "asset": "USDT",
    "network": "TRON",
    "amount": "0.5",
    "activations": 20,
    "claimed": 0,
    "total": "10",
    "returned": "0",
    "status": "ACTIVE",
    "link": "https://t.me/OroPayBot?start=CQk2m9x0a1b3c",
    "description": "За подписку на канал",
    "hasPassword": false,
    "newUsersOnly": false,
    "channel": null,
    "expiresAt": "2026-10-02T12:00:00.000Z",
    "createdAt": "2026-09-25T12:00:00.000Z"
  }
}

curl "https://oropay.app/api/merchant/v1/cheques?status=ACTIVE&count=20" \
  -H "Authorization: Bearer $OROPAY_KEY"

const res = await fetch("https://oropay.app/api/merchant/v1/cheques?status=ACTIVE&count=20", {
  headers: {
    Authorization: `Bearer ${process.env.OROPAY_KEY}`,
  },
});
const data = await res.json();
if (!data.ok) throw new Error(data.code ?? data.error);

import os, requests

r = requests.get(
    "https://oropay.app/api/merchant/v1/cheques",
    headers={"Authorization": f"Bearer {os.environ['OROPAY_KEY']}"},
    params={
        "status": "ACTIVE",
        "count": "20",
    },
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "cheques": [
    { "id": "48213", "code": "CQk2m9x0a1b3c", "status": "ACTIVE", "…": "…" }
  ]
}

curl -X DELETE https://oropay.app/api/merchant/v1/cheques/48213 \
  -H "Authorization: Bearer $OROPAY_KEY"

const res = await fetch("https://oropay.app/api/merchant/v1/cheques/48213", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.OROPAY_KEY}`,
  },
});
const data = await res.json();
if (!data.ok) throw new Error(data.code ?? data.error);

import os, requests

r = requests.delete(
    "https://oropay.app/api/merchant/v1/cheques/48213",
    headers={"Authorization": f"Bearer {os.environ['OROPAY_KEY']}"},
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "repeated": false,
  "cheque": { "id": "48213", "status": "CANCELLED", "claimed": 3, "returned": "8.5", "…": "…" }
}

curl -X POST https://oropay.app/api/merchant/v1/transfers \
  -H "Authorization: Bearer $OROPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spend_id":"task-8812-551","user_id":123456789,"asset":"USDT","amount":"1.25","comment":"Задание №8812"}'

const res = await fetch("https://oropay.app/api/merchant/v1/transfers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OROPAY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "spend_id": "task-8812-551",
    "user_id": 123456789,
    "asset": "USDT",
    "amount": "1.25",
    "comment": "Задание №8812"
  }),
});
const data = await res.json();
if (!data.ok) throw new Error(data.code ?? data.error);

import os, requests

r = requests.post(
    "https://oropay.app/api/merchant/v1/transfers",
    headers={"Authorization": f"Bearer {os.environ['OROPAY_KEY']}"},
    json={
        "spend_id": "task-8812-551",
        "user_id": 123456789,
        "asset": "USDT",
        "amount": "1.25",
        "comment": "Задание №8812",
    },
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "repeated": false,
  "transfer": {
    "id": "9021",
    "spendId": "task-8812-551",
    "userId": "123456789",
    "asset": "USDT",
    "network": "TRON",
    "amount": "1.25",
    "comment": "Задание №8812",
    "status": "COMPLETED",
    "createdAt": "2026-09-25T12:00:00.000Z"
  }
}

curl -X POST https://oropay.app/api/merchant/v1/invoices/PRbtixbbdeoy/refund \
  -H "Authorization: Bearer $OROPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"refund_id":"order-1024-r1","amount":"40","reason":"Товар закончился"}'

const res = await fetch("https://oropay.app/api/merchant/v1/invoices/PRbtixbbdeoy/refund", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OROPAY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "refund_id": "order-1024-r1",
    "amount": "40",
    "reason": "Товар закончился"
  }),
});
const data = await res.json();
if (!data.ok) throw new Error(data.code ?? data.error);

import os, requests

r = requests.post(
    "https://oropay.app/api/merchant/v1/invoices/PRbtixbbdeoy/refund",
    headers={"Authorization": f"Bearer {os.environ['OROPAY_KEY']}"},
    json={
        "refund_id": "order-1024-r1",
        "amount": "40",
        "reason": "Товар закончился",
    },
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "repeated": false,
  "refund": {
    "id": "311",
    "refundId": "order-1024-r1",
    "invoiceCode": "PRbtixbbdeoy",
    "asset": "USDT",
    "network": "TRON",
    "amount": "40",
    "reason": "Товар закончился",
    "createdAt": "2026-09-25T14:00:00.000Z"
  },
  "refundedTotal": "40",
  "refundable": "61.2601",
  "invoice": { "code": "PRbtixbbdeoy", "status": "PAID", "…": "…" }
}

curl https://oropay.app/api/merchant/v1/invoices/PRbtixbbdeoy/refunds \
  -H "Authorization: Bearer $OROPAY_KEY"

const res = await fetch("https://oropay.app/api/merchant/v1/invoices/PRbtixbbdeoy/refunds", {
  headers: {
    Authorization: `Bearer ${process.env.OROPAY_KEY}`,
  },
});
const data = await res.json();
if (!data.ok) throw new Error(data.code ?? data.error);

import os, requests

r = requests.get(
    "https://oropay.app/api/merchant/v1/invoices/PRbtixbbdeoy/refunds",
    headers={"Authorization": f"Bearer {os.environ['OROPAY_KEY']}"},
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "refunds": [
    { "id": "311", "refundId": "order-1024-r1", "amount": "40", "…": "…" }
  ],
  "refundedTotal": "40",
  "refundable": "61.2601",
  "invoice": { "code": "PRbtixbbdeoy", "…": "…" }
}

Подписки

Регулярные платежи. Вы заводите тариф, человек оформляет подписку по ссылке тарифа https://t.me/OroPayBot?start=SB… или в мини-приложении и подтверждает её PIN-кодом, если он у него заведён. Это его согласие на автосписания с баланса OroPay.

• Первое списание — сразу при оформлении; если в тарифе есть пробный период — в день его окончания. Пробный даётся один раз: только тому, у кого ещё не было подписок в вашем магазине.
• Дальше мы списываем цену в дату продления (nextChargeAt); за сутки до этого человек получает напоминание. Продления проверяются раз в 10 минут.
• Не хватило денег или средства заморожены — статус past_due, доступа нет, повтор через 24 часа. После третьей неудачной попытки — expired. Если приложение магазина выключено, подписка при продлении тоже становится expired.
• Отмена (человеком или вами) — дальше не списываем, доступ остаётся до конца оплаченного периода. Деньги за текущий период автоматически не возвращаются.
• Вы получаете цену за вычетом той же комиссии, что у счетов (0.75%), на баланс владельца магазина.
• За один период списание бывает ровно одно — за этим следит уникальный индекс в базе.

Условия тарифа: монета — только USDT или USDC; период — 7, 30, 90 или 365 дней; пробный — 0, 3 или 7 дней; цена — от 0.01 до 100000. Цена и период после создания не меняются: новая цена — новый тариф. До 50 тарифов на приложение, выключенные тоже считаются. Нужно право ключа subscriptions или invoices. Частота этих методов ограничена только общим счётчиком — 120 запросов в минуту с адреса.

curl -X POST https://oropay.app/api/merchant/v1/plans \
  -H "Authorization: Bearer $OROPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"VIP-канал","asset":"USDT","price":"9.99","period_days":30,"trial_days":3,"description":"Доступ в закрытый канал","plan_id":"vip-monthly"}'

const res = await fetch("https://oropay.app/api/merchant/v1/plans", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OROPAY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "VIP-канал",
    "asset": "USDT",
    "price": "9.99",
    "period_days": 30,
    "trial_days": 3,
    "description": "Доступ в закрытый канал",
    "plan_id": "vip-monthly"
  }),
});
const data = await res.json();
if (!data.ok) throw new Error(data.code ?? data.error);

import os, requests

r = requests.post(
    "https://oropay.app/api/merchant/v1/plans",
    headers={"Authorization": f"Bearer {os.environ['OROPAY_KEY']}"},
    json={
        "name": "VIP-канал",
        "asset": "USDT",
        "price": "9.99",
        "period_days": 30,
        "trial_days": 3,
        "description": "Доступ в закрытый канал",
        "plan_id": "vip-monthly",
    },
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "repeated": false,
  "plan": {
    "code": "SBk3m9x2pq7a",
    "planId": "vip-monthly",
    "name": "VIP-канал",
    "description": "Доступ в закрытый канал",
    "asset": "USDT",
    "price": "9.99",
    "periodDays": 30,
    "trialDays": 3,
    "active": true,
    "link": "https://t.me/OroPayBot?start=SBk3m9x2pq7a",
    "createdAt": "2026-09-25T12:00:00.000Z"
  }
}

curl https://oropay.app/api/merchant/v1/plans \
  -H "Authorization: Bearer $OROPAY_KEY"

const res = await fetch("https://oropay.app/api/merchant/v1/plans", {
  headers: {
    Authorization: `Bearer ${process.env.OROPAY_KEY}`,
  },
});
const data = await res.json();
if (!data.ok) throw new Error(data.code ?? data.error);

import os, requests

r = requests.get(
    "https://oropay.app/api/merchant/v1/plans",
    headers={"Authorization": f"Bearer {os.environ['OROPAY_KEY']}"},
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "plans": [
    { "code": "SBk3m9x2pq7a", "name": "VIP-канал", "active": true, "…": "…" }
  ]
}

curl -X POST https://oropay.app/api/merchant/v1/plans/SBk3m9x2pq7a/disable \
  -H "Authorization: Bearer $OROPAY_KEY"

const res = await fetch("https://oropay.app/api/merchant/v1/plans/SBk3m9x2pq7a/disable", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OROPAY_KEY}`,
  },
});
const data = await res.json();
if (!data.ok) throw new Error(data.code ?? data.error);

import os, requests

r = requests.post(
    "https://oropay.app/api/merchant/v1/plans/SBk3m9x2pq7a/disable",
    headers={"Authorization": f"Bearer {os.environ['OROPAY_KEY']}"},
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "plan": { "code": "SBk3m9x2pq7a", "active": false, "…": "…" }
}

curl "https://oropay.app/api/merchant/v1/subscriptions?user_id=123456789" \
  -H "Authorization: Bearer $OROPAY_KEY"

const res = await fetch("https://oropay.app/api/merchant/v1/subscriptions?user_id=123456789", {
  headers: {
    Authorization: `Bearer ${process.env.OROPAY_KEY}`,
  },
});
const data = await res.json();
if (!data.ok) throw new Error(data.code ?? data.error);

import os, requests

r = requests.get(
    "https://oropay.app/api/merchant/v1/subscriptions",
    headers={"Authorization": f"Bearer {os.environ['OROPAY_KEY']}"},
    params={
        "user_id": "123456789",
    },
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "active": true,
  "subscriptions": [
    {
      "id": "5021",
      "status": "active",
      "active": true,
      "userId": "123456789",
      "plan": { "code": "SBk3m9x2pq7a", "name": "VIP-канал" },
      "asset": "USDT",
      "price": "9.99",
      "periodDays": 30,
      "trialEndsAt": "2026-09-28T12:00:00.000Z",
      "currentPeriodStart": "2026-09-28T12:00:00.000Z",
      "currentPeriodEnd": "2026-10-28T12:00:00.000Z",
      "nextChargeAt": "2026-10-28T12:00:00.000Z",
      "failedAttempts": 0,
      "cancelledAt": null,
      "cancelledBy": null,
      "expiredAt": null,
      "createdAt": "2026-09-25T12:00:00.000Z"
    }
  ]
}

curl https://oropay.app/api/merchant/v1/subscriptions/5021 \
  -H "Authorization: Bearer $OROPAY_KEY"

const res = await fetch("https://oropay.app/api/merchant/v1/subscriptions/5021", {
  headers: {
    Authorization: `Bearer ${process.env.OROPAY_KEY}`,
  },
});
const data = await res.json();
if (!data.ok) throw new Error(data.code ?? data.error);

import os, requests

r = requests.get(
    "https://oropay.app/api/merchant/v1/subscriptions/5021",
    headers={"Authorization": f"Bearer {os.environ['OROPAY_KEY']}"},
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "subscription": { "id": "5021", "status": "active", "active": true, "…": "…" }
}

curl -X POST https://oropay.app/api/merchant/v1/subscriptions/5021/cancel \
  -H "Authorization: Bearer $OROPAY_KEY"

const res = await fetch("https://oropay.app/api/merchant/v1/subscriptions/5021/cancel", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OROPAY_KEY}`,
  },
});
const data = await res.json();
if (!data.ok) throw new Error(data.code ?? data.error);

import os, requests

r = requests.post(
    "https://oropay.app/api/merchant/v1/subscriptions/5021/cancel",
    headers={"Authorization": f"Bearer {os.environ['OROPAY_KEY']}"},
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "repeated": false,
  "subscription": { "id": "5021", "status": "cancelled", "active": true, "cancelledBy": "merchant", "…": "…" }
}

События подписок

Уходят на адрес вебхука из настроек приложения — нет адреса, нет и событий. Подпись и повторы — как у счетов (проверка подписи). Дополнительные заголовки: x-cxc-event, x-cxc-event-id, x-cxc-subscription. При повторе доставки событие приходит с тем же id — не продлевайте доступ дважды.

{
  "id": "evt_88213",
  "event": "subscription.renewed",
  "subscription": { "id": "5021", "status": "active", "active": true, "…": "…" },
  "charge": {
    "id": "9120",
    "asset": "USDT",
    "network": "TRON",
    "amount": "9.99",
    "fee": "0.1249",
    "merchantAmount": "9.8651",
    "periodStart": "2026-10-28T12:00:00.000Z",
    "periodEnd": "2026-11-27T12:00:00.000Z"
  },
  "createdAt": "2026-10-28T12:03:10.000Z"
}

Коды ошибок

Все значения code методов /api/merchant/v1/…. У старых методов счетов кода нет — только текст error и HTTP-статус (см. Создать счёт).

Монеты и сети

Сети (network): TRON, TON, EVM, BSC, LTC, BTC, SOL, XRP. Если монета лежит у вас только в одной сети, network можно не указывать. Для подписок — только USDT и USDC. Счета выставляются в фиате, монету выбирает покупатель.