Płatności
Diagram procesu płatności
Poniższy diagram sekwencji przedstawia proces płatności zakończony sukcesem:

Mapa statusów płatności
Na poniższym obrazku przedstawiono wszystkie statusy, jakie może przyjąć płatność, oraz możliwe przejścia między nimi:

| Kod | Opis |
|---|---|
| NEW | Obowiązuje tylko w przypadku płatności bez wybranej metody płatności. Ten status oznacza, że płatność została zaakceptowana przez Paynow i Paynow czeka na wybór metody płatności przez użytkownika. |
| PENDING | Wybrano metodę płatności, a Paynow czeka na dokonanie płatności przez kupującego. Po wybraniu metody płatności, kupujący nie może jej zmienić. |
| CONFIRMED | Płatność została pomyślnie przetworzona przez Paynow, a pieniądze zostały przekazane na konto odbiorcy. |
| REJECTED | Płatność nie została autoryzowana przez kupującego. |
| ERROR | Wystąpił problem podczas procesu płatności |
| EXPIRED | Termin ważności płatności minął i płatność nie jest już możliwa. |
| ABANDONED | Kupujący próbował ponowić płatność ze statusem ERROR lub REJECTED; Nowa płatność ma nowy 'id' i jest powiązana z zamówieniem |
Każda płatność pozostająca w statusie NEW lub PENDING przez 10 dni zostanie automatycznie przeprocesowana na status EXPIRED.
Aby użyć mechanizmu ponawiania płatności dla statusu ABANDONED, opcja w konfiguracji musi być włączona.
Utwórz płatność
Na potrzeby tego przewodnika przyjmiemy założenie, że dane autoryzacyjne to:
- Api-Key =
97a55694-5478-43b5-b406-fb49ebfdd2b5 - Signature-Key =
b305b996-bca5-4404-a0b7-2ccea3d2b64b
Krok 1: Przygotuj wiadomość z żądaniem płatności. W tym przykładzie użyjemy prostej wiadomości zawierającej tylko wymagane pola, które wyglądają następująco:
{
"amount": 45671,
"externalId": "234567898654",
"description": "Test transaction",
"buyer": {
"email": "jan.kowalski@melements.pl"
}
}
Podana kwota powinna być podana w najmniejszej jednostce waluty płatności (grosz w przypadku PLN). Oznacza to, że
powyższe żądanie definiuje płatność na kwotę 456,71 PLN.
Każde żądanie płatności musi zawierać „externalId”, który jest przypisywany przez Sprzedawcę podczas tworzenia. Pozwala to na zapewnienie unikalności płatności po stronie Sprzedawcy.
Pole opisu może zawierać dowolny tekst, który pomaga zidentyfikować płatność.
Pole kupującego musi zawierać co najmniej adres e-mail Kupującego dokonującego płatności i może zawierać inne
pola opisujące Kupującego.
Aby uzyskać pełną specyfikację dla żądania płatności, przedź do API reference.
Aby móc korzystać z niektórych metod płatności (np. PayPo), pole Kupujący musi również zawierać pole adresu, a pola rozliczeniowe i do wysyłki muszą zawierać co najmniej ulicę, kod pocztowy i miasto kupującego, jak pokazano tutaj.
Krok 2: Dołącz nagłówek Api-Key z wartością Api-Key, którą znajdziesz w Panelu Merchanta.
Krok 3: Oblicz podpis i dołącz go jako nagłówek Signature. Dla podanego
przykładu prawidłowy podpis to ZBlr1Eg2n28HHOkRkh1LyOD60xl0MQguYHDgJRy7Hps=
Jeśli próbujesz obliczyć podpis z przykładu w swoim kodzie i otrzymujesz inny wynik, upewnij się, że Twoja wiadomość JSON jest sformatowana w ten sam sposób, co wiadomość w przykładzie, tj. z wcięciem czterech spacji i bez znaku nowej linii na końcu.
Krok 4: Wygeneruj losowy ciąg o maksymalnej długości 45 znaków dla nagłówka Idempotency-Key.
Krok 5: Wykonaj żądanie POST z przygotowaną wiadomością na endpoint żądania płatności
curl --request POST 'https://api.sandbox.paynow.pl/v3/payments' \
-H 'Content-Type: application/json' \
-H 'Api-Key: 97a55694-5478-43b5-b406-fb49ebfdd2b5' \
-H 'Signature: lGOrwYvoRYwWcKSEtE/YDn8go1w/i5dj8Rv/ytIvXVE=' \
-H 'Idempotency-Key: 59c6dd26-f905-487b-96c9-fd1d2bd76885' \
--data-raw '{
"amount": 45671,
"externalId": "234567898654",
"description": "Test transaction",
"buyer": {
"email": "jan.kowalski@melements.pl"
}
}'
Pamiętaj, że żądanie musi zawierać nagłówki Host i Accept jak opisano tutaj. Nie są one wymienione powyżej, ponieważ polecenie curl domyślnie je zawiera.
Krok 6: Obsłuż zwróconą odpowiedź:
{
"redirectUrl": "https://paywall.sandbox.paynow.pl/NOLV-8F9-08K-WGD?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwb3NJZCI6IjEwMDAiLCJwYXltZW50SWQiOiJOT0xWLThGOS0wOEstV0dEIiwiZXhwIjoxNTU0ODEzMTY4fQ.71TLjI8U8p0c_hhC1Nj3cAPU3mtzYW4ylGo8qVeB18o",
"paymentId": "NOLV-8F9-08K-WGD",
"status": "NEW"
}
Odpowiedź zawiera adres URL, do którego Kupujący powinien zostać przekierowany, identyfikator płatności wygenerowany przez Paynow i
bieżący status płatności.
Zwrócony paymentId powinien zostać zapisany przez Sprzedawcę w celu dalszego wykorzystania.
Krok 7: Przekieruj Kupującego na adres podany w odpowiedzi. Kupujący zostanie przekierowany do paywall Paynow,
który przeprowadzi go przez proces płatności. Po zakończeniu płatności Kupujący zostanie przekierowany na adres URL
podany przez Sprzedawcę podczas konfiguracji jako return-url.
return-url będzie zawierał dodatkowe parametry adresu URL: paymentId oraz paymentStatus. Aby zobaczyć więcej szczegółów, zapoznaj się z diagramem procesu płatności
Krok 8: Podczas procesu płatności Paynow dostarcza powiadomienia o bieżącym statusie płatności za każdym razem, gdy status zostanie zmieniony.
W przypadku nieudanej płatności zostanie dostarczona podobna wiadomość zawierająca status REJECTED lub ERROR
zamiast w zależności od przyczyny niepowodzenia.
Podnoszenie płatności (ponawianie)
Paynow oferuje funkcję podnoszenia płatności dla płatności o statusie PENDING, REJECTED lub ERROR. Podnoszenie jest dostępne
dla wszystkich integracji. Aby obsługiwać podnoszenie płatności, należy obsłużyć status ABANDONED
z diagramu procesu płatności. Wszystkie płatności są powiązane przez externalId z początkowej
płatności.
Jak to działa, przykład:
- Wyślij żądanie tworzenia płatności .
- Odrzuć płatność.
- Na stronie statusu użyj opcji
Ponów płatność. Paynow utworzy nową płatność z nowympaymentId. - Autoryzuj płatność.
- Sprawdź status płatności lub
zaakceptuj powiadomienie z nowym
paymentId.externalIdbędzie takie samo jak dla pierwszej początkowej płatności.
Czas ważności płatności
Opcjonalne pole validityTime w żądaniu utworzenia płatności określa w sekundach czas, przez jaki płatność może zostać zrealizowana. Po jego upływie niezakończona płatność przechodzi do statusu EXPIRED.
Jeśli pole validityTime zostanie pominięte, przyjmowana jest wartość domyślna. Minimalna wartość wynosi 60 s, natomiast wartość domyślna i maksymalna zależą od wybranej metody płatności (paymentMethodId):
Metoda płatności (paymentMethodId) | Wartość minimalna | Warto ść maksymalna i domyślna |
|---|---|---|
Standardowa płatność (pozostałe metody lub brak paymentMethodId) | 60 s (1 min) | 864000 s (10 dni) |
Zapis karty i subskrypcje (2202) | 60 s (1 min) | 7200 s (2 godz.) |
Przekazanie wartości spoza dozwolonego zakresu dla danej metody skutkuje błędem walidacji 400 Bad Request (VALIDATION_ERROR).
Wygaszanie płatności
Jeśli płatność nie powinna już zostać opłacona (np. zamówienie zostało anulowane), możesz ją wygasić przed upływem jej
terminu ważności. Wygaszona płatność otrzymuje status EXPIRED, a Kupujący nie może jej już opłacić. Więcej informacji
znajdziesz w API reference.
Wygasić można płatność w statusie NEW, PENDING, REJECTED lub ERROR. Płatności w statusie CONFIRMED i
ABANDONED nie można wygasić. Płatność, która ma już status EXPIRED, pozostaje bez zmian.
Po wygaszeniu płatności:
- Paynow wysyła powiadomienie ze statusem
EXPIRED, - Kupujący, który otworzy link do płatności, zostanie przekierowany na stronę statusu płatności.
Płatności utworzone w wyniku podnoszenia
Jeśli Kupujący skorzystał z podnoszenia płatności, do jednego zamówienia może istnieć kilka
płatności. Flaga expireRecoveredPayments decyduje, które z nich zostaną wygaszone:
expireRecoveredPayments | Efekt |
|---|---|
false | Wygaszona zostaje tylko płatność o podanym paymentId. |
true | Wygaszona zostaje podana płatność lub ostatnia płatność utworzona w wyniku podnoszenia płatności o podanym paymentId, jeśli jest w statusie NEW, PENDING, REJECTED lub ERROR. |
Wywołanie
Na potrzeby tego przewodnika przyjmiemy założenie, że Api-Key to 97a55694-5478-43b5-b406-fb49ebfdd2b5, a paymentId
to NOLV-8F9-08K-WGD.
Krok 1: Przygotuj wiadomość z żądaniem wygaszenia. Pole expireRecoveredPayments jest wymagane:
{
"expireRecoveredPayments": false
}
Krok 2: Dołącz nagłówek Api-Key, oblicz podpis i dołącz go jako
nagłówek Signature, a następnie wygeneruj Idempotency-Key.
Krok 3: Wykonaj żądanie PATCH z przygotowaną wiadomością:
curl --request PATCH 'https://api.sandbox.paynow.pl/v3/payments/NOLV-8F9-08K-WGD/expire' \
-H 'Content-Type: application/json' \
-H 'Api-Key: 97a55694-5478-43b5-b406-fb49ebfdd2b5' \
-H 'Signature: NK6TMwZIA7CE1ncGVwvC5PB61mhMcMIE2WqwtawGCgk=' \
-H 'Idempotency-Key: 59c6dd26-f905-487b-96c9-fd1d2bd76885' \
--data-raw '{
"expireRecoveredPayments": false
}'
Krok 4: Obsłuż odpowiedź:
Status płatności możesz w dowolnym momencie sprawdzić za pomocą endpointu status płatności lub poczekać na powiadomienie.
Pozycje zamówienia (orderItems)
Opcjonalna tablica orderItems w żądaniu utworzenia płatności (POST /v3/payments) pozwala przekazać listę pozycji wchodzących w skład zamówienia.
Pola obiektu OrderItem
| Pole | Typ | Ograniczenia / wartości | Wymagalność |
|---|---|---|---|
name | string | niepuste, maks. 120 znaków | Wymagane (w każdym elemencie niepustej tablicy orderItems) |
category | string | niepuste, maks. 1000 znaków | Wymagane (w każdym elemencie niepustej tablicy orderItems) |
quantity | integer (int64) | >= 1 | Wymagane (w każdym elemencie niepustej tablicy orderItems) |
price | integer (int64) | >= 0; cena jednostkowa w najmniejszej jednostce waluty (np. grosz dla PLN; domyślnie 0) | Opcjonalne |
producer | string | maks. 120 znaków | Opcjonalne |
type | string (enum) | BUNDLE, DIGITAL, DIGITAL_SERVICE, DONATION, GIFT_CARD, PHYSICAL, SERVICE | Wymagane dla paymentMethodId: 2202 (gdy orderItems niepuste); opcjonalne dla pozostałych metod |
frequency | string (enum) | ANNUAL, MONTHLY, QUARTERLY, WEEKLY | Wymagane dla paymentMethodId: 2202 (gdy orderItems niepuste); opcjonalne dla pozostałych metod |
Zasady walidacji
Walidacja tablicy orderItems zależy od tego, czy została przekazana, oraz od wybranej metody płatności (paymentMethodId):
- Brak lub pusta tablica (
null/[]) – samo poleorderItemsjest opcjonalne dla wszystkich metod płatności (w tym2202); gdy zostanie pominięte lub jest pustą tablicą, walidacja pozycji nie jest uruchamiana. - Reguły bazowe (zawsze, gdy
orderItemsjest niepuste – dla każdej metody płatności, w tym2202):- żaden element tablicy
orderItemsnie może mieć wartościnull, - w każdym elemencie wymagane są pola
name(niepuste, maks.120znaków),category(niepuste, maks.1000znaków) orazquantity(>= 1), - jeśli przekazano
producer, jego długość nie może przekroczyć120znaków.
- żaden element tablicy
- Dodatkowe reguły dla płatności cyklicznych kartą (
paymentMethodId: 2202, CIT i MIT):- gdy
orderItemsjest niepuste ipaymentMethodId == 2202, oprócz reguł bazowych w każdym elemencie wymagane są również polatypeorazfrequency(nie mogą mieć wartościnull), - dla pozostałych metod płatności (lub gdy
paymentMethodIdpominięto) polatypeorazfrequencysą opcjonalne – można przekazać oba, tylko jedno z nich albo pominąć oba.
- gdy
- Format typów i wartości słownikowych (zawsze, niezależnie od
paymentMethodId):- jeśli przekazano
typelubfrequency, wartość musi pochodzić z dozwolonego słownika i być zapisana wielkimi literami (wielkość liter ma znaczenie; wartości liczbowe oraz spoza listy są odrzucane), - pola
quantityorazpricemuszą być nieujemnymi liczbami całkowitymi (int64).
- jeśli przekazano
Naruszenie którejkolwiek z powyższych reguł skutkuje odpowiedzią 400 Bad Request z kodem VALIDATION_ERROR (np. orderItems[0].name: name cannot be blank, orderItems[0].type: type cannot be null lub type: invalid field value (...)).
"orderItems": [
{
"name": "Subskrypcja miesięczna - Plan PRO",
"producer": "Nazwa Twojej Firmy",
"category": "Subskrypcja",
"quantity": 1,
"price": 4900,
"type": "DIGITAL_SERVICE",
"frequency": "MONTHLY"
}
]