ZergPay CLI и Live Explorer

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

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

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

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

zergpay-cli - webhook'и без ngrok

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

Установка

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Авто-reconnect

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

Параметры