Utwórz transakcję

Na tej stronie utworzysz transakcję Direct Billing, przekierujesz klienta do płatności i sprawdzisz jej status. Wymagania (token, punkt płatności, limity kwoty) są opisane we Wprowadzeniu.

Krok 1. Utwórz transakcję

curl -X POST "https://api.sandbox.paymentic.com/v1_2/directbilling/points/000cb241/transactions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "12.30",
    "title": "Zamowienie #12345",
    "description": "Dostep premium na 30 dni",
    "externalReferenceId": "order-2026-000123",
    "msisdn": "+48123456789",
    "redirect": {
      "success": "https://example.com/platnosc/sukces",
      "failure": "https://example.com/platnosc/blad"
    }
  }'

Pole	Typ	Wymagane	Opis
amount	string	tak	Kwota w PLN, maks. 2 miejsca po przecinku, od 1.00 do 200.00 i nie wyższa niż maksymalna kwota punktu.
title	string	tak	Tytuł transakcji, od 5 do 32 znaków.
description	string	nie	Opis transakcji, maks. 128 znaków.
externalReferenceId	string	nie	Twój identyfikator, maks. 64 znaki. Wraca w szczegółach transakcji i w webhooku.
msisdn	string	nie	Numer telefonu płatnika w formacie E.164, tylko numery polskie (+48 i 9 cyfr).
redirect.success	string	nie	Adres powrotu klienta po udanej płatności, maks. 255 znaków.
redirect.failure	string	nie	Adres powrotu klienta po nieudanej płatności, maks. 255 znaków.

Odpowiedź 201 Created

{
  "data": {
    "id": "ABCD-123-XYZ-9876",
    "redirectUrl": "https://directbilling.paymentic.com/?transactionId=ABCD-123-XYZ-9876&token=..."
  }
}

Zapamiętaj data.id: to identyfikator, którym odpytasz status i po którym rozpoznasz webhook.

Krok 2. Przekieruj klienta

Przekieruj klienta na data.redirectUrl. Po zakończeniu płatności klient wraca na adres redirect.success albo redirect.failure. Powrót na redirect.success nie jest potwierdzeniem zapłaty: wynik weryfikuj po stronie serwera, z webhooka albo z API.

Krok 3. Sprawdź status transakcji

Wynik dostaniesz w webhooku DIRECTBILLING.TRANSACTION_STATUS_CHANGED. Aktualny stan transakcji możesz też pobrać z API:

curl "https://api.sandbox.paymentic.com/v1_2/directbilling/points/000cb241/transactions/ABCD-123-XYZ-9876" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Odpowiedź 200 OK

{
  "data": {
    "id": "ABCD-123-XYZ-9876",
    "status": "PAID",
    "amount": "12.30",
    "currency": "PLN",
    "commission": "0.50",
    "title": "Zamowienie #12345",
    "description": "Dostep premium na 30 dni",
    "externalReferenceId": "order-2026-000123",
    "msisdn": "+48123456789",
    "mccmnc": 26001,
    "redirect": {
      "success": "https://example.com/platnosc/sukces",
      "failure": "https://example.com/platnosc/blad"
    },
    "paidAt": "2026-09-10T09:49:12+02:00",
    "createdAt": "2026-09-10T09:48:03+02:00",
    "expiresAt": "2026-09-10T10:48:03+02:00"
  }
}

Pole	Opis
status	Status transakcji, zob. niżej.
amount	Kwota transakcji jako string dziesiętny.
currency	Kod waluty ISO 4217.
commission	Prowizja jako string dziesiętny. Może być null.
msisdn	Numer telefonu płatnika w formacie E.164. Może być null.
mccmnc	MCC i MNC operatora sieci komórkowej, który obciążył płatnika. Może być null.
paidAt, createdAt, expiresAt	Daty w formacie ISO 8601. Mogą być null.

Statusy

Status	Znaczenie
CREATED	Transakcja utworzona, np. przez API.
PENDING	Płatnik podał numer telefonu, transakcja jest przetwarzana.
PAID	Transakcja opłacona.
FAILED	Płatność się nie powiodła, np. z powodu braku środków.
EXPIRED	Transakcja wygasła.

Tylko PAID oznacza, że płatność się udała.

Błędy

Kod HTTP	errors[].code	Znaczenie
400	POINT_NOT_ACTIVE	Punkt płatności nie jest aktywny.
404	POINT_NOT_FOUND	Punkt płatności o podanym pointId nie istnieje.
404	TRANSACTION_NOT_FOUND	Transakcja o podanym transactionId nie istnieje (przy pobieraniu szczegółów).
404	PATH_NOT_FOUND	Niepoprawna ścieżka.
415	UNSUPPORTED_MEDIA_TYPE	Body nie jest wysłane jako application/json.
422	VALIDATION_ERROR	Niepoprawne dane, np. kwota poza zakresem albo title krótszy niż 5 znaków. details.field wskazuje pole.

Pełna referencja: Create direct billing transaction i Get transaction details.