Документация API

Введение

Payman API работает как JSON REST API. Все запросы отправляются на https://payman33.com/v1 по HTTPS.

Авторизация

Передавайте токен доступа, полученный при создании аккаунта, как bearer-токен. Он показывается только один раз и не может быть выпущен повторно, поэтому храните его в секрете и никогда не размещайте в клиентском коде.

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxx

Отправка сообщения

POST /messages

Поле	Тип	Описание
`to`	string[]	Получатели в формате E.164. До 10 000 на запрос.
`text`	string	Текст сообщения: одна SMS, до 160 символов (GSM-7) или 70, если в нём есть любые другие буквы или эмодзи. Более длинный текст отклоняется.
`schedule_at`	string	Необязательно. Время отложенной отправки в формате ISO-8601, не более чем на 30 дней вперёд.
`callback_url`	string	Необязательно. HTTPS-адрес для получения отчётов о доставке.

{
  "id": "msg_01J9Z3K8V2",
  "status": "queued",
  "recipients": 1,
  "segments": 1,
  "cost": 0.0063
}

Добавьте заголовок Idempotency-Key для безопасных повторов: тот же ключ в течение 24 часов возвращает исходный ответ без повторной отправки.

Статус сообщения

GET /messages/{id}

Статусы: сначала queued, затем sent, затем delivered или failed. Запланированное сообщение остаётся в статусе scheduled до отправки; отменить его (с возвратом средств) можно через POST /messages/{id}/cancel.

Вебхуки

Когда приходит отчёт о доставке, мы отправляем его методом POST на ваш callback_url. Каждый запрос содержит заголовок X-Payman-Signature: это HMAC-SHA256 тела запроса с вашим секретом вебхука (Личный кабинет, вкладка API), чтобы вы могли проверить запрос. Неудачные доставки повторяются до 3 раз.

{
  "id": "msg_01J9Z3K8V2",
  "to": "+14155550123",
  "status": "delivered",
  "delivered_at": "2026-10-09T08:12:03Z"
}

Баланс

GET /balance

Возвращает текущий баланс в USDT. Цены указаны в USD; 1 USDT = 1 USD.

Ошибки

HTTP	Код	Значение
400	`invalid_request`	Поле отсутствует или имеет неверный формат.
401	`unauthorized`	API-ключ отсутствует или недействителен.
402	`insufficient_balance`	Пополните баланс, чтобы продолжить отправку.
403	`verification_required`	Неверифицированный аккаунт достиг дневного лимита получателей.
404	`not_found`	В вашем аккаунте нет такого сообщения.
429	`rate_limited`	Слишком много запросов. Повторите попытку по истечении времени из заголовка `Retry-After`.

Лимиты запросов

Лимит по умолчанию: 50 запросов в секунду на аккаунт. Для крупных рассылок используйте массовую отправку (несколько номеров в to). Неверифицированные аккаунты могут отправлять сообщения не более чем 500 получателям в день.