API для разработчиков

Merchant API позволяет встроить Millida Trade в собственный сайт: принимать оплату (Millida работает как платёжная система) и выдавать товары на сервере без установки плагина — ваш бэкенд сам забирает очередь команд.

База API: https://api.millida.trade/v2/merchant. Все суммы — в копейках (1 ₽ = 100 копеек).

Получение API-ключа

Ключ выпускается в личном кабинете магазина: раздел «Интеграции → API-ключи». При создании вы один раз получаете секрет вида mtk_live_… — сохраните его, повторно он не показывается.

Ключ можно ограничить правами (scopes):

• payments — создание и управление счетами;
• deliveries — забор и подтверждение очереди выдачи;
• read — чтение счетов, серверов и товаров.

Пустой набор прав = полный доступ. Ключ можно отозвать или перевыпустить в любой момент.

Аутентификация

Передавайте ключ в заголовке Authorization: Bearer или X-Api-Key:

Authorization: Bearer mtk_live_xxxxxxxxxxxxxxxx

Ключ привязан к одному магазину. Лимит запросов — 240/мин на ключ (создание счёта — 120/мин).

Millida как платёжная система

Сценарий: у вас свой сайт-витрина, оплату проводит Millida. Создаёте счёт, перенаправляете покупателя на paymentUrl, после оплаты получаете вебхук.

Создать счёт на произвольную сумму

POST /v2/merchant/invoices
Content-Type: application/json

{
  "externalId": "order-1042",
  "amountKopecks": 19900,
  "description": "VIP на 30 дней",
  "playerNickname": "Steve",
  "customerEmail": "player@example.com"
}

Ответ:

{
  "id": "clx…",
  "externalId": "order-1042",
  "status": "pending",
  "amountKopecks": 19900,
  "commissionKopecks": 995,
  "netKopecks": 18905,
  "paymentUrl": "https://millida.trade/checkout/clx…",
  "paidAt": null,
  "createdAt": "2026-06-16T10:00:00.000Z"
}

Перенаправьте покупателя на paymentUrl — там он выберет СБП или карту. externalId — ваш идентификатор заказа; повторный запрос с тем же externalId вернёт тот же счёт (защита от дублей).

Счёт по каталогу магазина

Если товары заведены в магазине Millida, передайте позиции — сумма и выдача рассчитаются автоматически:

POST /v2/merchant/invoices
{
  "externalId": "order-1043",
  "playerNickname": "Steve",
  "items": [{ "productId": "prod_…", "quantity": 1 }]
}

Проверить статус

GET /v2/merchant/invoices/clx…

Статусы: pending, paid, delivered, failed, cancelled, refunded. Список — GET /v2/merchant/invoices?status=paid&limit=50.

Выдача без плагина

Сценарий: вы не ставите MC-плагин, а сами исполняете команды на сервере. Укажите команды при создании счёта — после оплаты они попадут в очередь, а ваш бэкенд их заберёт.

Команды в счёте

POST /v2/merchant/invoices
{
  "externalId": "order-1044",
  "amountKopecks": 9900,
  "playerNickname": "Steve",
  "delivery": {
    "serverId": "srv_…",
    "commands": ["lp user Steve parent add vip", "say Steve купил VIP"]
  }
}

serverId берётся из GET /v2/merchant/servers.

Забрать очередь

Опрашивайте очередь (например, раз в 3–5 секунд). Выданные команды атомарно резервируются за вами:

GET /v2/merchant/deliveries?limit=20

{
  "deliveries": [
    {
      "id": "del_…",
      "orderId": "clx…",
      "externalId": "order-1044",
      "serverId": "srv_…",
      "playerNickname": "Steve",
      "commands": ["lp user Steve parent add vip", "say Steve купил VIP"],
      "allowOffline": false
    }
  ]
}

Подтвердить выполнение

После исполнения команд на сервере подтвердите доставку:

POST /v2/merchant/deliveries/del_…/ack
{ "success": true }

При ошибке отправьте { "success": false, "message": "player offline" } — доставка вернётся в очередь и придёт снова (до 20 попыток).

Вебхуки

Укажите webhookUrl при создании ключа — и получайте уведомления о событиях счёта. Вместе с URL выдаётся webhookSecret для проверки подписи.

События: invoice.paid, invoice.failed, invoice.delivered.

POST https://ваш-сайт/webhook
X-Millida-Event: invoice.paid
X-Millida-Signature: sha256=…

{
  "event": "invoice.paid",
  "data": {
    "id": "clx…",
    "externalId": "order-1042",
    "status": "PAID",
    "amountKopecks": 19900,
    "commissionKopecks": 995,
    "netKopecks": 18905,
    "playerNickname": "Steve",
    "paidAt": "2026-06-16T10:01:00.000Z"
  }
}

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

Подпись — HMAC-SHA256 от «сырого» тела запроса с вашим webhookSecret. Сравнивайте безопасно (constant-time):

import { createHmac, timingSafeEqual } from 'crypto';

function verify(rawBody, header, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(header);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Безопасность

• Секрет ключа храните на сервере, не на фронтенде. Скомпрометированный ключ — отзовите и перевыпустите в ЛК.
• Сумму к зачислению всегда берите из вебхука/GET /invoices/:id, а не из данных, пришедших с клиента.
• Всегда проверяйте подпись вебхука и идемпотентность по externalId (вебхук может прийти повторно).
• Комиссия платформы удерживается автоматически; в ответе видны commissionKopecks и netKopecks (сумма к зачислению).