balancedpay CLI и Live Explorer

Два инструмента, чтобы развернуть локальную интеграцию за минуту: balancedpay-cli ловит webhook'и без проброса тоннеля, Live Explorer запускает запросы прямо со страницы доки.

Live Explorer (на этой странице)

Кнопка ▶ Run в шапке любой ручки открывает попап с предзаполненным запросом. Введите sk_test_… ключ один раз — он закэшируется в localStorage браузера. Дальше Run, и видите реальный ответ API.

• Тело запроса можно править на лету: amount = 100099, чтобы получить insufficient_funds; 100050 для 3DS-флоу; и так далее (см. раздел «Тестирование»).
• Ответ показывается с HTTP-статусом, временем и красивой подсветкой. Кнопка «копировать» — рядом.
• На sk_live_… попросим подтверждение: запрос пойдёт в реальный банк, нечаянно нажать Run в production-режиме не получится.

balancedpay-cli — webhook'и без ngrok

Локальный helper, который слушает события мерчанта через SSE и форвардит их POST'ом на localhost. Аналог stripe-cli listen: ваш dev-сервер получает реальные webhook'и, не имея публичного URL.

Установка

go install github.com/balancedpay/cli/balancedpay@latest

# или скачайте релизный бинарник под вашу ОС:
# https://github.com/balancedpay/cli/releases

Авторизация: balancedpay login

Один раз сохраняем ключ в ~/.balancedpay/config.json. Дальше balancedpay listen, balancedpay trigger и прочие команды берут его сами.

$ balancedpay login
balancedpay API key (sk_test_… или sk_live_…): sk_test_xxxxxx_yyyy
✓ профиль "default" сохранён в ~/.balancedpay/config.json
  ключ: sk_test_xxx••••••yyyy
  url:  https://api.balancedpay.pro

# Несколько профилей:
$ balancedpay login --profile staging --base-url https://api.staging.balancedpay.pro
$ balancedpay status
Профили:
* default      sk_test_xxx••••••yyyy  https://api.balancedpay.pro
  staging      sk_test_aaa••••••bbbb  https://api.staging.balancedpay.pro
$ balancedpay use staging
$ balancedpay logout --profile staging

Файл с правами 0600, проверка ключа через тестовый GET перед сохранением — невалидные ключи отклоняются на этапе login.

Триггер событий: balancedpay trigger

Чтобы прокачать webhook-handler через все основные сценарии, не придумывая нужные суммы вручную:

$ balancedpay trigger payment.succeeded
✓ payment 5a331a39-…, status=succeeded, mode=test

$ balancedpay trigger payment.failed
✓ payment 8c7f12ab-…, status=failed, mode=test

$ balancedpay trigger payment.refunded
→ payment 9b2c1f8a-… создан, ждём succeeded…
✓ refund 4d11e3c4-…, status=succeeded, amount=10000

$ balancedpay trigger payment.cancelled
✓ payment 7e8aa4dd-… отменён

$ balancedpay trigger payout.failed
✓ payout f47ac10b-…, status=failed, mode=test

Под капотом — обычные POST на public-API с правильными триггерами симулятора (см. раздел «Тестирование»). При запущенном balancedpay listen webhook'и сразу прилетят на ваш dev-сервер.

Использование listen

# Авто-credentials из login:
balancedpay listen --forward-to http://localhost:3000/balancedpay/hook

# Или ad-hoc через ENV:
export FREEFIN_API_KEY=sk_test_xxxxxx
balancedpay listen --forward-to http://localhost:3000/balancedpay/hook

Что произойдёт при запуске:

1. CLI откроет SSE-стрим на /api/v1/public/cli/listen под вашим ключом.
2. Сервер выдаст одноразовый webhook secret для этой сессии. CLI напечатает его в первой строке: cli_a3f9e7…. Положите его вFREEFIN_WEBHOOK_SECRET своего dev-сервера.
3. Каждое событие мерчанта (платёж, выплата, возврат) CLI завернёт в стандартный webhook envelope, подпишет HMAC-SHA256 и POST'нет на --forward-to URL.

balancedpay-cli: connected, forward → http://localhost:3000/balancedpay/hook
balancedpay-cli: webhook secret для этой сессии: cli_a3f9e7…
balancedpay-cli: положите его в FREEFIN_WEBHOOK_SECRET вашего dev-окружения,
             чтобы verifyWebhook прошёл.

  14:01:23 [payment.succeeded     ] evt_8f9a… → http://localhost:3000/balancedpay/hook 200 (12ms)
  14:01:24 [payment.refunded      ] evt_a23b… → http://localhost:3000/balancedpay/hook 200 (8ms)

Авто-reconnect

Если соединение порвётся (Wi-Fi, рестарт сервера), CLI спит 3 секунды и переподключается. События, прилетевшие в момент разрыва, для CLI потеряются — это режим разработки. Для гарантий поднимайте обычный webhook-endpoint в ЛК с фиксированным URL: там retry до ~3.5 дней.

Параметры