Документація 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 URL для отримання звітів про доставку.

{
  "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 отримувачам на день.