To jest API V1, które nie jest już utrzymywane

Aby zapoznać się z aktualną dokumentacją, zobacz najnowszą wersję.

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

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), musisz użyć API V3, które umożliwia wysłanie sekcji Kupującego, która zawiera pole adresu z polami rozliczeniowymi i wysyłkowymi zawierającymi ulicę, kod pocztowy i miasto kupującego, jak wskazano 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/v1/payments' \
-H 'Content-Type: application/json' \
-H 'Api-Key: 97a55694-5478-43b5-b406-fb49ebfdd2b5' \
-H 'Signature: ZBlr1Eg2n28HHOkRkh1LyOD60xl0MQguYHDgJRy7Hps=' \
-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.