Dokumentacja API

Wprowadzenie

Payman API to interfejs REST w formacie JSON. Wszystkie żądania są wysyłane na adres https://payman33.com/v1 poprzez HTTPS.

Uwierzytelnianie

Wyślij token dostępu otrzymany przy tworzeniu konta jako token Bearer. Jest on wyświetlany tylko raz i nie może być ponownie wystawiony, więc zachowaj go w tajemnicy i nigdy nie umieszczaj w kodzie po stronie klienta.

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxx

Wyślij wiadomość

POST /messages

Pole	Typ	Opis
`to`	string[]	Odbiorcy w formacie E.164. Maksymalnie 10 000 na żądanie.
`text`	string	Treść wiadomości: jedna SMS, do 160 znaków (GSM-7) lub 70, jeśli zawiera inne litery lub emoji. Dłuższe teksty są odrzucane.
`schedule_at`	string	Opcjonalny czas w formacie ISO-8601 do wysłania później, maksymalnie 30 dni w przód.
`callback_url`	string	Opcjonalny URL HTTPS, który otrzymuje raporty dostarczenia.

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

Dodaj nagłówek Idempotency-Key, aby bezpiecznie ponowić próbę: ten sam klucz w ciągu 24 godzin zwróci oryginalną odpowiedź zamiast wysyłać ponownie.

Status wiadomości

GET /messages/{id}

Statusy: queued, następnie sent, potem delivered lub failed. Zaplanowana wiadomość pozostaje scheduled aż zostanie wysłana; anuluj ją (i odzyskaj opłatę) za pomocą POST /messages/{id}/cancel.

Webhooki

Gdy raport dostarczenia dotrze, wysyłamy go metodą POST na Twój callback_url. Każde żądanie zawiera nagłówek X-Payman-Signature: HMAC-SHA256 ciała z Twoim sekretem webhooka (Dashboard, zakładka API), abyś mógł je zweryfikować. Nieudane dostarczenia są ponawiane do 3 razy.

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

Saldo

GET /balance

Zwraca aktualne saldo w USDT. Ceny są podane w USD; 1 USDT = 1 USD.

Błędy

HTTP	Kod	Znaczenie
400	`invalid_request`	Brakujące lub błędnie sformatowane pole.
401	`unauthorized`	Brakujący lub nieprawidłowy klucz API.
402	`insufficient_balance`	Doładuj konto, aby kontynuować wysyłanie.
403	`verification_required`	Niezweryfikowane konta osiągnęły dzienny limit odbiorców.
404	`not_found`	Brak takiej wiadomości na Twoim koncie.
429	`rate_limited`	Zbyt wiele żądań. Spróbuj ponownie po czasie podanym w nagłówku `Retry-After`.

Limity szybkości

Domyślny limit to 50 żądań na sekundę na konto. Używaj zbiorczych wysyłek (wiele numerów w to) w dużych kampaniach. Niezweryfikowane konta mogą wysyłać do maksymalnie 500 odbiorców dziennie.