Przejdź do głównej zawartości

Płatności

Diagram procesu płatności​

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

business flow image

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:

business flow image

KodOpis
NEWObowią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.
PENDINGWybrano 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ć.
CONFIRMEDPłatność została pomyślnie przetworzona przez Paynow, a pieniądze zostały przekazane na konto odbiorcy.
REJECTEDPłatność nie została autoryzowana przez kupującego.
ERRORWystąpił problem podczas procesu płatności
EXPIREDTermin ważności płatności minął i płatność nie jest już możliwa.
ABANDONEDKupujący próbował ponowić płatność ze statusem ERROR lub REJECTED; Nowa płatność ma nowy 'id' i jest powiązana z zamówieniem
Uwaga

Każda płatność pozostająca w statusie NEW lub PENDING przez 10 dni zostanie automatycznie przeprocesowana na status EXPIRED.

Nie zapomnij

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.

Uwaga

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=

Ważne

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"
}
}'
Uwaga

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:

  1. Wyślij żądanie tworzenia płatności .
  2. Odrzuć płatność.
  3. Na stronie statusu użyj opcji Ponów płatność. Paynow utworzy nową płatność z nowym paymentId.
  4. Autoryzuj płatność.
  5. Sprawdź status płatności lub zaakceptuj powiadomienie z nowym paymentId. externalId bę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ść minimalnaWartość 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:

expireRecoveredPaymentsEfekt
falseWygaszona zostaje tylko płatność o podanym paymentId.
trueWygaszona 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ź:

Uwaga

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​

PoleTypOgraniczenia / wartościWymagalność
namestringniepuste, maks. 120 znakówWymagane (w każdym elemencie niepustej tablicy orderItems)
categorystringniepuste, maks. 1000 znakówWymagane (w każdym elemencie niepustej tablicy orderItems)
quantityinteger (int64)>= 1Wymagane (w każdym elemencie niepustej tablicy orderItems)
priceinteger (int64)>= 0; cena jednostkowa w najmniejszej jednostce waluty (np. grosz dla PLN; domyślnie 0)Opcjonalne
producerstringmaks. 120 znakówOpcjonalne
typestring (enum)BUNDLE, DIGITAL, DIGITAL_SERVICE, DONATION, GIFT_CARD, PHYSICAL, SERVICEWymagane dla paymentMethodId: 2202 (gdy orderItems niepuste); opcjonalne dla pozostałych metod
frequencystring (enum)ANNUAL, MONTHLY, QUARTERLY, WEEKLYWymagane 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):

  1. Brak lub pusta tablica (null / []) – samo pole orderItems jest opcjonalne dla wszystkich metod płatności (w tym 2202); gdy zostanie pominięte lub jest pustą tablicą, walidacja pozycji nie jest uruchamiana.
  2. Reguły bazowe (zawsze, gdy orderItems jest niepuste – dla każdej metody płatności, w tym 2202):
    • żaden element tablicy orderItems nie może mieć wartości null,
    • w każdym elemencie wymagane są pola name (niepuste, maks. 120 znaków), category (niepuste, maks. 1000 znaków) oraz quantity (>= 1),
    • jeśli przekazano producer, jego długość nie może przekroczyć 120 znaków.
  3. Dodatkowe reguły dla płatności cyklicznych kartą (paymentMethodId: 2202, CIT i MIT):
    • gdy orderItems jest niepuste i paymentMethodId == 2202, oprócz reguł bazowych w każdym elemencie wymagane są również pola type oraz frequency (nie mogą mieć wartości null),
    • dla pozostałych metod płatności (lub gdy paymentMethodId pominięto) pola type oraz frequency są opcjonalne – można przekazać oba, tylko jedno z nich albo pominąć oba.
  4. Format typów i wartości słownikowych (zawsze, niezależnie od paymentMethodId):
    • jeśli przekazano type lub frequency, 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 quantity oraz price muszą być nieujemnymi liczbami całkowitymi (int64).

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"
}
]