OK
Planet Pay Merchant API (2.1.15)
Poniższa dokumentacja techniczna (Merchant API) umożliwia wdrożenie wszystkich dostępnych metod płatności oraz funkcjonalności oferowanych przez bramkę płatniczą Planet Pay.
Słownik pojęć:
Secret - poufny klucz przyznawany Merchantowi przez Planet Pay
Merchant - właściciel punktu sprzedaży zarejestrowany w systemie operatora płatności
Agent - podmiot pośredniczący w transakcji (np. operator aplikacji mobilnej)
Klient - klient końcowy (wykonujący i opłacający zamówienie)
MID - merchant identification number - numer merchanta/agenta nadawany przez operatora płatności
SCA - silne uwierzytelnienie klienta; środek wprowadzony przez dyrektywę PSD2 w celu zwiększenia bezpieczeństwa płatności internetowych
Statusy Płatności:
Flow statusów płatności przedstawia się nastepująco NEW - PENDING - COMPLETED/REJECTED - CANCELLED/ERROR/SETTLED
Wywołanie metody payment powoduje zarejestrowanie w systemie płatności ze statusem NEW.
Płatność utrzymuje się w statusie NEW do momentu określenia metody płatności i instrumentu płatniczego.
Płatność zmienia status na PENDING w momencie rozpoczęcia procesowania transakcji (np. inicjalizacja 3DS w przypadku płatności kartą lub komunikacja z systemami PSP w przypadku transakcji BLIK).
Płatność, która zakończyła się powodzeniem, otrzymuje status COMPLETED.
Płatność po rozliczeniu ostatecznie otrzymuje status SETTLED.
Płatność w statusie NEW i PENDING może zostać anulowana. Płatność otrzymuje wtedy status CANCELLED.
Dopuszczalne jest anulowanie płatności w statusie COMPLETED w przypadku braku możliwości zrealizowania zlecenia przez merchanta.
Anulowanie płatności w statusie COMPLETED nie jest możliwe, jeżeli istnieje choć jedno dopełnienie (capture) lub wykonany został zwrot (refund).
Błąd systemowy może spowodować oznaczenie transakcji statusem ERROR.
Notyfikacje
Notyfikacje dotyczące płatności powinny być przyjmowane na dedykowany endpoint /payment niezależnie od typu płatności.
API wspólne dla wszystkich metod płatności. Poszczególne metody i kanały płatności mogą się różnić zakresem pól obowiązkowych. Operator płatności nadaje każdemu zleceniu płatności unikatowy numer paymentId, który może zostać wykorzystany przez merchanta np. do pobrania aktualnego statusu płatności. Status płatności może być również wysłany do merchanta kanałem notyfikacji (powiadomienia asynchroniczne). Wszystkie wywołania API wymagają podania tokenu autoryzacyjnego w nagłówku żądania.
Operations
- Sandboxhttps://api.sandbox.planetpay.pl/v1/ecommerce/payment/{paymentId}/retry
- Produkcjahttps://api.planetpay.pl/v1/ecommerce/payment/{paymentId}/retry
- cURL
- Python
- JS
curl -i -X POST \
'https://api.sandbox.planetpay.pl/v1/ecommerce/payment/{paymentId}/retry' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'Request
W sytuacji gdy płatność nie została dokończona przez klienta z jakiegoś powodu (zagubiony link do płatności) możemy wygenerować nowy link z tym samym paymentId i nowym tokenem JWT typu CLIENT. Wygenerowanie nowego linka jest możliwe wyłącznie jeżeli płatność znajduje się w statusie NEW. Dotyczy wyłącznie kanału PAYWALL. Uwaga: niezrealizowana płatność może zostać automatycznie anulowana po przekroczeniu czasu ważności linka (validTime).
Security
bearerAuth
- Sandboxhttps://api.sandbox.planetpay.pl/v1/ecommerce/payment/{paymentId}/restore
- Produkcjahttps://api.planetpay.pl/v1/ecommerce/payment/{paymentId}/restore
- cURL
- Python
- JS
curl -i -X POST \
'https://api.sandbox.planetpay.pl/v1/ecommerce/payment/{paymentId}/restore' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'Request
Realizacja zwrotu środków do klienta. Muszą zostać spełnione następujące warunki: • oryginalna płatność jest w statusie COMPLETED lub SETTLED • kwota zwrotu (lub suma kwot zwrotów częściowych) dla danej płatności nie przekracza kwoty oryginalnej płatności • merchant zapewnił środki na pokrycie kwoty zwrotu. Każda zarejestrowana operacja zwrotu otrzymuje unikatowy identyfikator refundId.
Security
bearerAuth
- application/json;charset=UTF-8
- application/json
Kwota zwrotu dla zwrotów częściowych; domyślnie zwracana jest pełna kwota (Format: 000.00)
- Sandboxhttps://api.sandbox.planetpay.pl/v1/ecommerce/payment/{paymentId}/refund
- Produkcjahttps://api.planetpay.pl/v1/ecommerce/payment/{paymentId}/refund
- cURL
- Python
- JS
- application/json;charset=UTF-8
- application/json
curl -i -X POST \
'https://api.sandbox.planetpay.pl/v1/ecommerce/payment/{paymentId}/refund' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{
"subpaymentId": "string",
"amount": 0,
"description": "string",
"extRefundId": "string"
}'Dostępna jest tokenizacja kart klienta w oparciu o wewnętrzne mechanizmy bramki ecommmerce (COF) lub tokenizacja w oparciu o usługi organizacji płatniczej Visa VTS/Mastercard SCOF (NETWORK). Proces może być kilkuetapowy, w związku z czym cały flow tokenizacji spina identyfikator o nazwie tokenizerId. Do operacji na tokenie (usunięcie/modyfikacja) należy wykorzystywać identyfikator tokenu (nie tokenizacji).
Operations
System wysyła do merchanta notyfikacje w reakcji na określone zdarzenia systemowe. Notyfikacje wysyłane są jeżeli w parametryzacji merchanta podany został URL API implementującego poniższą specyfikację. System generuje żądania metodą POST. Oczekujemy, że odbiorca zwróci kod HTTP 200 po przyjęciu komunikatu. Wysyłka notyfikacji jest ponawiana w przypadku błędów sieciowych (HTTP 50X). Notyfikacje nie będą ponawiane w przypadku, gdy system nie przyjął komunikatu (HTTP 40X). Notyfikacje zawierają cyfrowy podpis, który wysyłany jest w nagłówku Signature jako wartość hex. Podpis wyliczany jest algorytmem HMAC-SHA256 z wartości wszystkich pól komunikatu (konkatenacja). Do wyliczenia podpisu obowiązuje kolejność pól prezentowana w niniejszej specyfikacji. Tajny klucz dla algorytmu ustawiany jest w parametryzacji merchanta.
Operations