Wysyłki SMS

Na tej stronie wyślesz wiadomość SMS i sprawdzisz, czy została dostarczona. Wysyłki SMS Paymentic obsługują zarówno wiadomości transakcyjne (kody 2FA i jednorazowe hasła, statusy zamówień i przesyłek, potwierdzenia płatności, przypomnienia), jak i marketingowe, z wysoką dostępnością i krótkim czasem doręczenia. Używasz tego samego tokenu, tych samych hostów i tego samego formatu błędów co przy płatnościach.

Wymagania

• Token API z panelu (Integracja → Dostęp do API), przekazywany w nagłówku Authorization: Bearer YOUR_API_TOKEN. Zob. Wprowadzenie.
• Usługa SMS włączona dla Twojego konta. Bez niej API odpowiada 403 z kodem SMS_SERVICE_NOT_ACTIVE; włączenie uzgadniasz z opiekunem handlowym.
• Środki na portfelu SMS. Koszt każdej wiadomości jest pobierany z salda; przy braku środków API odpowiada 402 z kodem INSUFFICIENT_FUNDS.
• Cennik dla kraju odbiorcy. Jeśli dla numeru docelowego nie ma skonfigurowanej ceny, API odpowiada 400 z kodem PRICE_NOT_CONFIGURED.

Do testów użyj hosta https://api.sandbox.paymentic.com, na produkcji https://api.paymentic.com.

Krok 1. Wyślij wiadomość

curl -X POST "https://api.sandbox.paymentic.com/v1_2/messaging/sms/messages" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "+48123123123",
    "text": "Twoj kod to 1234.",
    "sender": "Paymentic",
    "externalReferenceId": "order-2026-000123"
  }'

Pole	Typ	Wymagane	Opis
recipient	string	tak	Numer odbiorcy w formacie E.164, z kodem kraju i plusem, np. +48123123123.
text	string	tak	Treść wiadomości.
sender	string	nie	Alfanumeryczna nazwa nadawcy, maks. 11 znaków. Pominięta: nadawca domyślny Twojego konta.
unicode	boolean	nie	true wymusza kodowanie UCS-2. Domyślnie false.
externalReferenceId	string	nie	Twój identyfikator wiadomości, maks. 36 znaków. Wraca w szczegółach wiadomości i pozwala powiązać ją z rekordem po Twojej stronie.
priority	string	nie	LOW (domyślnie), MEDIUM albo HIGH.

Odpowiedź 202 Accepted

{
  "data": {
    "id": "01JZX8K3M9QABCDEF0123456789",
    "status": "QUEUED",
    "sender": "Paymentic",
    "recipient": "+48123123123",
    "text": "Twoj kod to 1234.",
    "segmentsCount": 1,
    "totalCost": "0.053",
    "source": "API",
    "priority": "LOW",
    "externalReferenceId": "order-2026-000123",
    "createdAt": "2026-09-10T09:48:03+02:00",
    "sentAt": null,
    "deliveredAt": null
  }
}

202 oznacza, że wiadomość została przyjęta do wysyłki, a nie dostarczona. Zapamiętaj data.id: to identyfikator, którym odpytasz status. segmentsCount mówi, na ile segmentów została podzielona treść, a totalCost ile łącznie kosztowała (string dziesiętny z trzema miejscami po przecinku).

Krok 2. Sprawdź status dostarczenia

curl -X GET "https://api.sandbox.paymentic.com/v1_2/messaging/sms/messages/01JZX8K3M9QABCDEF0123456789" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Odpowiedź 200 ma ten sam kształt co przy wysyłce, z aktualnym status oraz czasami sentAt i deliveredAt.

Status	Znaczenie	sentAt	deliveredAt
QUEUED	Wiadomość czeka w kolejce na wysyłkę.	null	null
SENT	Wiadomość została przekazana operatorowi.	czas	null
DELIVERED	Operator potwierdził dostarczenie na telefon odbiorcy.	czas	czas
FAILED	Wysyłka albo dostarczenie nie powiodło się.	zależnie	null

Statusy DELIVERED i FAILED są końcowe. Messaging API nie wysyła webhooków o zmianie statusu wiadomości, więc jeśli potrzebujesz potwierdzenia dostarczenia, odpytaj ten endpoint po chwili od wysyłki.

Pole source mówi, skąd pochodzi wiadomość: API dla wysyłek przez to API, WEB dla wysłanych z panelu, SYSTEM dla wysyłanych automatycznie przez Paymentic.

Polskie znaki i liczba segmentów

Znaki spoza podstawowego alfabetu SMS (np. „ą", „ę", „ł") wymagają kodowania UCS-2, w którym w jednym segmencie mieści się mniej znaków, więc ta sama treść może zająć więcej segmentów i kosztować więcej. Jeśli chcesz wymusić UCS-2 niezależnie od treści, ustaw unicode: true. Faktyczny podział i koszt zobaczysz w segmentsCount i totalCost w odpowiedzi, także w sandboxie, zanim wyślesz wiadomość na produkcji.

Błędy

Kod HTTP	errors[].code	Znaczenie
400	PRICE_NOT_CONFIGURED	Brak cennika dla kraju odbiorcy. Skontaktuj się z opiekunem handlowym.
401	UNAUTHORIZED	Brak lub nieprawidłowy token.
402	INSUFFICIENT_FUNDS	Za mało środków na portfelu SMS. Doładuj saldo i wyślij ponownie.
403	SMS_SERVICE_NOT_ACTIVE	Usługa SMS nie jest włączona dla Twojego konta.
404	MESSAGE_NOT_FOUND	Wiadomość o podanym id nie istnieje.
422	VALIDATION_ERROR	Niepoprawne body, np. numer poza formatem E.164 albo sender dłuższy niż 11 znaków. details.field wskazuje pole.

Pełna referencja: Send a single SMS i Fetch a single SMS by ID.