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_…. Ключ не передавайте в браузер и не кладите в код фронтенда — только на сервер.
Правила
- Деньги — целые центы USD:
150000= $1 500.00. Даты — ISO 8601 (UTC). - Лимит — 120 запросов в минуту на ключ, данные карт — 30 в минуту. При превышении — код 429 и заголовок
Retry-After(сколько секунд подождать). - Повторы без дублей. У POST-запросов указывайте заголовок
Idempotency-Keyс любым своим уникальным значением. Если ответ потерялся и вы повторили запрос с тем же ключом — придёт первый ответ, а карта не выпустится и деньги не переведутся второй раз. Тот же ключ с другим телом запроса — 422. - Неизвестное поле в теле запроса — ошибка 400 с названием поля, а не молчаливый пропуск.
Ошибки
- 400 — ошибка в запросе; поле и причина — в
details - 401 — нет ключа, ключ неверный или отозван
- 403 — команда приостановлена
- 404 — не найдено (объекты других команд для ключа не существуют)
- 409 / 422 — запрос с этим Idempotency-Key ещё выполняется / ключ уже использован для другого запроса
- 429 — превышен лимит, подождите Retry-After секунд
Команда и деньги
availableCents — сколько можно перевести на саб-аккаунты прямо сейчас; heldCents — удержано (комиссия по пополнениям в обработке и комиссии за отказы).Саб-аккаунты
{ "name": "TikTok" }{ "amountCents": 150000, "note": "на рекламу" }{ "amountCents": 5000 }{ "fromSubAccountId": "…", "toSubAccountId": "…", "amountCents": 20000 }Карты
bin — один из /v1/bins, без него — любой. limit.period: daily, weekly, monthly, yearly или lifetime (на всё время жизни карты).{
"subAccountId": "…",
"name": "FB 01",
"bin": "40041606",
"limit": { "amountCents": 100000, "period": "monthly" }
}issued, причина — в stopped.{ "subAccountId": "…", "nameTemplate": "FB {n}", "count": 10, "startAt": 1 }"limit": null снимает лимит. Передавайте только то, что меняете.{ "status": "paused", "note": "BM 123 · кабинет 7" }Транзакции
subAccountId, cardId, status (pending, settled, declined, reversed, refunded), from, to, q (мерчант, название или последние 4 карты, заметка). summary — траты и число отказов по всему фильтру. У отказа есть declineReasonText — причина простыми словами.Вебхуки — управление
secret для проверки подписи приходит в ответе один раз. Для balance.low нужен порог: lowBalanceCents (каждый саб-аккаунт) и/или lowMainBalanceCents (основной баланс).{
"url": "https://ваш-сервер.com/northgate",
"events": ["balance.low", "transaction.declined"],
"lowBalanceCents": 10000
}{ "enabled": false }Пример: карта под новый кабинет
# 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.
balance.low— баланс саб-аккаунта или основной опустился ниже вашего порога. Приходит один раз на пересечение: пока баланс ниже — повторов нет; поднялся выше и снова упал — придёт снова.balance.changed— изменился любой баланс (прежнее и новое значение).deposit.confirmed— пополнение пришло и зачислено.transaction.declined— платёж по карте отклонён, с причиной простыми словами.
Каждое событие выглядит так:
{
"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 карты — эти данные попадут в контекст модели. Ассистент вызывает его только по прямой просьбе, а каждый вызов пишется в журнал команды. Для автоматизации без людей лучше отдельный ключ — его можно отозвать, не трогая остальные интеграции.