Skip to content

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
Status 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.

Download OpenAPI description
api.json
api.yaml
Languages
Servers
Sandbox
https://api.sandbox.planetpay.pl
Produkcja
https://api.planetpay.pl

Uwierzytelnienie

Wysłanie metody uwierzytelniającej i pobranie tokenu JWT jest wymagane do poprawnego procesowania płatności przez bramkę PlanetPay

Operations

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

Zlecenie płatności

Request

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.

Security
bearerAuth
Body
required
channelstringrequired

Kanał operacji

Enum"PAYWALL""MOBILE""WEBAPI""EBOK""CSS"
instrumentobject(InstrumentInfo)

Szczegółowe dane requestu

merchantobject or null(MerchantInfo)

Dane merchanta pośredniczącego (operator aplikacji mobilnej)

customerobject(CustomerInfo)

Dane właściciela karty

deviceobject or null(DeviceInfo)

Dane urządzenia z którego wykonywana jest operacja (przeglądarka www lub urządzenie mobilne) (wymagane dla channel = PAYWALL/WEBAPI)

agentobject or null(MerchantInfo)

Dane merchanta pośredniczącego (operator aplikacji mobilnej)

optionsobject or null(PaymentOptions)

Inne parametry sterujące

methodstringrequired

Metoda płatności

orderobject(OrderInfo)

Dane zamówienia podlegajacego płatności

recipientobject or null(RecipientInfo)

Odbiorca środkow dla transakcji typu ACCT_FUNDING (wymagane dla transKind = ACCT_FUNDING)

consentsstring

Zgody marketingowe

preAuthRequestboolean
initialRecurringForZeroAmountboolean
restorableboolean
curl -i -X POST \
  https://api.sandbox.planetpay.pl/v1/ecommerce/payment \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/jose' \
  -d '[object Object]'

Responses

OK

Body
paymentIdstring

Identyfikator płatności w systemie operatora płatności

subpaymentsArray of objects(SubpaymentResponse)

Lista subtransakcji przy płatnościach z MARKETPLACE

statusstring

Aktualny status płatności

dataRequeststring

Zadanie dodatkowych danych

acsDataobject(AcsData)

Dane potrzebne do wykonania ACS challenge

redirectURLstring

Adres URL dla kontynuacji flow webowego

rejectCodestring

Powód odrzucenia (w przypadku niepowodzenia)

rejectInfostring

Dodatkowe informacje o powodzie odrzucenia Płatności

tokenizerIdstring

Identyfikator systemowy tokenu (służy m.in. do pobrania tokenu)

blikObjectobject(BlikTransactionDto)

Struktura zapytania BLIK

optionsobject(PaymentOptionsInfoResponse)

Inne parametry sterujace

channelstring

Kanal płatności

Enum"PAYWALL""MOBILE""WEBAPI""EBOK""CSS"
methodstring

Metoda płatności

Enum"CARD""PBL""BLIK""GPAY""APAY""UNKNOWN""C2P"
apaySessionstring

Obiekt sesji APAY do inicjalizacji płatności

reattemptstring

Informacja o ograniczeniach w wykonywaniu płatności. Dopuszczalne wartości: NEVER - nie wysyłaj wiecej komunikatów na ten numer karty; NEVER_RECURRING - nie wysyłaj wiecej komunikatów dla płatności powtarzalnej; LATER - spróbuj poźniej

Enum"NEVER""NEVER_RECURRING""LATER"
Response
No response example

Wycofanie transakcji

Request

Metoda umożliwia wycofanie transakcji. W tej chwili obsługiwany jest wyłącznie typ ADJUSTMENT.

Security
bearerAuth
Path
paymentIdstringrequired
transIdstringrequired
curl -i -X POST \
  'https://api.sandbox.planetpay.pl/v1/ecommerce/payment/{paymentId}/transactions/{transId}/cancel' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Body*/*
paymentIdstring

Identyfikator płatności w systemie operatora płatności

transIdstring

Identyfikator systemowy transakcji

statusstring

Aktualny status płatności

rejectCodestring

Powód odrzucenia (w przypadku niepowodzenia)

rejectInfostring

Dodatkowe informacje o powodzie odrzucenia płatności

Kontynuacja odrzuconej płatności

Request

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.

Security
bearerAuth
Path
paymentIdstringrequired

Identyfikator płatności w systemie operatora płatności

curl -i -X POST \
  'https://api.sandbox.planetpay.pl/v1/ecommerce/payment/{paymentId}/retry' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Body*/*
paymentIdstring

Identyfikator płatności w systemie operatora płatności

subpaymentsArray of objects(SubpaymentResponse)

Lista subtransakcji przy płatnościach z MARKETPLACE

statusstring

Aktualny status płatności

dataRequeststring

Zadanie dodatkowych danych

acsDataobject(AcsData)

Dane potrzebne do wykonania ACS challenge

redirectURLstring

Adres URL dla kontynuacji flow webowego

rejectCodestring

Powód odrzucenia (w przypadku niepowodzenia)

rejectInfostring

Dodatkowe informacje o powodzie odrzucenia Płatności

tokenizerIdstring

Identyfikator systemowy tokenu (służy m.in. do pobrania tokenu)

blikObjectobject(BlikTransactionDto)

Struktura zapytania BLIK

optionsobject(PaymentOptionsInfoResponse)

Inne parametry sterujace

channelstring

Kanal płatności

Enum"PAYWALL""MOBILE""WEBAPI""EBOK""CSS"
methodstring

Metoda płatności

Enum"CARD""PBL""BLIK""GPAY""APAY""UNKNOWN""C2P"
apaySessionstring

Obiekt sesji APAY do inicjalizacji płatności

reattemptstring

Informacja o ograniczeniach w wykonywaniu płatności. Dopuszczalne wartości: NEVER - nie wysyłaj wiecej komunikatów na ten numer karty; NEVER_RECURRING - nie wysyłaj wiecej komunikatów dla płatności powtarzalnej; LATER - spróbuj poźniej

Enum"NEVER""NEVER_RECURRING""LATER"

Tokenizacja

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

Notyfikacje

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