Подписки и автоплатежи

Магазин может запросить у пользователя Heth.me согласие на регулярные платежи. Плательщик проверяет и подписывает условия обычным разблокированным HethWallet. Отдельный вход по email или в Customer Portal не нужен. Платежи списываются с баланса счёта Heth в согласованных валюте и сети.

Плательщику

Откройте Настройки → Подписки и автоплатежи. Новые запросы показаны отдельно от существующих подписок.
Откройте запрос и проверьте магазин, сумму одного платежа, валюту/сеть и период. Ссылка подтверждения открывает этот же экран. Заблокированный кошелёк запросит обычный PIN и вернёт к запросу.
Нажмите Подтвердить подписку или Отклонить. Открытие ссылки или получение уведомления не подтверждает подписку.
После согласия планируется первый платёж. В списке видны сумма, период и дата следующего списания; при повторной попытке после ошибки — время следующей попытки.
Отзовите подписку, чтобы остановить будущие списания. Отмена не возвращает уже выполненные платежи.

Подтверждение записывает согласие и планирует платёж; оно не означает, что платёж уже прошёл. Проверяйте статус транзакции. В момент списания на балансе должно быть достаточно средств.

Как узнать о новом запросе

Если плательщик найден, сервер отправляет «Запрос на подписку» на зарегистрированные устройства со ссылкой /subscriptions/confirm/<request_id>?env=<env>. Запись также сохраняется под колоколом уведомлений, даже если ни одно устройство не может получить push. Ожидающие запросы доступны в Настройки → Подписки и автоплатежи.

В установленной PWA используется web push. Приложение Heth.me для iOS и Android, начиная с версии 1.0.0 (сборка 5), использует системные уведомления. Включите уведомления в кошельке и разрешите их в настройках устройства. Нажатие на запрос подписки открывает экран подтверждения; заблокированный кошелёк сначала попросит обычный PIN или доступный ключ входа. Получение или открытие уведомления не означает согласия на подписку. Если уведомление не пришло, откройте список ожидающих запросов или ссылку подтверждения от магазина.

Магазину

В HethWallet откройте Бизнес → Подписки и автоплатежи. Укажите адрес кошелька плательщика, @username или номер карты Heth, название подписки, сумму одного платежа, валюту/сеть и период. Отправьте запрос и скопируйте ссылку подтверждения. Здесь же можно смотреть свои запросы и отменять их, пока плательщик ещё не дал согласие.

Оператор должен включить подписки Heth для организации и настроить рабочий маршрут платежей. Создание запроса не даёт разрешения на списание.

Создание запроса через API

Используйте API-ключ магазина или его обычную партнёрскую Bearer-сессию. На app.heth.me организация определяется по домену. Ключ только для чтения не позволяет создавать и отменять запросы.

curl -X POST 'https://app.heth.me/api/v1/heth/subscription-requests' \
  -H "x-api-key: $HETH_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "request_id": "b56b2c66-4ae5-4cb9-92ea-7a3297b72b55",
    "payer": "@alice",
    "description": "Monthly membership",
    "amount": "1000000",
    "currency": "USDT",
    "network": "ETH",
    "interval": "monthly",
    "period": 1,
    "env": "prod"
  }'

Поле	Описание	Тип	Пример
`request_id`	Уникальный идемпотентный UUID. При повторе того же запроса используйте его с неизменными условиями.	String	`b56b2c66-4ae5-4cb9-92ea-7a3297b72b55`
`payer`	Адрес кошелька, имя пользователя или номер карты Heth.	String	`@alice`
`description`	Название подписки: 1–250 символов без переносов строки.	String	`Monthly membership`
`amount`	Положительное целое в минимальных единицах токена. Для USDT с 6 знаками `1000000` означает 1 USDT.	String	`1000000`
`currency`, `network`	Включённая пара токен/сеть выбранного контура. Сети: `ETH`, `TRX`, `BASE`.	String	`USDT`, `ETH`
`interval`	`daily`, `weekly`, `monthly` или `yearly`.	String	`monthly`
`period`	Число интервалов от 1 до 365; по умолчанию 1.	Number	`1`
`env`	`prod` (по умолчанию). Сохраняйте это значение при открытии и подтверждении запроса.	String	`prod`

HTTP 201 возвращает сам запрос, включая id, status, amount_decimals, confirm_url, expires_at, subscription_id и next_charge_at. Запрос действует семь дней. Успешное создание не раскрывает существование указанного плательщика; прочитать и подтвердить запрос может только его адресат.

Операции API

Все пути ниже начинаются с /api/v1. Для операций магазина нужен его API-ключ или партнёрская Bearer-сессия.

Метод и путь	Назначение
`POST /heth/subscription-requests`	Создать запрос.
`GET /heth/subscription-requests?env=prod&limit=50`	Получить запросы магазина в `data` и `total`.
`POST /heth/subscription-requests/:id/cancel`	Отменить ожидающий запрос; тело `{"env":"prod"}`.

Для первой страницы не передавайте page. Для следующей укажите page=1, затем увеличивайте номер; limit задаёт размер страницы.

Для операций кошелька нужна обычная Bearer-сессия кошелька плательщика. API-ключ магазина не может подтвердить подписку за плательщика.

Метод и путь	Назначение
`GET /heth/subscriptions?env=prod&limit=50`	Свои подписки в `data`/`total`, ожидающие запросы в `requests`/`requests_total`.
`GET /heth/subscription-requests/:id?env=prod`	Прочитать адресованный запрос и каноническое сообщение `message` для подписи.
`POST /heth/subscription-requests/:id/confirm`	Подтвердить с `{"signature":"<wallet signature>","env":"prod"}` после проверки точных условий.
`POST /heth/subscription-requests/:id/reject`	Отклонить; тело `{"env":"prod"}`.
`POST /heth/subscriptions/:id/revoke-mandate`	Остановить будущие списания; тело `{"env":"prod"}`.

Подпись связывает магазин, плательщика, организацию, контур, описание, сумму и её масштаб, валюту/сеть, интервал и период, правило первого платежа, nonce и срок действия. Для изменения условий нужны новый запрос и новое согласие. Повтор подтверждения или запланированного платежа не может дважды списать средства за один период. Временные метки API без часового пояса означают UTC; приложение показывает местное время устройства.

Статусы и ошибки

Статусы запроса: pending, signed, rejected, expired. У подтверждённого запроса заполнен subscription_id. Фактическое выполнение платежей отслеживается через API транзакций и настроенные webhooks.

401 означает отсутствие или недействительность авторизации; 403 — выключенные подписки или API-ключ только для чтения. Недоступный запрос возвращает 404. 422 означает неверные условия, повтор UUID с другими условиями, недействительную подпись или истёкший/закрытый запрос. Магазин не может изменить подписанные условия активной подписки без нового согласия плательщика.

Плательщику​

Как узнать о новом запросе​

Магазину​

Создание запроса через API​

Операции API​

Статусы и ошибки​