# 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. ## Aktualizacja danych instrumentu płatniczego - [PUT /v1/ecommerce/payment/{paymentId}/instrument](https://planetayapi.redocly.app/api/platnosci/fillpaymentinstrument.md): Metoda pozwala uzupełnić dane instrumentu płatniczego lub urządzenia bazując na wygenerowanym wcześniej paymentId. Umożliwia rozbicie flow płatności na kilka etapów (np. rejestracja płatności przez merchanta, uzupełnienie danych instrumentu płatniczego, uzupełnienie danych urządzenia). ## Aktualizacja atrybutu instrumentu płatniczego - [PATCH /v1/ecommerce/payment/{paymentId}/instrument](https://planetayapi.redocly.app/api/platnosci/fillpaymentinstrumentcvv.md): W przypadku gdy wymagane jest dosłanie pojedynczego atrybutu instrumentu (np. kod CVV) można wykorzystać metodę ## Zlecenie płatności - [POST /v1/ecommerce/payment](https://planetayapi.redocly.app/api/platnosci/createpayment.md): Merchant wywołuje tę metodę w celu zainicjowania płatności. System zwraca status potwierdzający przyjęcie płatności do realizacji. Jeżeli do przeprocesowania płatności wymagane są dodatkowe dane lub wymagana jest autoryzacja płatności przez klienta, taka informacja zwracana jest w odpowiedzi (np. dane do przeprowadzenia ACS challenge w przypadku transakcji kartowych wymagających SCA). W przypadku kanału PAYWALL lub metody PBL zwraca adres URL, na który należy przekierować użytkownika, aby kontynuować flow. Metoda nie zwraca końcowego statusu płatności, chyba że błąd wystąpił na wczesnym etapie weryfikacji karty (np. nieobsługiwany BIN) lub wystąpił inny problem natury konfiguracyjnej (np. nieobsługiwany kanał płatności dla merchanta). Aktualny status zawsze można pobrać korzystając z metody GET /payment. Informacja o płatności dostępna jest poprzez Merchant API przez 3 miesiące. Status propagowany jest też asynchronicznie kanałem notyfikacji. ## Wycofanie transakcji - [POST /v1/ecommerce/payment/{paymentId}/transactions/{transId}/cancel](https://planetayapi.redocly.app/api/platnosci/transactioncancel.md): Metoda umożliwia wycofanie transakcji. W tej chwili obsługiwany jest wyłącznie typ ADJUSTMENT. ## Kontynuacja odrzuconej płatności - [POST /v1/ecommerce/payment/{paymentId}/retry](https://planetayapi.redocly.app/api/platnosci/retrypayment.md): Awaryjna metoda rejestrująca nową płatność na podstawie poprzedniej, która zakończyła się niepowodzeniem (status REJECTED/CANCELLED/ERROR). Dla płatności rejestrowany jest nowy identyfikator paymentId. ## Generowanie nowego linku do płatności - [POST /v1/ecommerce/payment/{paymentId}/restore](https://planetayapi.redocly.app/api/platnosci/restorepayment.md): 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). ## Realizacja zwrotu środkow dla przeprocesowanych płatności - [POST /v1/ecommerce/payment/{paymentId}/refund](https://planetayapi.redocly.app/api/platnosci/refundpayment.md): 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. ## Zlecenie dopełnienia - [POST /v1/ecommerce/payment/{paymentId}/capture](https://planetayapi.redocly.app/api/platnosci/capture.md): Preautoryzacja (transKind=PREAUTH) skutkuje blokadą środków i wymaga wykonania operacji dopełnienia w celu obciążenia klienta. Blokada środków domyślnie zakładana jest na 30 dni (wartość ta może być ustawiona niżej poprzez parametry konfiguracyjne merchanta). Dopełnienie zatwierdza ostateczną kwotę płatności i kieruje ją do rozliczenia (do tego czasu transakcja jest utrzymywana w statusie COMPLETED). Dopełnienie może być zrealizowane na kwotę równą lub mniejszą względem preautoryzacji. ## Anulowanie płatności - [POST /v1/ecommerce/payment/{paymentId}/cancel](https://planetayapi.redocly.app/api/platnosci/cancelpayment.md): Płatność w statusie NEW i PENDING może zostać anulowana. Płatność otrzymuje status CANCELLED. Możliwe jest w pewnych sytuacjach anulowanie płatności w statusie COMPLETED, co skutkuje odwróceniem oryginalnej transakcji (reversal) bez ostatecznego skutku finansowego dla klienta. W szczególności można anulować preautoryzację, co skutkuje zwolnieniem blokady środków. ## Okeślenie organizacji płatniczej i wersji protokołu (dla flow mobilnego). - [POST /v1/ecommerce/payment/{paymentId}/binInfo](https://planetayapi.redocly.app/api/platnosci/getpaymentbininfobypaymentid.md): Dodatkowy krok dla flow mobilnego do określenia organizacji płatniczej i używanej wersji protokołu 3DSecure. Wersja protokołu ustalana jest jako najwyższa możliwa z zakresów obsługiwanych przez komponenty: SDK, ACS, 3DS i DS. Drugi wariant metody na potrzeby wywołań z payment SDK zakłada, że płatność została już wcześniej zainicjalizowana (znamy instrument) ## Zlecenie korekty kwoty preautoryzacji - [POST /v1/ecommerce/payment/{paymentId}/adjustment](https://planetayapi.redocly.app/api/platnosci/adjustment.md): Korekta pozwala na modyfikację kwoty preautoryzacji. Operację można wykonać wielokrotnie, dopóki nie zostanie wykonane dopełnienie (capture). ## Wyszukiwanie płatności po zewnetrznych identyfikatorach - [POST /v1/ecommerce/payment/search](https://planetayapi.redocly.app/api/platnosci/searchpayment.md): Wyszukiwanie płatności po zewnętrznych identyfikatorach. Przeszukiwane są wyłącznie płatności związane z merchantem, dla którego wydano token dostępowy. Zwracana jest lista identyfikatorów paymentId. Tylko jedna z płatnośćci może być zakończona sukcesem. Powinna być zwracana na pierwszej pozycji. ## Okeślenie organizacji płatniczej i wersji protokołu (dla flow mobilnego). - [POST /v1/ecommerce/payment/binInfo](https://planetayapi.redocly.app/api/platnosci/getpaymentbininfo.md): Dodatkowy krok dla flow mobilnego do określenia organizacji płatniczej i używanej wersji protokołu 3DSecure. Wersja protokołu uStałana jest jako najwyższa możliwa z zakresów obsługiwanych przez komponenty: SDK, ACS, 3DS i DS. ## Pobieranie informacji o płatności - [GET /v1/ecommerce/payment/{paymentId}](https://planetayapi.redocly.app/api/platnosci/getpaymentinfo.md): Metoda służy do pobrania podstawowych informacji o płatności. Metoda nigdy nie zwraca danych wrażliwych związanych z płatnością. Podstawowy przypadek użycia dla metody to inicjalizacja bramki web (channel=PAYWALL), która posiada początkowo wyłącznie informacje o paymentId i musi pobrać brakujące informacje w celu prezentacji klientowi. ## Aktualizacja danych instrumentu płatniczego oraz urządzenia - [PATCH /v1/ecommerce/payment/{paymentId}](https://planetayapi.redocly.app/api/platnosci/fillpaymentinstrumentanddevice.md): Metoda pozwala uzupełnić dane instrumentu płatniczego lub urządzenia bazując na wygenerowanym wcześniej paymentId. Umożliwia rozbicie flow płatności na kilka etapów (np. rejestracja płatności przez merchanta, uzupełnienie danych instrumentu płatniczego, uzupełnienie danych urządzenia). ## Lista transakcji w ramach płatności - [GET /v1/ecommerce/payment/{paymentId}/transactions](https://planetayapi.redocly.app/api/platnosci/transactions.md) ## Pobieranie tokenu kartowego - [GET /v1/ecommerce/payment/{paymentId}/tokenizer](https://planetayapi.redocly.app/api/platnosci/getpaymenttokeninfo.md): Pobranie danych tokenu na podstawie identyfikatora procesu tokenizacji. Merchant powinien zapisać nr tokenu i posługiwać się nim w dalszej komunikacji z API. ## Lista subtransakcji przy płatnościach z MARKETPLACE - [GET /v1/ecommerce/payment/{paymentId}/subpayments](https://planetayapi.redocly.app/api/platnosci/subpayments.md) ## Pobieranie statusu płatności - [GET /v1/ecommerce/payment/{paymentId}/status](https://planetayapi.redocly.app/api/platnosci/getpaymentstatus.md): Aktualny status płatności można sprawdzić używając identyfikatora płatności (paymentId). ## Pobieranie informacji o zwrotach - [GET /v1/ecommerce/payment/{paymentId}/refunds](https://planetayapi.redocly.app/api/platnosci/getrefundsinfo.md): Informacja o statusie zwrotów dla płatności. ## Pobieranie informacji o zwrotach - [GET /v1/ecommerce/payment/{paymentId}/refund/{refundId}](https://planetayapi.redocly.app/api/platnosci/getrefundinfo.md): Informacja o statusie wybranego zwrotu. ## Pobieranie danych ACS challenge - [GET /v1/ecommerce/payment/{paymentId}/acsData](https://planetayapi.redocly.app/api/platnosci/getacsdata.md): Metoda służy do zwrócenia danych potrzebnych do przeprowadzenia SCA (ACS challenge). Zwykle dane te zwracane są w odpowiedzi na żądanie inicjujące płatność, ale możliwe jest, że konieczność przeprowadzenia SCA zostanie zgłoszona później, podczas odpytania o status płatności. ## Pobieranie dostępnego salda do zwrotów - [GET /v1/ecommerce/payment/refunds/balance](https://planetayapi.redocly.app/api/platnosci/refundsbalance.md): Informacja o dostępnym saldzie merchanta do wykonania zwrotu ## Pobranie metod płatności dla merchanta - [GET /v1/ecommerce/payment/methods](https://planetayapi.redocly.app/api/platnosci/getpaymentmethods.md): Lista aktywowanych dla merchanta metod płatności. Przydatna, gdy klient ma możliwość wyboru metody płatności na poźniejszym etapie (metoda nieokreślona podczas rejestracji płatności). Identyfikator merchanta i kanał płatności pochodzi z tokenu autoryzacyjnego (JWT). ## Weryfikacja karty - [POST /v1/ecommerce/payment/cardInfo](https://planetayapi.redocly.app/api/platnosci/cardinfo.md): Metoda zwraca podstawowe informacje o karcie. Umożliwia sprawdzenie karty odbiorcy przed wykonaniem właściwej operacji transferu środkow. ## Pobranie metod płatności dla merchanta - [GET /v1/ecommerce/payment/{paymentId}/methods](https://planetayapi.redocly.app/api/platnosci/getspecifiedpaymentmethods.md): Lista aktywowanych dla merchanta metod płatności. Przydatna, gdy klient ma możliwość wyboru metody płatności na poźniejszym etapie (metoda nieokreślona podczas rejestracji płatności). Identyfikator merchanta i kanał płatności pochodzi z tokenu autoryzacyjnego (JWT). ## Pobranie opcjonalnych parametrów metody płatności - [GET /v1/ecommerce/payment/methods/PBL](https://planetayapi.redocly.app/api/platnosci/paymentmethodoptionpbl.md): Niektóre metody płatności posiadają osobną listę opcji. W przypadku przelewów (PBL) otrzymamy liste bankow. ## Pobranie opcjonalnych parametrów metody płatności - [GET /v1/ecommerce/payment/methods/CARD](https://planetayapi.redocly.app/api/platnosci/paymentmethodoptioncard.md): Niektóre metody płatności posiadają osobną listę opcji. W przypadku przelewów (PBL) otrzymamy liste bankow. ## Pobranie opcjonalnych parametrów metody płatności - [GET /v1/ecommerce/payment/methods/C2P](https://planetayapi.redocly.app/api/platnosci/paymentmethodoptionc2p.md): Niektóre metody płatności posiadają osobną listę opcji. W przypadku przelewów (PBL) otrzymamy liste bankow.