Merchant API

Overview

The Merchant API allows your bot or website to accept payments via OroPay and pay people from your shop's balance. The customer pays from their OroPay wallet in Telegram or by a transfer to an address from any wallet or exchange — without our bot; the money is credited to the shop owner's balance.

• Invoices — create an invoice, send the customer to our payment page checkoutUrl (or to the bot via payUrl), and get notified of payment via a webhook or a request. Payment to an address in 13 networks and a test mode without real money.
• Payouts — balance, cheques, transfers by Telegram ID, and refunds by invoice. Disabled by default.
• Subscriptions — plans with automatic recurring payments.

Base URL

https://oropay.app/api/merchant

Invoices use old, unversioned paths (/api/merchant/invoice, /api/merchant/invoices), while payouts, refunds, and subscriptions use versioned paths: /api/merchant/v1/…. Both sets of endpoints are functional.

Format

• The request body is JSON with the Content-Type: application/json header. The body will not be read without this header.
• The response is always JSON. Success: "ok": true and data. Error: "ok": false, text in error, and for /v1/… methods, a stable code (see Errors).
• Amounts are strings ("1.5") to avoid precision loss. Dates are in ISO 8601 format in UTC.
• In the body of /v1/… methods, fields can be written in either snake_case (spend_id) or camelCase (spendId).
• An unknown path under /api/merchant/v1/ returns a 404 with code: "METHOD_NOT_FOUND".

Authorization and keys

A shop application is created in the OroPay mini-app, under the "Shop" section. You can have up to 10 applications per account. When you create an application, two values are shown, each only once:

How to pass the key

Only in the Authorization header using the Bearer scheme. The key is not accepted in the URL or body.

Authorization: Bearer cxc_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

Using Python with the standard urllib? Set a custom User-Agent header, for example User-Agent: MyShop/1.0. Requests with the default Python-urllib/… header are blocked by our site protection (403 response, "error code: 1010"). With requests, Node.js, curl, and other libraries, you don't need to specify anything.

• The key and secret can be reissued separately. A new key becomes active immediately, and the old one stops working instantly— even for payout requests already in transit (the application is re-read under a lock before debiting).
• After reissuing the secret, all notifications will be signed with the new secret.
• Reissuing the key and secret, changing the webhook URL, commission mode, and enabling the application must be confirmed with a PIN code (if set). The owner receives a Telegram message for each reissue and webhook URL change.
• After reissuing a key, "API Payouts" are disabled: the permission granted to the old key is not transferred to the new one. You must re-enable it in your dashboard—with a PIN code.
• An application disabled by the owner will respond to any key as if it were unknown—with a 401 error.

Key scopes

Each key has a set of scopes. A new key is granted only the invoices scope. The owner can change scopes in the application dashboard.

Missing a scope results in a 403 error with code: "SCOPE_REQUIRED". A key cannot be saved with no scopes at all.

Error format

The /api/merchant/v1/… methods (payouts, refunds, subscriptions) return a stable machine-readable code — build your logic on the code field; the error text is for human readers and may change. Sometimes the response contains additional fields (e.g., the remaining limit).

{
  "ok": false,
  "code": "DAILY_LIMIT_EXCEEDED",
  "error": "Daily payout limit of $500.00 has been reached (calculated across all of the owner's shops): ≈ $498.10 spent, ≈ $5.00 requested",
  "limitUsd": 500,
  "spentUsd": 498.1,
  "leftUsd": 1.9
}

Older invoice methods (/api/merchant/invoice…) return only text: {"ok": false, "error": "…"}. The exception is 403 SCOPE_REQUIRED, which does have a code. For a full list of codes, see the Error codes section.

Rate limits

The window is one minute. Responses include the standard RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. If you receive a 429 error, wait and retry the request with the same operation key.

Idempotency

Network connections can drop responses, and your code will inevitably retry requests. To prevent a retry from creating a second invoice or paying twice, operations use keys. There is no separate header like Idempotency-Key—the key is passed as a body field.

• spend_id, refund_id, plan_id: 1 to 64 printable ASCII characters without spaces. spend_id is shared between cheques and transfers and is unique within an application. orderId: up to 128 characters (longer strings are truncated).
• Uniqueness is enforced by the database (unique index), and the payout record is created in the same transaction as the debit. Two concurrent requests with the same key will not result in a double charge.
• Canceling an invoice, cheque, or subscription is idempotent by nature: re-canceling an already canceled item is not an error.

Libraries and examples

Ready-made libraries for Node.js and Python plus bot and website examples: accept crypto in a Telegram bot or on a website in 10 minutes. No dependencies, webhook signature verification and every API method included.

Install

npm i oropay        # coming soon to npm

pip install oropay  # coming soon to PyPI

Single-file download

What's inside: every API method — invoices, pay to an address, payouts, refunds, subscriptions; verifyWebhook / verify_webhook; errors with status and code. Responses are the API fields as is, amounts as strings. The qr field of an address payment is returned as an absolute URL.

Bot in 10 minutes

1. Keys. In the OroPay bot: "Shop" → create an app → API key (cxc_…) and webhook secret, each shown once. Get a bot token from @BotFather.
2. Example. Download examples.zip, open aiogram3-shop (Python) or grammy-shop (Node.js), copy .env.example to .env and fill in the token, key and secret.
3. Run. pip install -r requirements.txt and python bot.py — or npm install and npm start.
4. Try it. In the bot: /buy → "Pay (test)" → "Pay (test)" on the checkout page → "I've paid" → the bot sends the item. No money moves — this is test mode.
5. Webhook and going live. Start a tunnel (cloudflared tunnel --url http://localhost:8080) and put its URL into PUBLIC_URL — items are delivered automatically. Then set OROPAY_TEST_MODE=0 to accept real payments.

The core of the bot, condensed (the full version with an "I've paid" button and double-delivery protection is in the archive):

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 — test invoices, no money

@dp.message(Command("buy"))
async def buy(message):
    invoice = await asyncio.to_thread(  # sync client — run it in a thread
        oropay.create_invoice, "5.00", currency="USD",
        order_id=f"tg{message.chat.id}-{int(time.time() * 1000)}",  # the buyer goes into orderId
        description="Guide", test=TEST,
        callback_url=os.environ["PUBLIC_URL"] + "/oropay/webhook",
    )
    rows = [] if TEST else [[Btn(text="Pay in Telegram", url=invoice["payUrl"])]]
    rows.append([Btn(text="Any wallet", url=invoice["checkoutUrl"])])  # test invoices — only here
    await message.answer(f"To pay: {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, "Thank you! Your item: …")  # deliver once — by 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 — test invoices, no money

bot.command("buy", async (ctx) => {
  const invoice = await oropay.createInvoice({
    amount: "5.00", currency: "USD",
    orderId: `tg${ctx.chat.id}-${Date.now()}`, // the buyer goes into orderId
    description: "Guide", test: TEST,
    callbackUrl: `${process.env.PUBLIC_URL}/oropay/webhook`,
  });
  const kb = new InlineKeyboard();
  if (!TEST) kb.url("Pay in Telegram", invoice.payUrl).row();
  kb.url("Any wallet", invoice.checkoutUrl); // test invoices — only here
  await ctx.reply(`To pay: ${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, "Thank you! Your item: …"); // deliver once — by inv.code
  }
  res.writeHead(200).end("ok");
}).listen(8080);

bot.start();

Signature verification with the library

verifyWebhook(rawBody, headers, secret) in Node.js and verify_webhook(raw_body, headers, secret) in Python do everything from Signature verification: HMAC-SHA256 of timestamp + "\n" + body with the webhook secret, constant-time compare, rejection of timestamps more than 5 minutes away. They return the parsed event and throw WebhookVerificationError with a reason on any failure. PHP needs no library — three lines are enough.

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

const app = express();
// Keep the body raw: the signature covers the bytes, not parsed 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) {
    // Deliver order event.invoice.orderId unless already delivered.
  }
  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()  # raw bytes; 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  # deliver order event["invoice"]["orderId"] unless already delivered
    return web.Response(text="ok")

<?php
$secret = getenv('OROPAY_WEBHOOK_SECRET');   // webhook secret, not the API key
$raw = file_get_contents('php://input');     // raw body — before json_decode
$ts  = $_SERVER['HTTP_X_CXC_TIMESTAMP'] ?? '';
$sig = strtolower($_SERVER['HTTP_X_CXC_SIGNATURE'] ?? '');

// Timestamp is Unix ms, at most 5 minutes off; constant-time signature compare.
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']) {
    // deliver order $event['invoice']['orderId'] unless already delivered
}
echo 'ok';

Library methods

Node.js names are camelCase, Python names are snake_case; the library sends body parameters in the form used by this documentation (spendId → spend_id).

A failed call throws OroPayError: status — HTTP status (0 — no response), code — a code from Error codes (empty for the old invoice methods), message, and data — the full response body. There are no automatic retries: retry yourself with the same orderId / spend_id / refund_id.

Invoices

An invoice is an amount in a fiat currency (USD, EUR, RUB, UAH) that the buyer pays with any of their coins.

1. Create an invoice — POST /api/merchant/invoice. The response contains a payUrl link.
2. Send the buyer to pay. From a website — to checkoutUrl: our page with the amount, a QR code for the phone and a “Pay in Telegram” button; after payment we send the buyer back to your returnUrl. From a bot or chat — a button to payUrl, a link to the bot like https://t.me/OroPayBot?start=pay_PR…. The bot will show the invoice; the buyer will choose a coin and pay from their OroPay balance. On the payment page they can also transfer to an address from any wallet.
3. Get notified of the payment — via the invoice.paid webhook or a GET /api/merchant/invoice/{code} request.
4. Fulfill the order. The money is already in the shop owner's balance.

Fees and crediting

Welcome offer: new shops pay 0% fee for the first 30 days after creating their first shop, or 60 days with a promo code (enter it in the shop dashboard or send /promo to the bot). During this period invoices have feePercent = "0", feeAmount = "0", and charged equals amount for any feeMode.

The fee is 0.75% of the order amount. Who pays it is determined by feeMode (defaults to the application setting):

• The exchange rate is calculated at the moment of payment: the buyer pays the charged amount, converted to the chosen coin. This quantity is paidAmount in paidToken.
• The same coin is credited to the shop's balance: paidAmount × (charged − feeAmount) / charged, rounded down to the coin's precision. From then on, the coin's exchange rate is your responsibility: we do not convert it.
• Amounts are returned without rounding to cents: the fee for $5 is "0.0625". There is no minimum fee.
• An invoice is valid for 1 hour (expiresAt), after which it cannot be paid. Payment is made from the internal balance, so underpayments and overpayments are not possible when paying from an OroPay balance; for payments to an address see the 99% rule there.

The invoice object

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 subscription, 1 month","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 subscription, 1 month",
    "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 subscription, 1 month",
        "feeMode": "BUYER",
    },
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "invoice": {
    "code": "PRbtixbbdeoy",
    "status": "PENDING",
    "orderId": "order-1024",
    "description": "Pro subscription, 1 month",
    "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"
}

Webhooks

We send a POST request with a JSON body to your URL. Webhooks are optional: if you don't provide a URL, you won't receive notifications, but you can still poll for the status via an API request.

URL requirements

• Must be an https:// URL, up to 512 characters, a hostname, not an IPv6 address.
• localhost, *.local, *.internal, and internal IP ranges (10.x, 127.x, 169.254.x, 172.16–31.x, 192.168.x, 100.64/10, etc.) are forbidden. Before each delivery attempt, the hostname is resolved via DNS, and if it points to an internal address, the notification is not sent.
• Redirects are not followed: a 3xx response is considered a failure.

Headers

invoice.paid body

{
  "event": "invoice.paid",
  "invoice": {
    "code": "PRbtixbbdeoy",
    "status": "PAID",
    "orderId": "order-1024",
    "description": "Pro subscription, 1 month",
    "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 body

{
  "event": "invoice.refunded",
  "refund": {
    "id": "311",
    "refundId": "order-1024-r1",
    "invoiceCode": "PRbtixbbdeoy",
    "asset": "USDT",
    "network": "TRON",
    "amount": "40",
    "reason": "Item out of stock",
    "createdAt": "2026-09-25T14:00:00.000Z"
  },
  "refundedTotal": "40",
  "refundable": "61.2601",
  "invoice": { "code": "PRbtixbbdeoy", "status": "PAID", "…": "…" }
}

Verifying signatures

The signature is the hex-encoded HMAC-SHA256 of the string timestamp + "\n" + body, where timestamp is the value from the x-cxc-timestamp header and body is the raw request payload. The HMAC key is your application's webhook secret (not the API key). This method is the same for all events.

1. Read the request body as raw bytes before parsing the JSON. A parsed and re-serialized JSON will produce a different signature.
2. Compute the HMAC and compare it with the x-cxc-signature header value using a constant-time comparison function.
3. Verify the timestamp. Reject the notification if the x-cxc-timestamp differs from your server's clock by more than 5 minutes (in either direction). The signature proves that the notification is from us, but not that it's recent. Without a timestamp check, an intercepted request could be replayed later. A new timestamp is generated for each delivery attempt, so retries after a failure will pass this check. Keep your server's clock synchronized (e.g., using NTP).
4. If the signature or timestamp is invalid, respond with an error and take no action. If it's valid, process the event and respond with a 2xx status code.

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; // older than 5 minutes — reject

// The body must be raw: the signature is calculated over bytes, not parsed 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") || "";
  // Time: timestamp is Unix milliseconds. No timestamp or it's off by more than 5 minutes — reject.
  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") {
    // Fulfill the order event.invoice.orderId if it hasn't been fulfilled yet.
  }
  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  # older than 5 minutes — reject

@app.post("/oropay/webhook")
def oropay_webhook():
    body = request.get_data()  # raw bytes, before JSON parsing
    ts = request.headers.get("x-cxc-timestamp", "")
    # Time: timestamp is Unix milliseconds. No timestamp or it's off by more than 5 minutes — reject.
    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  # fulfill the order event["invoice"]["orderId"] if it hasn't been fulfilled yet
    return "", 200

Delivery and retries

• The first attempt is made immediately after the event. Success is a 2xx response within 15 seconds. Your response body is not read.
• On failure (another status code, timeout, connection drop, 3xx), we retry with an increasing delay: 1, 2, 4, 8, 16, 32 minutes, then once per hour. Up to 12 attempts in total — about 6 hours. The queue is checked once a minute.
• Each attempt comes with a new x-cxc-timestamp and a new signature.
• Webhooks for subscriptions and refunds are delivered under the same rules.

Test webhook

In your shop dashboard (Keys tab, next to the webhook URL), there is a "Send test webhook" button. We send a test event to the URL from your application settings, following the same process as real events: same x-cxc-signature signed with the webhook secret, same address validation (internal addresses are prohibited), no redirects, 15-second timeout. The dashboard immediately shows your server's response: status code, time, the first 500 characters of the response, or an error.

{
  "event": "test",
  "test": true,
  "id": "test_9a8b7c6d5e4f",
  "app": { "id": "17", "name": "Sadovaya Coffee Shop" },
  "createdAt": "2026-09-26T09:50:00.000Z",
  "message": "Test event from the dashboard. Verify the signature and respond with 2xx; no money is involved."
}

How to distinguish a test event from a real one

• In the body: "event": "test" and "test": true; in the headers: x-cxc-event: test and x-cxc-test: 1.
• There is no invoice and no x-cxc-invoice header: no money is involved in a test. Do not fulfill anything — just verify the signature and respond with 2xx.
• A test event is not retried on failure and does not enter the retry queue.
• No more than 10 tests per minute per owner (across all their shops).

Payouts

You can pay people from your shop balance: using cheques (a link that any Telegram user can use to claim money) and transfers by Telegram ID. This is useful, for example, for a bot that pays for completed tasks. The shop balance is the owner's balance, the same one that receives invoice payments.

How to enable

1. Set a PIN code in the OroPay settings — payouts cannot be enabled without it (error PIN_NOT_SET).
2. In the mini app, open "Shop" → application → "Payouts and Refunds".
3. Enable "API Payouts" and confirm with your PIN code. The payouts scope will be automatically added to the key.
4. Set the daily limit and single payout limit.

An API payout is processed only if all of the following are true: the key has the payouts scope, the "API Payouts" switch is enabled, the owner's funds are not frozen, and a PIN code recovery is not in progress. Otherwise — 403 PAYOUTS_DISABLED or 403 OWNER_FROZEN. Invoice refunds also require the "API Payouts" switch to be enabled (the payouts scope is not needed for them) — otherwise 403 REFUNDS_DISABLED.

Limits

• Dollars are calculated based on the coin's exchange rate at the time of the payout. If there's no rate, 503 RATE_UNAVAILABLE is returned, and the payout is not made.
• Limits are checked under an owner-level lock within the same transaction as the debit: concurrent requests will not bypass the limit together.
• Canceling a cheque returns the remainder to the balance but does not restore the daily limit.
• Current values and the remaining amount for today are available in the balance.

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":"For subscribing to the channel","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": "For subscribing to the channel",
    "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": "For subscribing to the channel",
        "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": "For subscribing to the channel",
    "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":"Task #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": "Task #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": "Task #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": "Task #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":"Product is out of stock"}'

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": "Product is out of stock"
  }),
});
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": "Product is out of stock",
    },
    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": "Product is out of stock",
    "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", "…": "…" }
}

Subscriptions

Recurring payments. You create a plan, a user subscribes via the plan's link https://t.me/OroPayBot?start=SB… or in the Mini App and confirms it with their PIN code, if they have one set up. This constitutes their consent for automatic charges from their OroPay balance.

• The first charge occurs immediately upon subscription; if the plan includes a trial period, the charge occurs on the day it ends. The trial is offered only once: to users who have not had any previous subscriptions in your shop.
• Subsequently, we charge the price on the renewal date (nextChargeAt); the user receives a reminder 24 hours prior. Renewals are checked every 10 minutes.
• If there are insufficient funds or the funds are frozen, the status becomes past_due, access is denied, and we retry after 24 hours. After the third failed attempt, the status becomes expired. If the shop's application is disabled, the subscription also becomes expired upon renewal.
• Cancellation (by the user or by you) — we stop charging, and access remains until the end of the paid period. Funds for the current period are not automatically refunded.
• You receive the price minus the same commission as for invoices (0.75%), credited to the shop owner's balance.
• There is exactly one charge per period — this is enforced by a unique index in the database.

Plan conditions: currency must be USDT or USDC; period can be 7, 30, 90, or 365 days; trial can be 0, 3, or 7 days; price ranges from 0.01 to 100000. The price and period cannot be changed after creation: a new price requires a new plan. Up to 50 plans per application, including disabled ones. Requires the subscriptions or invoices key scope. The rate for these methods is limited by a general counter of 120 requests per minute per IP address.

curl -X POST https://oropay.app/api/merchant/v1/plans \
  -H "Authorization: Bearer $OROPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"VIP channel","asset":"USDT","price":"9.99","period_days":30,"trial_days":3,"description":"Access to a private channel","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 channel",
    "asset": "USDT",
    "price": "9.99",
    "period_days": 30,
    "trial_days": 3,
    "description": "Access to a private channel",
    "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 channel",
        "asset": "USDT",
        "price": "9.99",
        "period_days": 30,
        "trial_days": 3,
        "description": "Access to a private channel",
        "plan_id": "vip-monthly",
    },
    timeout=30,
)
data = r.json()

{
  "ok": true,
  "repeated": false,
  "plan": {
    "code": "SBk3m9x2pq7a",
    "planId": "vip-monthly",
    "name": "VIP channel",
    "description": "Access to a private channel",
    "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 channel", "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 channel" },
      "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", "…": "…" }
}

Subscription events

Events are sent to the webhook URL specified in the app settings. No URL, no events. Signature and retries work the same way as for invoices (signature verification). Additional headers: x-cxc-event, x-cxc-event-id, x-cxc-subscription. On redelivery, the event is sent with the same id — do not grant access twice.

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

Error codes

All code values for /api/merchant/v1/… methods. Older invoice methods do not have a code; they only return an error text and an HTTP status (see Create invoice).

Coins and Networks

Networks (network): TRON, TON, EVM, BSC, LTC, BTC, SOL, XRP. If you hold a coin in only one network, you can omit the network parameter. For subscriptions, only USDT and USDC are supported. Invoices are issued in fiat, the coin is chosen by the customer.