logo
Powered by Redocly

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

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

Request
path Parameters
paymentId
required
string

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

Request Body schema:
required
type
required
string

Typ instrumentu płatniczego

Enum: "COF" "CARD" "BLIK" "BLIK_CODE" "BLIK_UID" "BLIK_PAYID" "GPAY" "APAY" "PBL" "SCOF"
instrumentNo
string or null

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

encInstrumentNo
string or null

Zaszyfrowany nr instrumentu płatniczego

instrumentRef
string or null

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

token
string or null

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

expDate
string or null

Data ważnosci (Format: YYYYMM) (wymagany dla type = CARD)

encExpDate
string or null

Zaszyfrowana data ważnosci

cvv
string or null

Kod zabezpieczajacy (wymagany dla type = CARD)

encCvv
string or null

Zaszyfrowany kod zabezpieczajacy

code
string or null

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

alias
string or null

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

app
string or null

Identyfikator konta mobilnego BLIK (w przypadku niejednoznacznosci aliasu)

provider
string or null

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

Enum: "BM" "PA"
bank
string or null

Nazwa banku (wymagany dla type = PBL)

bankId
integer or null <int32>

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

register
boolean or null

Zarejestruj alias na potrzeby transparentnych płatności

Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal Server Error

502

Bad Gateway

503

Service Unavailable

504

Gateway Timeout

put/v1/ecommerce/payment/{paymentId}/instrument
Request samples
No sample
Response samples
No sample

Aktualizacja atrybutu instrumentu płatniczego

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

Request
path Parameters
paymentId
required
string

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

Request Body schema:
required
cvv
string or null

Kod zabezpieczajacy karty

Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal Server Error

502

Bad Gateway

503

Service Unavailable

504

Gateway Timeout

patch/v1/ecommerce/payment/{paymentId}/instrument
Request samples
{
  • "cvv": "string"
}

Zlecenie płatności

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 ecommerce API przez 3 miesiące. Status propagowany jest też asynchronicznie kanałem notyfikacji.

Request
Request Body schema:
required
channel
required
string

Kanał operacji

Enum: "PAYWALL" "MOBILE" "WEBAPI" "EBOK" "CSS"
object (InstrumentInfo)

Szczegółowe dane requestu

type
required
string

Typ instrumentu płatniczego

Enum: "COF" "CARD" "BLIK" "BLIK_CODE" "BLIK_UID" "BLIK_PAYID" "GPAY" "APAY" "PBL" "SCOF"
instrumentNo
string or null

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

encInstrumentNo
string or null

Zaszyfrowany nr instrumentu płatniczego

instrumentRef
string or null

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

token
string or null

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

expDate
string or null

Data ważnosci (Format: YYYYMM) (wymagany dla type = CARD)

encExpDate
string or null

Zaszyfrowana data ważnosci

cvv
string or null

Kod zabezpieczajacy (wymagany dla type = CARD)

encCvv
string or null

Zaszyfrowany kod zabezpieczajacy

code
string or null

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

alias
string or null

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

app
string or null

Identyfikator konta mobilnego BLIK (w przypadku niejednoznacznosci aliasu)

provider
string or null

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

Enum: "BM" "PA"
bank
string or null

Nazwa banku (wymagany dla type = PBL)

bankId
integer or null <int32>

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

register
boolean or null

Zarejestruj alias na potrzeby transparentnych płatności

object or null (MerchantInfo)

Dane merchanta pośredniczacego (operator aplikacji mobilnej)

merchantId
required
string [ 0 .. 15 ] characters

Identyfikator merchanta nadany przez operatora płatności (MID)

merchantName
string or null
Deprecated

Nazwa merchanta

name
string or null

Nazwa merchanta

mcc
string or null

MCC

url
string or null

Adres URL sklepu

redirectURL
string or null

Adres URL przekierowania

terminalId
string or null

Id terminala

object or null (MerchantAddress)

Adres merchanta

street
required
string

Adres (ulica i numer domu)

postal
required
string

Kod pocztowy

state
string or null

Województwo

city
required
string

Miasto

country
required
string

Kraj (kod ISO np. PL)

taxId
string or null

Nip

acsNotificationURL
string or null

Adres publicznego endpointu do odebrania notyfikacji CRes z ACS (jeżeli obsługiwany przez merchanta)

object (CustomerInfo)

Dane wlasciciela karty

email
required
string

Adres email klienta

extCustomerId
string or null

Identyfikator klienta w systemie merchanta

name
string or null

Imię i nazwisko klienta

surname
string or null

Imię i nazwisko klienta

object or null (CustomerAddress)

Adres rozliczeniowy klienta (wymagany dla method = CARD)

street
required
string

Adres (ulica i numer domu)

postal
required
string

Kod pocztowy

state
string

Województwo

city
required
string

Miasto

country
required
string

Kraj (kod ISO np. PL)

object or null (CustomerRiskIndicator)

Dodatkowe parametry analizy ryzyka na potrzeby 3DS

scaPreference
string

Preferencje dotyczące silnego uwierzytelnienia klienta (SCA)

accountAuthDate
string or null

Data i godzina (UTC) uwierzytelnienia klienta (Format: YYYYMMDDHHMM) (wymagane dla scaPreference = LOW_RISK)

accountCreateDate
string or null

Data założenia konta u merchanta/agenta (Format: YYYYMMDD) (wymagane dla scaPreference = LOW_RISK)

accountChangeDate
string or null

Data ostatniej zmiany danych konta (Format: YYYYMMDD) (wymagane dla scaPreference = LOW_RISK)

accountActiveDate
string or null

Data od kiedy posiadacz karty aktywował płatności na koncie merchanta/agenta (Format: YYYYMMDD) (wymagane dla scaPreference = LOW_RISK)

passChangeDate
string or null

Data ostatniej zmiany hasła do konta (Format: YYYYMMDD) (wymagane dla scaPreference = LOW_RISK)

purchaseCount6M
integer or null <int32>

Liczba zakupów wykonana za pomocą konta w ciagu ostatnich sześciu miesięcy (wymagane dla scaPreference = LOW_RISK)

tokenizationCountDay
integer or null <int32>

Liczba prób dodania kart do konta z ostatnich 24 godzin (wymagane dla scaPreference = LOW_RISK)

transactionCountDay
integer or null <int32>
Deprecated

Liczba transakcji udanych oraz nieudanych z ostatnich 24 godzin

transactionCountYear
integer or null <int32>
Deprecated

Liczba transakcji udanych oraz nieudanych z ostatniego roku

shipAddressDate
string or null

Data pierwszego użycia adresu, który zostal wybrany dla aktualnej transakcji (Format: YYYYMMDD) (wymagane dla scaPreference = LOW_RISK)

shipNameIndicator
boolean or null

Wskazuje czy nazwa posiadacza karty zdefiniowana na koncie operatora jest identyczna jak ta w nazwie do wysyłki biezacej transakcji

suspiciousActivity
boolean or null

Wskazuje czy kiedykolwiek zachowanie posiadacza karty zostało potraktowane jako podejrzane (wymagane dla scaPreference = LOW_RISK)

authenticatedTransaction
boolean or null

Wskazuje czy transakcja byla dodatkowo uwierzytelniona

transactionSCountDay
integer or null <int32>

Liczba transakcji udanych z ostatnich 24 godzin

transactionUCountDay
integer or null <int32>

Liczba transakcji nieudanych z ostatnich 24 godzin

transactionSCountYear
integer or null <int32>

Liczba transakcji udanych z ostatniego roku

transactionUCountYear
integer or null <int32>

Liczba transakcji nieudanych z ostatniego roku

object or null (PhoneNumber)

Obiekt zawierajacy dane telefoniczne klienta

countryCode
required
string [ 1 .. 3 ] characters

Kod kraju

phoneNo
required
string [ 7 .. 15 ] characters

Numer telefonu

object or null (DeviceInfo)

Dane urządzenia z ktorego wykonywana jest operacja (przegladarka www lub urzadzenie mobilne) (wymagane dla channel = PAYWALL/WEBAPI)

ip
string or null

IP urządzenia

name
string or null

Nazwa urządzenia z ktorego wykonywana jest płatność

object or null (SdkData)

Parametry SDK (wymagany dla channel = MOBILE)

sdkTransID
required
string

Identyfikator UUID generowany przez 3DS SDK

sdkReferenceNumber
required
string

Identyfikator dostawcy oraz wersji 3DS SDK

sdkInterface
required
string

Wspierane przez SDK typ interfejsu

sdkUiType
required
Array of strings

Lista typow interfejsow wspieranych dla procesu challenge

Items Enum: "TEXT" "SINGLE_SELECT" "MULTI_SELECT" "OOB" "HTML"
sdkAppId
required
string

Stała Wartość UUID, ktora jest generowana przez SDK podczas inStałacji aplikacji

sdkEncData
required
string

Obiekt JWE przygotowany przez SDK, zawierajacy zaszyfrowane dane dla DS

required
object (EphemPubKey)

Czesc publiczna efemerycznej pary kluczy wygenerowanych przez SDK służąca do negocjacji połączenia z ACS

sdkAuthValue
required
string

Wartość służąca do weryfkacji autentycznosci oraz integralnosci SDK

object or null (BrowserData)

Parametry przeglądarki (wymagany dla channel = PAYWALL/WEBAPI; method = CARD)

javascriptEnabled
required
boolean

Obsługa JavaScript włączona w przeglądarce

javaEnabled
boolean or null

Obsługa Java włączona w przeglądarce (wymagany dla javascriptEnabled = true)

language
required
string or null

Jezyk ustawiony na przeglądarce (wymagany dla javascriptEnabled = true)

colorDepth
string or null

Wartość reprezentujaca głębie bitowa palety kolorów (wymagany dla javascriptEnabled = true)

screenHeight
integer or null <int32>

Wysokość ekranu w pikselach (wymagany dla javascriptEnabled = true)

screenWidth
integer or null <int32>

Szerokość ekranu w pikselach (wymagany dla javascriptEnabled = true)

timezone
integer or null <int32>

Przesunięcie strefy czasowej w minutach między czasem UTC (wymagany dla javascriptEnabled = true)

object or null (MerchantInfo)

Dane merchanta pośredniczacego (operator aplikacji mobilnej)

merchantId
required
string [ 0 .. 15 ] characters

Identyfikator merchanta nadany przez operatora płatności (MID)

merchantName
string or null
Deprecated

Nazwa merchanta

name
string or null

Nazwa merchanta

mcc
string or null

MCC

url
string or null

Adres URL sklepu

redirectURL
string or null

Adres URL przekierowania

terminalId
string or null

Id terminala

object or null (MerchantAddress)

Adres merchanta

street
required
string

Adres (ulica i numer domu)

postal
required
string

Kod pocztowy

state
string or null

Województwo

city
required
string

Miasto

country
required
string

Kraj (kod ISO np. PL)

taxId
string or null

Nip

acsNotificationURL
string or null

Adres publicznego endpointu do odebrania notyfikacji CRes z ACS (jeżeli obsługiwany przez merchanta)

object or null (PaymentOptions)

Inne parametry sterujace

transKind
string or null

Rodzaj transakcji dla transakcji kartowych

transType
string or null

Typ transakcji dla transakcji kartowych

tokenize
boolean or null

Zadanie tokenizacji karty

recurring
string or null

Flaga płatności cyklicznych

recurringType
string or null

Rodzaj płatności cyklicznej

refPaymentId
string or null

Identyfikator poprzedniej płatności (INITIAL)

tdsServerTxnId
string or null

Identyfikator transakcji z systemu 3DS Server (jeżeli wystapiła wczesniejsza interakcja z 3DS przed zarejestrowaniem płatności)

validTime
integer or null <int32> <= 604800

Czas ważnosci generowanych linkow płatności w sekundach (domyslnie 600; max. 604800)

iframe
boolean or null

Zadanie tokenizacji karty

asyncNotify
string or null

Obsługa notyfikacji dla transakcji kartowych

methods
string or null

Lista dozwolonych metod płatności

method
required
string

Metoda płatności

object (OrderInfo)

Dane zamówienia podlegajacego płatności

amount
number or null

Kwota transakcji (Format: 000.00)

currency
string or null

Waluta transakcji (kod ISO np. PLN)

extOrderId
string or null

Identyfikator zamówienia z systemu merchanta

object or null (CustomerAddress)

Adres rozliczeniowy klienta (wymagany dla method = CARD)

street
required
string

Adres (ulica i numer domu)

postal
required
string

Kod pocztowy

state
string

Województwo

city
required
string

Miasto

country
required
string

Kraj (kod ISO np. PL)

object or null (MerchantRiskIndicator)

Dodatkowe parametry analizy ryzyka na potrzeby 3DS

deliveryEmailAddress
string or null

Adres e-mail dostawy. Pole obowiazkowe dla Electronic Delivery.

deliveryTimeframe
string or null

Wskazuje ramy czasowe dostawy

Enum: "ELECTRONIC" "SAME_DAY" "NEXT_DAY" "TWO_DAY"
giftCardAmount
number or null

Kwota przedplaty dla kart przedplaconych lub kart podarunkowych w calych jednostkach waluty.

giftCardCount
integer or null <int32>

Liczba zakupionych kart przedplaconych lub podarunkowych

giftCardCurr
string or null

Waluta zakupionych kart przedplaconych lub podarunkowych

preorder
boolean or null

Flaga oznaczająca zamówienie z przyszłą datą wydania

preorderDate
string or null <date>

W przypadku zakupu typu preorder przewidywana data dostępnosci zakupu

reorder
boolean or null

Flaga Wskazujaca czy przedmiot jest zamawiany ponownie

shipping
string or null

Określa sposób wysyłki wybrany dla transakcji

Enum: "CARDHOLDER_ADDR" "VERIFIED_ADDR" "DIFFERENT_ADDR" "STORE" "DIGITAL" "TICKETS" "NONE"
description
string or null

Opis zamówienia (do prezentacji na ekranie potwierdzenia)

Array of objects or null or null (SubpaymentInfo)

Podział na transakcje przy płatności z MARKETPLACE

Array
subpaymentId
string or null

Identyfikator subtransakcji

merchantId
required
string

Identyfikator merchanta

amount
number

Kwota transakcji

commission
number

Prowizja dla MARKETPLACE

extOrderId
string or null

Identyfikator zamówienia w systemie merchanta

object or null (RecipientInfo)

Odbiorca srodków dla transakcji typu ACCT_FUNDING (wymagane dla transKind = ACCT_FUNDING)

ownAccount
required
boolean

Własny rachunek/wallet

name
string or null

Imię odbiorcy (wymagany dla ownAccount = false)

surname
string or null

Nazwisko odbiorcy (wymagany dla ownAccount = false)

accountNo
string or null

Nr rachunku odbiorcy (wymagany dla ownAccount = false)

object or null (CustomerAddress)

Adres rozliczeniowy klienta (wymagany dla method = CARD)

street
required
string

Adres (ulica i numer domu)

postal
required
string

Kod pocztowy

state
string

Województwo

city
required
string

Miasto

country
required
string

Kraj (kod ISO np. PL)

riskyBrands
Array of strings or null or null

Lista MCC wysokiego ryzyka związanych z walletem (transakcje AFT)

Enum: "ADULT_CONTENT" "CRYPTOCURRENCY" "CYBERLOCKER_SERVICES" "GAMBLING" "HIGH_RISK_SECURITIES" "PRESCRIPTION_DRUG" "TOBACCO"
preAuthRequest
boolean
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal Server Error

502

Bad Gateway

503

Service Unavailable

504

Gateway Timeout

post/v1/ecommerce/payment
Request samples
No sample
Response samples
No sample

Wycofanie transakcji

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

Request
path Parameters
paymentId
required
string
transId
required
string
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal Server Error

502

Bad Gateway

503

Service Unavailable

504

Gateway Timeout

post/v1/ecommerce/payment/{paymentId}/transactions/{transId}/cancel
Request samples 
Kontynuacja odrzuconej płatności
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.


Request 
path Parameters
paymentId
required
string
Identyfikator płatności w systemie operatora płatności


 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


post/v1/ecommerce/payment/{paymentId}/retry
Request samples 
Generowanie nowego linku do płatności
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).


Request 
path Parameters
paymentId
required
string
Identyfikator płatności w systemie operatora płatności


 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


post/v1/ecommerce/payment/{paymentId}/restore
Request samples 
Realizacja zwrotu środkow dla przeprocesowanych płatności
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.


Request 
path Parameters
paymentId
required
string
Identyfikator płatności w systemie operatora płatności


 
Request Body schema: 
required
subpaymentId
string or null
Identyfikator subtransakcji


 
amount
number or null
Kwota zwrotu dla zwrotow czesciowych; domyslnie zwracana jest pelna kwota (Format: 000.00)


 
description
string or null
Dodatkowe informacje o powodzie zwrotu


 
extRefundId
string or null
Identyfikator zwrotu w zewnetrznym systemie


 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


post/v1/ecommerce/payment/{paymentId}/refund
Request samples 
{
  • "subpaymentId": "string",
  • "amount": 0,
  • "description": "string",
  • "extRefundId": "string"
}
Zlecenie dopełnienia
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.


Request 
path Parameters
paymentId
required
string
 
Request Body schema: 
required
amount
number or null
Kwota dopełnienia


 
description
string or null
Dodatkowe informacje


 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


post/v1/ecommerce/payment/{paymentId}/capture
Request samples 
{
  • "amount": 0,
  • "description": "string"
}
Anulowanie płatności
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.


Request 
path Parameters
paymentId
required
string
Identyfikator płatności w systemie operatora płatności


 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


post/v1/ecommerce/payment/{paymentId}/cancel
Request samples 
Okeslenie organizacji platniczej i wersji protokołu (dla flow mobilnego).
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. Drugi wariant metody na potrzeby wywołań z payment SDK zakłada, że płatność została już wcześniej zainicjalizowana (znamy instrument)


Request 
path Parameters
paymentId
required
string
Identyfikator płatności w systemie operatora płatności


 
Request Body schema: 
required
channel
required
string
Kanał operacji


 Enum: "PAYWALL" "MOBILE" "WEBAPI" "EBOK" "CSS"  
sdkStartProtocol
required
string
Najstarsza wersja protokołu wspierana przez SDK


 
sdkEndProtocol
required
string
Najnowsza wersja protokołu wspierana przez SDK


 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


post/v1/ecommerce/payment/{paymentId}/binInfo
Request samples 
{
  • "channel": "PAYWALL",
  • "sdkStartProtocol": "string",
  • "sdkEndProtocol": "string"
}
Zlecenie korekty kwoty perautoryzacji
Korekta pozwala na modyfikację kwoty preautoryzacji. Operację można wykonać wielokrotnie, dopóki nie zostanie wykonane dopełnienie (capture).


Request 
path Parameters
paymentId
required
string
 
Request Body schema: 
required
amount
number or null
Kwota dopełnienia


 
description
string or null
Dodatkowe informacje


 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


post/v1/ecommerce/payment/{paymentId}/adjustment
Request samples 
{
  • "amount": 0,
  • "description": "string"
}
Wyszukiwanie płatności po zewnetrznych identyfikatorach
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.


Request 
Request Body schema: 
required
extOrderId
required
string
Identyfikator zamówienia z systemu merchanta


 
object or null (MerchantInfo) 
Dane merchanta pośredniczacego (operator aplikacji mobilnej)


 
merchantId
required
string  [ 0 .. 15 ] characters 
Identyfikator merchanta nadany przez operatora płatności (MID)


 
merchantName
string or null
 Deprecated 
Nazwa merchanta


 
name
string or null
Nazwa merchanta


 
mcc
string or null
MCC


 
url
string or null
Adres URL sklepu


 
redirectURL
string or null
Adres URL przekierowania


 
terminalId
string or null
Id terminala


 
object or null (MerchantAddress) 
Adres merchanta


 
street
required
string
Adres (ulica i numer domu)


 
postal
required
string
Kod pocztowy


 
state
string or null
Województwo


 
city
required
string
Miasto


 
country
required
string
Kraj (kod ISO np. PL)


 
taxId
string or null
Nip


 
acsNotificationURL
string or null
Adres publicznego endpointu do odebrania notyfikacji CRes z ACS (jeżeli obsługiwany przez merchanta)


 
object or null (MerchantInfo) 
Dane merchanta pośredniczacego (operator aplikacji mobilnej)


 
merchantId
required
string  [ 0 .. 15 ] characters 
Identyfikator merchanta nadany przez operatora płatności (MID)


 
merchantName
string or null
 Deprecated 
Nazwa merchanta


 
name
string or null
Nazwa merchanta


 
mcc
string or null
MCC


 
url
string or null
Adres URL sklepu


 
redirectURL
string or null
Adres URL przekierowania


 
terminalId
string or null
Id terminala


 
object or null (MerchantAddress) 
Adres merchanta


 
street
required
string
Adres (ulica i numer domu)


 
postal
required
string
Kod pocztowy


 
state
string or null
Województwo


 
city
required
string
Miasto


 
country
required
string
Kraj (kod ISO np. PL)


 
taxId
string or null
Nip


 
acsNotificationURL
string or null
Adres publicznego endpointu do odebrania notyfikacji CRes z ACS (jeżeli obsługiwany przez merchanta)


 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


post/v1/ecommerce/payment/search
Request samples 
{
  • "extOrderId": "string",
  • "merchant": {
    },
  • "agent": {
    }
}
Okeslenie organizacji platniczej i wersji protokołu (dla flow mobilnego).
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.


Request 
Request Body schema: 
required
channel
required
string
Kanał operacji


 Enum: "PAYWALL" "MOBILE" "WEBAPI" "EBOK" "CSS"  
sdkStartProtocol
required
string
Najstarsza wersja protokołu wspierana przez SDK


 
sdkEndProtocol
required
string
Najnowsza wersja protokołu wspierana przez SDK


 
required
object (InstrumentInfo) 
Szczegółowe dane requestu


 
type
required
string
Typ instrumentu płatniczego


 Enum: "COF" "CARD" "BLIK" "BLIK_CODE" "BLIK_UID" "BLIK_PAYID" "GPAY" "APAY" "PBL" "SCOF"  
instrumentNo
string or null
Nr instrumentu płatniczego (np. tokenu lub karty) (wymagany dla type = CARD/COF)


 
encInstrumentNo
string or null
Zaszyfrowany nr instrumentu płatniczego


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


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


 
expDate
string or null
Data ważnosci (Format: YYYYMM) (wymagany dla type = CARD)


 
encExpDate
string or null
Zaszyfrowana data ważnosci


 
cvv
string or null
Kod zabezpieczajacy (wymagany dla type = CARD)


 
encCvv
string or null
Zaszyfrowany kod zabezpieczajacy


 
code
string or null
Jednorazowy kod płatności BLIK (wymagany dla type = BLIK_CODE)


 
alias
string or null
Alias uzytkownika BLIK dla płatności OneClick lub cyklicznych (wymagany dla type = BLIK_UID/BLIK_PAYID)


 
app
string or null
Identyfikator konta mobilnego BLIK (w przypadku niejednoznacznosci aliasu)


 
provider
string or null
Identyfikator pośrednika płatności (może byc wybrany automatycznie na podstawie konfiguracji merchanta)


 Enum: "BM" "PA"  
bank
string or null
Nazwa banku (wymagany dla type = PBL)


 
bankId
integer or null <int32> 
Identyfikator banku (w systemie operatora PBL) (wymagany dla type = PBL)


 
register
boolean or null
Zarejestruj alias na potrzeby transparentnych płatności


 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


post/v1/ecommerce/payment/binInfo
Request samples 
{
  • "channel": "PAYWALL",
  • "sdkStartProtocol": "string",
  • "sdkEndProtocol": "string",
  • "instrument": {
    }
}
Pobieranie informacji o płatności
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.


Request 
path Parameters
paymentId
required
string
Identyfikator płatności w systemie operatora płatności


 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


get/v1/ecommerce/payment/{paymentId}
Request samples 
Aktualizacja danych instrumentu płatniczego oraz urządzenia
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).


Request 
path Parameters
paymentId
required
string
Identyfikator płatności w systemie operatora płatności


 
Request Body schema: 
required
object (InstrumentInfo) 
Szczegółowe dane requestu


 
type
required
string
Typ instrumentu płatniczego


 Enum: "COF" "CARD" "BLIK" "BLIK_CODE" "BLIK_UID" "BLIK_PAYID" "GPAY" "APAY" "PBL" "SCOF"  
instrumentNo
string or null
Nr instrumentu płatniczego (np. tokenu lub karty) (wymagany dla type = CARD/COF)


 
encInstrumentNo
string or null
Zaszyfrowany nr instrumentu płatniczego


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


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


 
expDate
string or null
Data ważnosci (Format: YYYYMM) (wymagany dla type = CARD)


 
encExpDate
string or null
Zaszyfrowana data ważnosci


 
cvv
string or null
Kod zabezpieczajacy (wymagany dla type = CARD)


 
encCvv
string or null
Zaszyfrowany kod zabezpieczajacy


 
code
string or null
Jednorazowy kod płatności BLIK (wymagany dla type = BLIK_CODE)


 
alias
string or null
Alias uzytkownika BLIK dla płatności OneClick lub cyklicznych (wymagany dla type = BLIK_UID/BLIK_PAYID)


 
app
string or null
Identyfikator konta mobilnego BLIK (w przypadku niejednoznacznosci aliasu)


 
provider
string or null
Identyfikator pośrednika płatności (może byc wybrany automatycznie na podstawie konfiguracji merchanta)


 Enum: "BM" "PA"  
bank
string or null
Nazwa banku (wymagany dla type = PBL)


 
bankId
integer or null <int32> 
Identyfikator banku (w systemie operatora PBL) (wymagany dla type = PBL)


 
register
boolean or null
Zarejestruj alias na potrzeby transparentnych płatności


 
object or null (DeviceInfo) 
Dane urządzenia z ktorego wykonywana jest operacja (przegladarka www lub urzadzenie mobilne) (wymagane dla channel = PAYWALL/WEBAPI)


 
ip
string or null
IP urządzenia


 
name
string or null
Nazwa urządzenia z ktorego wykonywana jest płatność


 
object or null (SdkData) 
Parametry SDK (wymagany dla channel = MOBILE)


 
sdkTransID
required
string
Identyfikator UUID generowany przez 3DS SDK


 
sdkReferenceNumber
required
string
Identyfikator dostawcy oraz wersji 3DS SDK


 
sdkInterface
required
string
Wspierane przez SDK typ interfejsu


 
sdkUiType
required
Array of strings
Lista typow interfejsow wspieranych dla procesu challenge


Items Enum: "TEXT" "SINGLE_SELECT" "MULTI_SELECT" "OOB" "HTML"  
sdkAppId
required
string
Stała Wartość UUID, ktora jest generowana przez SDK podczas inStałacji aplikacji


 
sdkEncData
required
string
Obiekt JWE przygotowany przez SDK, zawierajacy zaszyfrowane dane dla DS


 
required
object (EphemPubKey) 
Czesc publiczna efemerycznej pary kluczy wygenerowanych przez SDK służąca do negocjacji połączenia z ACS


 
sdkAuthValue
required
string
Wartość służąca do weryfkacji autentycznosci oraz integralnosci SDK


 
object or null (BrowserData) 
Parametry przeglądarki (wymagany dla channel = PAYWALL/WEBAPI; method = CARD)


 
javascriptEnabled
required
boolean
Obsługa JavaScript włączona w przeglądarce


 
javaEnabled
boolean or null
Obsługa Java włączona w przeglądarce (wymagany dla javascriptEnabled = true)


 
language
required
string or null
Jezyk ustawiony na przeglądarce (wymagany dla javascriptEnabled = true)


 
colorDepth
string or null
Wartość reprezentujaca głębie bitowa palety kolorów (wymagany dla javascriptEnabled = true)


 
screenHeight
integer or null <int32> 
Wysokość ekranu w pikselach (wymagany dla javascriptEnabled = true)


 
screenWidth
integer or null <int32> 
Szerokość ekranu w pikselach (wymagany dla javascriptEnabled = true)


 
timezone
integer or null <int32> 
Przesunięcie strefy czasowej w minutach między czasem UTC (wymagany dla javascriptEnabled = true)


 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


patch/v1/ecommerce/payment/{paymentId}
Request samples 
No sample
Response samples 
No sample
Pobranie listy transakcji dla płatności
Request 
path Parameters
paymentId
required
string
 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


get/v1/ecommerce/payment/{paymentId}/transactions
Request samples 
Pobieranie tokenu kartowego
Pobranie danych tokenu na podstawie identyfikatora procesu tokenizacji. Merchant powinien zapisać nr tokenu i posługiwać się nim w dalszej komunikacji z API.


Request 
path Parameters
paymentId
required
string
Identyfikator płatności w systemie operatora płatności


 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


get/v1/ecommerce/payment/{paymentId}/tokenizer
Request samples 
Pobranie listy subtransakcji dla płatności marketplace
Request 
path Parameters
paymentId
required
string
 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


get/v1/ecommerce/payment/{paymentId}/subpayments
Request samples 
Pobieranie statusu płatności
Aktualny status płatności można sprawdzić używając identyfikatora płatności (paymentId).


Request 
path Parameters
paymentId
required
string
Identyfikator płatności w systemie operatora płatności


 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


get/v1/ecommerce/payment/{paymentId}/status
Request samples 
Pobieranie informacji o zwrotach
Informacja o statusie zwrotów dla płatności.


Request 
path Parameters
paymentId
required
string
Identyfikator płatności w systemie operatora płatności


 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


get/v1/ecommerce/payment/{paymentId}/refunds
Request samples 
Pobieranie informacji o zwrotach
Informacja o statusie wybranego zwrotu.


Request 
path Parameters
paymentId
required
string
Identyfikator płatności w systemie operatora płatności


 
refundId
required
string
Identyfikator zwrotu (zgodny formatem z identyfikatorem płatności)


 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


get/v1/ecommerce/payment/{paymentId}/refund/{refundId}
Request samples 
Pobieranie danych ACS challenge
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.


Request 
path Parameters
paymentId
required
string
Identyfikator płatności w systemie operatora płatności


 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


get/v1/ecommerce/payment/{paymentId}/acsData
Request samples 
Pobranie metod płatności dla merchanta
Lista aktywowanych dla merchanta metod płatności.


Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


get/v1/ecommerce/payment/methods
Request samples 
Pobranie opcjonalnych parametrow metody płatności
Niektóre metody płatności posiadają osobną listę opcji, np. w przypadku przelewów (PBL) otrzymamy listę banków.


Request 
path Parameters
paymentMethod
required
string
 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


500
Internal Server Error


502
Bad Gateway


503
Service Unavailable


504
Gateway Timeout


get/v1/ecommerce/payment/methods/{paymentMethod}
Request samples 
➔ Next to Notyfikacje