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

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

Aktualizacja danych instrumentu płatniczego dla tokenizacji

Request

Metoda pozwala uzupełnić dane instrumentu płatniczego, jeżeli nie zostaly podane wczesniej. Dozwolone jest przesłanie sekcji instrument i device.

Security
bearerAuth
Path
tokenizerIdstringrequired

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

Body
required
typestringrequired

Typ instrumentu płatniczego

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

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

encInstrumentNostring or null

Zaszyfrowany nr instrumentu płatniczego

instrumentRefstring or null

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

tokenstring or null

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

expDatestring or null

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

Example: "202101"
encExpDatestring or null

Zaszyfrowana data ważności

cvvstring or null

Kod zabezpieczający (wymagany dla type = CARD)

encCvvstring or null

Zaszyfrowany kod zabezpieczający

codestring or null= 6 characters

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

aliasstring or null

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

appstring or null

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

providerstring or null

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

Enum"BM""PA""PU"
bankstring or null

Nazwa banku (wymagany dla type = PBL)

bankIdinteger or null(int32)

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

payloadstring or null

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

cardMaskstring or null

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

curl -i -X PUT \
  'https://api.sandbox.planetpay.pl/v1/ecommerce/tokenizer/{tokenizerId}/instrument' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/jose' \
  -d '[object Object]'

Responses

OK

Body*/*
tokenizerIdstring

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

statusstring

Status tokenizacji

dataRequeststring

Zadanie dodatkowych danych

Enum"INSTRUMENT""CARD_CVV""CARD_3DS""CARD_OTP""CAPTURE""BLIK_APP""DEVICE""CUSTOMER""EMAIL""BLIK_CODE"
acsDataobject(AcsData)

Dane potrzebne do wykonania ACS challenge

redirectURLstring

Adres URL dla kontunuacji flow webowego

rejectCodestring

Powód odrzucenia (w przypadku niepowodzenia)

rejectInfostring

Dodatkowe informacje o powodzie odrzucenia

Aktualizacja atrybutu instrumentu płatniczego

Request

Tą metodę można wykorzystać gdy wymagane jest dosłanie pojedynczego atrybutu instrumentu (np. kod CVV)

Security
bearerAuth
Path
tokenizerIdstringrequired

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

Body
required
cvvstring
codestring
appstring
curl -i -X PATCH \
  'https://api.sandbox.planetpay.pl/v1/ecommerce/tokenizer/{tokenizerId}/instrument' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -d '{
    "cvv": "string",
    "code": "string",
    "app": "string"
  }'

Responses

OK

Body*/*
tokenizerIdstring

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

statusstring

Status tokenizacji

dataRequeststring

Zadanie dodatkowych danych

Enum"INSTRUMENT""CARD_CVV""CARD_3DS""CARD_OTP""CAPTURE""BLIK_APP""DEVICE""CUSTOMER""EMAIL""BLIK_CODE"
acsDataobject(AcsData)

Dane potrzebne do wykonania ACS challenge

redirectURLstring

Adres URL dla kontunuacji flow webowego

rejectCodestring

Powód odrzucenia (w przypadku niepowodzenia)

rejectInfostring

Dodatkowe informacje o powodzie odrzucenia

Tokenizacja kart klienta

Request

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.

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

Typ tokenizacji (COF/NETWORK lub DEFAULT jeżeli system sam ma podjać decyzje na podstawie parametryzacji merchanta)

Enum"COF""NETWORK""DEFAULT"
recipientobject(TokenizerRecipientInfo)
curl -i -X POST \
  https://api.sandbox.planetpay.pl/v1/ecommerce/tokenizer \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/jose' \
  -d '[object Object]'

Responses

OK

Body
tokenizerIdstring

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

statusstring

Status tokenizacji

dataRequeststring

Zadanie dodatkowych danych

Enum"INSTRUMENT""CARD_CVV""CARD_3DS""CARD_OTP""CAPTURE""BLIK_APP""DEVICE""CUSTOMER""EMAIL""BLIK_CODE"
acsDataobject(AcsData)

Dane potrzebne do wykonania ACS challenge

redirectURLstring

Adres URL dla kontunuacji flow webowego

rejectCodestring

Powód odrzucenia (w przypadku niepowodzenia)

rejectInfostring

Dodatkowe informacje o powodzie odrzucenia

Response
No response example

Unieważnienie tokenu

Request

Usunięcie tokenu z systemu operatora płatności. Wariant z wykorzystaniem identyfikatora procesu tokenizacji

Security
bearerAuth
Path
tokenizerIdstringrequired

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

Body
reasonstring or null

Powód usunięcia tokenu

Enum"FRAUD""CLIENT""SYSTEM"
curl -i -X POST \
  'https://api.sandbox.planetpay.pl/v1/ecommerce/tokenizer/{tokenizerId}/discard' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -d '{
    "reason": "FRAUD"
  }'

Responses

OK

Body*/*
statusstring

Status tokenizacji

rejectCodestring

Powód odrzucenia (w przypadku niepowodzenia)

rejectInfostring

Dodatkowe informacje o powodzie odrzucenia

Anulowanie tokenizacji

Request

Proces tokenizacji możne zostać przerwany przez klienta. Tokenizacja otrzymuje status CANCELLED.

Security
bearerAuth
Path
tokenizerIdstringrequired

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

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

Responses

OK

Body*/*
tokenizerIdstring

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

statusstring

Status tokenizacji

rejectCodestring

Powód odrzucenia (w przypadku niepowodzenia)

rejectInfostring

Dodatkowe informacje o powodzie odrzucenia

Wyszukanie tokenu

Request

Wyszukiwanie tokenów kartowych po numerze. Wyszukiwanie odbywa się w kontekście merchanta.

Security
bearerAuth
Body
required
methodstring

Typ tokenizacji (COF/NETWORK)

Enum"COF""NETWORK""DEFAULT"
typestring

Typ tokenu (COF/SCOF/VTS)

Enum"COF""SCOF""VTS"
instrumentNostring or null

Nr tokenu kartowego (wymagany dla method = COF)

instrumentRefstring or null

Identyfikator tokenu w zewnetrznym systemie (wymagany dla method = SCOF/VTS)

curl -i -X POST \
  https://api.sandbox.planetpay.pl/v1/ecommerce/tokenizer/search \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -d '{
    "method": "COF",
    "type": "COF",
    "instrumentNo": "string",
    "instrumentRef": "string"
  }'

Responses

OK

Body*/*
typestring

Typ tokenu (aktualnie wyłącznie COF)

instrumentNostring

Token wygenerowany dla klienta

instrumentRefstring

Identyfikator tokenizowanej karty w zewnetrznym systemie

expDatestring

Data ważności tokenu (Format: YYYYMM)

Example: "202101"
cardMaskstring

Maskowany nr karty (na potrzeby wyświetlenia)

cardGroupstring

Organizacja płatnicza (VISA/MC)

Enum"VISA""MC""AMEX"
customerIdstring

Identyfikator klienta użyty w procesie tokenizacji

merchantIdstring

Identyfikator merchanta użyty w procesie tokenizacji

visualURLstring

URL do grafiki z wizerunkiem karty

visualIdstring

Identyfikator wizerunku karty (guid w przypadku VTS)

Unieważnienie tokenu

Request

Usunięcie tokenu z systemu operatora płatności. Wariant wykorzystujący numer tokenu kartowego.

Security
bearerAuth
Body
required
methodstring

Typ tokenizacji (COF/NETWORK)

Enum"COF""NETWORK""DEFAULT"
typestring

Typ tokenu (COF/SCOF/VTS)

Enum"COF""SCOF""VTS"
instrumentNostring or null

Nr tokenu kartowego (wymagany dla method = COF)

instrumentRefstring or null

Identyfikator tokenu w zewnetrznym systemie (wymagany dla method = SCOF/VTS)

reasonstring or null

Powód usuniecia tokenu

Enum"FRAUD""CLIENT""SYSTEM"
curl -i -X POST \
  https://api.sandbox.planetpay.pl/v1/ecommerce/tokenizer/discard \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -d '{
    "method": "COF",
    "type": "COF",
    "instrumentNo": "string",
    "instrumentRef": "string",
    "reason": "FRAUD"
  }'

Responses

OK

Body*/*
statusstring

Status tokenizacji

rejectCodestring

Powód odrzucenia (w przypadku niepowodzenia)

rejectInfostring

Dodatkowe informacje o powodzie odrzucenia

Konwersja tokenu COF na NETWORK

Request

Tokeny z wewnętrznej tokenizacji COF można zmigrować na tokeny NETWORK. Metoda nie usuwa danych oryginalnego tokenu.

Security
bearerAuth
Body
required
methodstringrequired
Value"NETWORK"
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/tokenizer/convert \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -d '{
    "method": "NETWORK",
    "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*/*
typestring

Typ tokenu (aktualnie wylacznie COF)

Enum"COF""CARD""BLIK""BLIK_CODE""BLIK_UID""BLIK_PAYID""GPAY""APAY""PBL""SCOF"
instrumentNostring

Token wygenerowany dla klienta

instrumentRefstring

Identyfikator tokenizowanej karty w zewnetrznym systemie

statusstring

Status tokenizacji

rejectCodestring

Powód odrzucenia (w przypadku niepowodzenia)

rejectInfostring

Dodatkowe informacje o powodzie odrzucenia

Okreś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. 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/tokenizer/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 tokenu kartowego

Request

Pobranie danych tokenu na podstawie identyfikatora procesu tokenizacji. Merchant powinien zapisać nr tokenu i posługiwać się nim w dalszej komunikacji z API.

Security
bearerAuth
Path
tokenizerIdstringrequired

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

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

Responses

OK

Body*/*
tokenizerIdstring

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

typestring

Typ tokenu (aktualnie wyłącznie COF)

Enum"COF""SCOF""VTS"
instrumentNostring

Token wygenerowany dla klienta

instrumentRefstring

Identyfikator tokenizowanej karty w zewnetrznym systemie

statusstring

Status tokenizacji

redirectURLstring

Adres URL dla kontunuacji flow webowego

expDatestring

Data ważności tokenu (Format: YYYYMM)

Example: "202101"
cardMaskstring

Maskowany nr karty (na potrzeby wyświetlenia)

cardGroupstring

Organizacja płatnicza (VISA/MC)

Enum"VISA""MC""AMEX"
rejectCodestring

Powód odrzucenia (w przypadku niepowodzenia)

rejectInfostring

Dodatkowe informacje o powodzie odrzucenia

customerIdstring

Identyfikator klienta użyty w procesie tokenizacji

merchantIdstring

Identyfikator merchanta użyty w procesie tokenizacji

dataRequeststring

Zadanie dodatkowych danych

Enum"INSTRUMENT""CARD_CVV""CARD_3DS""CARD_OTP""CAPTURE""BLIK_APP""DEVICE""CUSTOMER""EMAIL""BLIK_CODE"
visualURLstring

URL do grafiki z wizerunkiem karty

visualIdstring

Identyfikator wizerunku karty (guid w przypadku VTS)

recipientobject(RecipientVerificationInfo)

Informacje o weryfikacji odbiorcy (w przypadku transferu srodkow P2P)

Aktualizacja danych instrumentu płatniczego i urządzenia

Request

Podobna metoda wykorzystywana jest przez paywall API, ale pozwala rownież na przesłanie danych urządzenia z którego klient realizuje płatność. Dozwolone jest przesłanie sekcji instrument i device.

Security
bearerAuth
Path
tokenizerIdstringrequired

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

Body
required
instrumentobject(InstrumentInfo)

Szczegółowe dane requestu

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)

customerobject(CustomerInfo)

Dane właściciela karty

consentsstring

Zgody marketingowe

languagestring or null

Preferowana wersja jezykowa (kod ISO np. pl)

curl -i -X PATCH \
  'https://api.sandbox.planetpay.pl/v1/ecommerce/tokenizer/{tokenizerId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/jose' \
  -d '[object Object]'

Responses

OK

Body*/*
tokenizerIdstring

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

statusstring

Status tokenizacji

dataRequeststring

Zadanie dodatkowych danych

Enum"INSTRUMENT""CARD_CVV""CARD_3DS""CARD_OTP""CAPTURE""BLIK_APP""DEVICE""CUSTOMER""EMAIL""BLIK_CODE"
acsDataobject(AcsData)

Dane potrzebne do wykonania ACS challenge

redirectURLstring

Adres URL dla kontunuacji flow webowego

rejectCodestring

Powód odrzucenia (w przypadku niepowodzenia)

rejectInfostring

Dodatkowe informacje o powodzie odrzucenia

Sprawdzenie statusu tokenizacji

Request

Sprawdzenie statusu tokenizacji bez zwracania ciała tokenu kartowego.

Security
bearerAuth
Path
tokenizerIdstringrequired

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

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

Responses

OK

Body*/*
tokenizerIdstring

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

statusstring

Status tokenizacji

rejectCodestring

Powód odrzucenia (w przypadku niepowodzenia)

rejectInfostring

Dodatkowe informacje o powodzie odrzucenia

redirectURLstring

Adres URL dla kontunuacji flow webowego

Pobranie informacji o wizerunku karty

Request

Metoda pozwalająca pobrać dane wizerunku karty w przypadku tokenów VTS.

Security
bearerAuth
Path
instrumentRefstringrequired
visualIdstringrequired
curl -i -X GET \
  'https://api.sandbox.planetpay.pl/v1/ecommerce/tokenizer/vts/{instrumentRef}/cardVisual/{visualId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Body*/*
altTextstring

Nazwa grafiki

mimeTypestring

Typ MIME (np. image/png)

widthstring

Szerokość w pikselach

heightstring

Wysokość w pikselach

encodedDatastring

Dane grafiki encodowane jako base64

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