Northgate
API команды

API команды

Всё, что есть в панели, — из вашей CRM или скрипта: саб-аккаунты и переводы между ними, выпуск и настройки карт, полные данные карт, транзакции.

Адрес: https://api.northgate.cards. Описание для генераторов клиентов и MCP: openapi.json.

Ключ

Создаётся в панели: Настройки → API (нужны права админа команды). Ключ показывается один раз — сохраните его в надёжном месте. Он работает только для вашей команды, от имени админа, который его создал, и перестаёт работать сразу после отзыва в панели.

curl https://api.northgate.cards/v1/balance \
  -H "Authorization: Bearer ng_live_…"

Можно и заголовком X-Api-Key: ng_live_…. Ключ не передавайте в браузер и не кладите в код фронтенда — только на сервер.

Правила

Ошибки

Команда и деньги

GET/v1/me
Чей это ключ: команда и админ, от имени которого он действует
GET/v1/balance
Баланс команды
availableCents — сколько можно перевести на саб-аккаунты прямо сейчас; heldCents — удержано (комиссия по пополнениям в обработке и комиссии за отказы).
GET/v1/deposit-addresses
Адреса для пополнения (USDC в Base/Ethereum, USDT в Tron)
GET/v1/deposits?page=1&pageSize=50
Входящие пополнения: пришло, комиссия, зачислено

Саб-аккаунты

GET/v1/sub-accounts
Все саб-аккаунты с балансом и числом карт
GET/v1/sub-accounts/{id}
Один саб-аккаунт
POST/v1/sub-accounts
Создать саб-аккаунт
{ "name": "TikTok" }
POST/v1/sub-accounts/{id}/allocate
Перевести с основного баланса на саб-аккаунт
{ "amountCents": 150000, "note": "на рекламу" }
POST/v1/sub-accounts/{id}/return
Вернуть с саб-аккаунта на основной баланс
{ "amountCents": 5000 }
POST/v1/transfers
Перевод между саб-аккаунтами
{ "fromSubAccountId": "…", "toSubAccountId": "…", "amountCents": 20000 }

Карты

GET/v1/bins
БИНы, на которых сейчас можно выпустить карту
GET/v1/cards?subAccountId=…&status=active
Карты команды (фильтры необязательны)
GET/v1/cards/{id}
Одна карта
POST/v1/cards
Выпустить карту
bin — один из /v1/bins, без него — любой. limit.period: daily, weekly, monthly, yearly или lifetime (на всё время жизни карты).
{
  "subAccountId": "…",
  "name": "FB 01",
  "bin": "40041606",
  "limit": { "amountCents": 100000, "period": "monthly" }
}
POST/v1/cards/bulk
Выпустить пачку — до 20 карт по шаблону ({n} — номер)
Останавливается на первом отказе: выпущенное — в issued, причина — в stopped.
{ "subAccountId": "…", "nameTemplate": "FB {n}", "count": 10, "startAt": 1 }
PATCH/v1/cards/{id}
Изменить: название, заметка, пауза / включение / закрытие, лимит
"limit": null снимает лимит. Передавайте только то, что меняете.
{ "status": "paused", "note": "BM 123 · кабинет 7" }
GET/v1/cards/{id}/details
Полные данные карты: номер, CVV, срок, платёжный адрес
Каждый запрос пишется в журнал команды. Не больше 30 в минуту на ключ.

Транзакции

GET/v1/transactions?status=declined&from=2026-10-01&page=1
Транзакции с фильтрами и страницами
Фильтры: subAccountId, cardId, status (pending, settled, declined, reversed, refunded), from, to, q (мерчант, название или последние 4 карты, заметка). summary — траты и число отказов по всему фильтру. У отказа есть declineReasonText — причина простыми словами.

Вебхуки — управление

GET/v1/webhooks
Ваши адреса для событий
POST/v1/webhooks
Добавить адрес (до 5 на команду)
secret для проверки подписи приходит в ответе один раз. Для balance.low нужен порог: lowBalanceCents (каждый саб-аккаунт) и/или lowMainBalanceCents (основной баланс).
{
  "url": "https://ваш-сервер.com/northgate",
  "events": ["balance.low", "transaction.declined"],
  "lowBalanceCents": 10000
}
PATCH/v1/webhooks/{id}
Изменить: адрес, события, пороги, включить/выключить
{ "enabled": false }
POST/v1/webhooks/{id}/test
Отправить тестовое событие сейчас и увидеть ответ вашего адреса
POST/v1/webhooks/{id}/rotate-secret
Новый секрет подписи (старый перестаёт работать сразу)
GET/v1/webhooks/{id}/deliveries
Журнал доставок: что ушло, что ответил адрес, когда повтор

Пример: карта под новый кабинет

# 1. перевести $500 на саб-аккаунт
curl -X POST https://api.northgate.cards/v1/sub-accounts/SUB_ID/allocate \
  -H "Authorization: Bearer ng_live_…" \
  -H "Idempotency-Key: alloc-2026-10-02-01" \
  -H "Content-Type: application/json" \
  -d '{"amountCents": 50000}'

# 2. выпустить карту с месячным лимитом
curl -X POST https://api.northgate.cards/v1/cards \
  -H "Authorization: Bearer ng_live_…" \
  -H "Idempotency-Key: card-fb-01" \
  -H "Content-Type: application/json" \
  -d '{"subAccountId": "SUB_ID", "name": "FB 01",
       "limit": {"amountCents": 50000, "period": "monthly"}}'

# 3. взять номер и CVV, чтобы привязать к рекламному кабинету
curl https://api.northgate.cards/v1/cards/CARD_ID/details \
  -H "Authorization: Bearer ng_live_…"

Оповещения (вебхуки)

Подписывайтесь на события — мы пришлём POST с JSON на ваш https-адрес. Добавить адрес можно в панели (Настройки → Вебхуки) или через POST /v1/webhooks.

Каждое событие выглядит так:

{
  "id": "6f1c…",            // ID события — одинаковый в повторах, убирайте дубли по нему
  "type": "balance.low",
  "createdAt": "2026-10-02T12:00:00.000Z",
  "teamId": "…",
  "data": {
    "scope": "sub_account",
    "subAccount": { "id": "…", "name": "TikTok" },
    "previousCents": 15000,
    "balanceCents": 8000,
    "thresholdCents": 10000,
    "currency": "USD"
  }
}

Проверяйте подпись. В заголовке X-Northgate-Signature: t=…,v1=… — время и HMAC-SHA256 от t.тело вашим секретом. Считайте её от тела ровно в том виде, как оно пришло, и отклоняйте события старше 5 минут:

// Node.js / Express — тело нужно сырым: app.post(path, express.raw({ type: 'application/json' }), …)
import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? '', 'hex');
  return given.length === expected.length && timingSafeEqual(given, expected);
}

Ответьте любым 2xx в течение 10 секунд. Иначе повторим через 10 с, 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 12 ч — всего 8 попыток. Порядок событий не гарантирован. Адрес должен быть публичным: внутренние и локальные адреса не принимаются.

MCP — для Claude, Cursor и других AI

Тот же ключ подключает команду к AI-ассистенту: он сможет смотреть балансы и транзакции, выпускать и настраивать карты, переводить деньги между саб-аккаунтами. Сервер: https://api.northgate.cards/mcp (Streamable HTTP).

Claude Code

claude mcp add --transport http northgate https://api.northgate.cards/mcp \
  --header "Authorization: Bearer ng_live_…"

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "northgate": {
      "url": "https://api.northgate.cards/mcp",
      "headers": { "Authorization": "Bearer ng_live_…" }
    }
  }
}

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "northgate": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.northgate.cards/mcp",
               "--header", "Authorization: Bearer ng_live_…"]
    }
  }
}

Инструмент get_card_details отдаёт номер и CVV карты — эти данные попадут в контекст модели. Ассистент вызывает его только по прямой просьбе, а каждый вызов пишется в журнал команды. Для автоматизации без людей лучше отдельный ключ — его можно отозвать, не трогая остальные интеграции.

API команды — Northgate