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

Wyszukiwanie płatności po zewnetrznych identyfikatorach

Request

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.

Security
bearerAuth
Body
required
extOrderIdstringrequired

Identyfikator zamowienia z systemu merchanta

merchantobject or null(MerchantInfo)

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

agentobject or null(MerchantInfo)

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

curl -i -X POST \
  https://api.sandbox.planetpay.pl/v1/ecommerce/payment/search \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -d '{
    "extOrderId": "string",
    "merchant": {
      "merchantId": "string",
      "merchantName": "string",
      "name": "string",
      "mcc": "stri",
      "url": "string",
      "redirectURL": "string",
      "terminalId": "string",
      "location": {
        "street": "string",
        "postal": "string",
        "state": "12",
        "city": "string",
        "country": "POL",
        "countryOfOrigin": "POL"
      },
      "taxId": "string",
      "acsNotificationURL": "string",
      "amexMerchantId": "string",
      "dpaId": "string",
      "organizationId": "string"
    },
    "agent": {
      "merchantId": "string",
      "merchantName": "string",
      "name": "string",
      "mcc": "stri",
      "url": "string",
      "redirectURL": "string",
      "terminalId": "string",
      "location": {
        "street": "string",
        "postal": "string",
        "state": "12",
        "city": "string",
        "country": "POL",
        "countryOfOrigin": "POL"
      },
      "taxId": "string",
      "acsNotificationURL": "string",
      "amexMerchantId": "string",
      "dpaId": "string",
      "organizationId": "string"
    }
  }'

Responses

OK

Body*/*
paymentsArray of stringsunique

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

Okeślenie organizacji płatniczej i wersji protokołu (dla flow mobilnego).

Request

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.

Security
bearerAuth
Body
required
channelstringrequired

Kanał operacji

Enum"PAYWALL""MOBILE""WEBAPI""EBOK""CSS"
sdkStartProtocolstringrequired

Najstarsza wersja protokołu wspierana przez SDK

sdkEndProtocolstringrequired

Najnowsza wersja protokołu wspierana przez SDK

instrumentobject(InstrumentInfo)required

Szczegółowe dane requestu

instrument.​typestringrequired

Typ instrumentu płatniczego

Enum"COF""CARD""BLIK""BLIK_CODE""BLIK_UID""BLIK_PAYID""GPAY""APAY""PBL""SCOF"
instrument.​instrumentNostring or null

Nr instrumentu płatniczego (np. tokenu lub karty) (wymagany dla type = CARD/COF)

instrument.​encInstrumentNostring or null

Zaszyfrowany nr instrumentu płatniczego

instrument.​instrumentRefstring or null

Identyfikator instrumentu płatnicznego w zewnętrznym systemie (wymagany dla type = SCOF/VTS)

instrument.​tokenstring or null

Dane tokenu zwracane przez API APAY/GPAY (base64 encoded) (wymagany dla type = APAY/GPAY)

instrument.​expDatestring or null

Data ważności (Format: YYYYMM) (wymagany dla type = CARD)

Example: "202101"
instrument.​encExpDatestring or null

Zaszyfrowana data ważności

instrument.​cvvstring or null

Kod zabezpieczający (wymagany dla type = CARD)

instrument.​encCvvstring or null

Zaszyfrowany kod zabezpieczający

instrument.​codestring or null= 6 characters

Jednorazowy kod płatności BLIK (wymagany dla type = BLIK_CODE)

instrument.​aliasstring or null

Alias użytkownika BLIK dla płatności OneClick lub cyklicznych (wymagany dla type = BLIK_UID/BLIK_PAYID)

instrument.​appstring or null

Identyfikator konta mobilnego BLIK (w przypadku niejednoznaczności aliasu)

instrument.​providerstring or null

Identyfikator pośrednika płatności (może być wybrany automatycznie na podstawie konfiguracji merchanta)

Enum"BM""PA""PU"
instrument.​bankstring or null

Nazwa banku (wymagany dla type = PBL)

instrument.​bankIdinteger or null(int32)

Identyfikator banku (w systemie operatora PBL) (wymagany dla type = PBL)

instrument.​payloadstring or null

Payload otrzymany z SDK na potrzeby płatności Click2Pay

instrument.​cardMaskstring or null

Maska karty otrzymana z PayU na potrzeby płatności tokenem kartowym

curl -i -X POST \
  https://api.sandbox.planetpay.pl/v1/ecommerce/payment/binInfo \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -d '{
    "channel": "PAYWALL",
    "sdkStartProtocol": "string",
    "sdkEndProtocol": "string",
    "instrument": {
      "type": "COF",
      "instrumentNo": "string",
      "encInstrumentNo": "string",
      "instrumentRef": "string",
      "token": "string",
      "expDate": "202101",
      "encExpDate": "string",
      "cvv": "string",
      "encCvv": "string",
      "code": "string",
      "alias": "string",
      "app": "string",
      "provider": "BM",
      "bank": "string",
      "bankId": 0,
      "payload": "string",
      "cardMask": "string"
    }
  }'

Responses

OK

Body*/*
cardGroupstring
Enum"VISA""MC""AMEX"
dsRefNumberstring
tdsServerTxnIdstring
tdsProtocolstring
tdsMethodURLstring

Pobieranie informacji o płatności

Request

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.

Security
bearerAuth
Path
paymentIdstringrequired

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

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

Responses

OK

Body*/*
paymentIdstring

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

statusstring

Aktualny status płatności

merchantobject or null(MerchantInfo)

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

customerobject(CustomerInfo)

Dane właściciela karty

orderobject(OrderInfo)

Dane zamówienia podlegajacego płatności

rejectCodestring

Powód odrzucenia (w przypadku niepowodzenia)

rejectInfostring

Dodatkowe informacje o powodzie odrzucenia płatności

optionsobject(PaymentOptionsInfoResponse)

Inne parametry sterujace

channelstring

Kanał płatności

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

Metoda płatności

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

Aktualna kwota płatności, która może być modyfikowana przez adjustment lub cancel. W standardowym przypadku jest równa kwocie z sekcji order (ta oryginalna kwota nigdy nie ulega zmianie)

captureAmountnumber

Zatwierdzona kwota płatności (dotyczy preautoryzacji). Dla regularnych płatności równa kwocie z sekcji order, dla preautorycji aktualizowana po każdej akcji capture

redirectURLstring

Adres URL dla kontynuacji flow webowego

forceScaboolean

Flaga wymuszenia silnego uwierzytelnienia klienta (SCA)

recipientobject(RecipientVerificationInfo)

Informacje o weryfikacji odbiorcy (w przypadku transferu srodkow P2P)

reattemptstring

Informacja o ograniczeniach w wykonywaniu płatności. Dopuszczalne wartosci:NEVER - nie wysyłaj więcej komunikatow na ten numer karty; NEVER_RECURRING - nie wysyłaj wiecej komunikatow dla płatności powtarzalnej; LATER - sprobuj póź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