Przejdź do głównej zawartości

Secure Elements

Rozszerzenie PayU API​

Pobieranie konfiguracji Click to Pay​

Aby skorzystać z Click to Pay w aplikacji Secure Elements, najpierw zweryfikuj dostępność tej metody oraz pobierz jej konfigurację dla swojego POS-a. W tym celu wywołaj metodę pobierania instrumentów płatniczych, rozszerzając zapytanie o dodatkowy parametr features z wartością clickToPay.

Przykład żądania pobrania metod płatności w środowisku produkcyjnym
curl -X GET https://secure.payu.com/api/v2_1/paymethods?features=clickToPay \
-H "Authorization: Bearer 87ad751f-7ea5-4023-a16f-04b6647a07f5"
-H "Cache-Control: no-cache"

W odpowiedzi w tablicy payByLinks w obiekcie z tokenami kartowymi ("value"="c") otrzymasz dodatkowy obiekt clickToPay zawierający wszystkie niezbędne dane do skonfigurowania Click to Pay w aplikacji Secure Elements.

Przykład pozytywnej odpowiedzi na pobranie metod płatności (HTTP 200) z dodatkowym obiektem clickToPay
{
    "payByLinks":[{
        "value":"c",
        "name":"Płatność online kartą płatniczą",
        "brandImageUrl":"http://static.payu.com/images/mobile/logos/pbl_c.png",
        "status":"ENABLED",
        "minAmount": 50,
        "maxAmount": 100000,
        "features": {
            "clickToPay": {
                "clickToPayBrandImageUrl": "https://static.payu.com/images/mobile/logos/pbl_cpt_on.png",
                "mastercard": {
                  "status": "ENABLED",
                  "dpaId": "mddctp12"
                },
                "visa": {
                    "dpaId": "visctp01",
                    "acquirerBIN": "123456",
                    "acquirerMerchantId": "MERCH01",
                    "status": "ENABLED"
                }
            }
        }
    }]
}

Rozszerzenie zamówienia​

Aby utworzyć zamówienie z już wybraną metodą płatności, musisz dodać do standardowego zamówienia sekcję payMethods. Opis obiektu payMethods możesz znaleźć w naszej referencji API w sekcji Create an Order.

Użycie danych karty​

W obiekcie payMethod powinieneś przekazać token zwrócony przez aplikację Secure Elements po zakończeniu procesu. Token ten powinien być przekazany w polu value obiektu payMethod, a pole type powinno mieć wartość CARD_TOKEN.

Przykład obiektu payMethods
{
    "payMethods": {
        "payMethod": {
            "type": "CARD_TOKEN",
            "value": "TOKD_1LOQUV5MMRNX70i7UXXXXXXXXX"
        }
    }
}

Użycie karty z Click to Pay​

W obiekcie payMethod przekaż dane zwrócone przez aplikację Secure Elements po zakończeniu procesu. W zależności od organizacji płatniczej karty uzupełnij odpowiednie pola w obiekcie clickToPay:

  • dla kart Visa Click to Pay wymagane jest pole srcCorrelationId,
  • dla kart Mastercard Click to Pay wymagane są pola srcCorrelationId oraz srcDigitalCardId.
Przykład obiektu payMethods dla kart Visa Click to Pay
{
    "payMethods": {
        "payMethod": {
            "type": "PBL",
            "value": "c",
            "clickToPay" : {
                "visa": {
                    "srcCorrelationId": "123e4567-e89b-12d3-a456-426614174000"
                }
            }
        }
    }
}
Notatka

Szczegółowe informacje na temat parametrów znajdziesz w sekcji Create an Order w naszej referencji API.

JavaScript SDK​

PayU udostępnia JS SDK z biblioteką JavaScript działającą po stronie przeglądarki. Biblioteka ta zawiera metody i obiekty, które mogą pomóc w integracji niektórych rozwiązań oferowanych przez PayU, np. Secure Elements. Możesz też wypróbować aplikację demonstracyjną Secure Elements, w której przetestujesz integrację na własnych danych POS i skonfigurujesz niestandardowe style.

Przykład użycia​

Ładowanie JS SDK
JS SDK należy zawsze wczytywać z serwera PayU. Nie możesz wczytać go z własnego serwera ani dołączać do budowanego pakietu.
<script type="text/javascript" src="https://secure.payu.com/javascript/sdk"></script>
Tworzenie instancji SecureElements
SecureElements(options?)
Parametry Metody
optionsoptionalobject
Opcje instancji.
devboolean
Utworzenie instancji w trybie deweloperskim, która umożliwia działanie na stronie nieużywającej HTTPS.
Zwraca
Instancję SecureElements.
Wyjątki
non.https.integration
Występuje podczas tworzenia instancji SecureElements, gdy protokół strony, na której wczytywane jest JS SDK, nie jest protokołem https ani file, a strona nie jest ładowana z localhost: 127.0.0.1 lub 0.0.0.0. Podczas prac wdrożeniowych można włączyć tryb deweloperski w parametrze options.
const secureElements = SecureElements();
Metody instancji SecureElements
render(selector, options)
Wyświetla aplikację na stronie.
Parametry metody
selectorrequiredstring
Selektor elementu, w którym ma się wyświetlić aplikacja. Element jest wyszukiwany przy użyciu metody querySelectorAll.
optionsrequiredobject
Opcje aplikacji.
configurationrequiredobject
Obiekt konfiguracji aplikacji. Więcej informacji o poszczególnych elementach dostępne jest w sekcji Konfiguracja.
customizationobject
Obiekt dostosowania aplikacji. Więcej informacji o poszczególnych elementach dostępne jest w sekcji Dostosowanie.
Zwraca
Instancję SecureElements.
Wyjątki
element.selector.empty
Nie podano parametru selector lub jest on pusty.
element.selector.not.string
Parametr selector nie jest typu string.
element.not.exists
Element nie istnieje na stronie.
element.too.many.exists
Na stronie znajduje się więcej niż jeden element.
element.not.valid
Niepoprawny element (nie ma zaimplementowanej metody appendChild lub jest to element typu input).
element.contains.children
Element posiada elementy podrzędne.
no.configuration.defined
Nie podano opcji configuration lub jest nieprawidłowego typu.
no.elements.defined
Nie podano w konfiguracji pola elements lub jest nieprawidłowego typu.
no.posId.defined
Nie podano w konfiguracji pola posId lub jest nieprawidłowego typu.
secureElements.render('#secureElementsApp', {
    configuration: {
        elements: ['cards'],
        posId: '482413',
        clickToPay: {
            dpaName: "Sandbox Test",
            mastercard: {
                dpaId: 'jI8iGo86'
            },
            visa: {
                dpaId: 'jI8iGo86',
                acquirerBIN: "498707",
                acquirerMerchantId: 'jI8iGo86'
            }
        },
        buyer: {
            email: 'test-email@test-domain.com'
        }
    },
    customization: {
        lang: 'pl',
    },
});
on(event, callback)
Umożliwia przypięcie własnej funkcji zwrotnej do zdarzenia emitowanego przez aplikację. Więcej informacji o zdarzeniach znajdziesz w rozdziale zdarzenia.
Parametry metody
eventrequiredstring
Rodzaj zdarzenia
Możliwe wartości
readyWyemitowane, gdy aplikacja zostanie wyświetlona.
completedWyemitowane, gdy płatnik zakończy proces w aplikacji.
callbackrequiredfunction
Funkcja zwrotna wywoływana po wyemitowaniu zdarzenia.
Zwraca
Własną instancję SecureElements
Wyjątki
event.unknown
Nieznany typ zdarzenia w parametrze event
event.callback.not.function
Parametr callback nie jest funkcją.
secureElements
    .on('ready', function () {
        // aplikacja gotowa
    })
    .on('completed', function (body) {
        // płatnik zakończył proces w aplikacji
    })

Opcje​

Opcje metody render.

Konfiguracja​

Wszystkie parametry są sprawdzane pod kątem odpowiedniego typu oraz czy zawierają poprawne wartości. W przypadku nieznanego lub niepoprawnego parametru opcjonalnego jest on ignorowany, a informacje o tym zostaną zalogowane do konsoli przeglądarki na poziomie warn.

Parametry konfiguracji
elementsrequiredarray
Tablica zawierająca listę elementów do włączenia.
Dozwolone wartości: cards.
posIdrequiredstring
Identyfikator punktu płatności, który można znaleźć w panelu menedżerskim.
Musi być ciągiem znaków zawierającym wyłącznie cyfry.
clickToPayobject
Dane konfiguracyjne Click to Pay.
W przypadku braku tych danych, funkcjonalność Click to Pay nie będzie dostępna.
buyerobject
Informacje o płatniku.

W poniższym przykładzie użyto testowych danych ze środowiska Sandbox.

{
    elements: ['cards'],
    posId: '482413',
    clickToPay: {
        dpaName: "Sandbox Test",
        mastercard: {
            dpaId: 'jI8iGo86'
        },
        visa: {
            dpaId: 'jI8iGo86',
            acquirerBIN: "498707",
            acquirerMerchantId: 'jI8iGo86'
        }
    },
    buyer: {
        email: 'test-email@test-domain.com'
    }
}
Obiekt clickToPay
Dane konfiguracyjne Click to Pay.
dpaNamestring
Nazwa merchanta, która może być wyświetlona na stronach Click to Pay. Maksymalna długość to 32 znaki.
mastercardobject
Dane konfiguracyjne dla Mastercard uzyskane w usłudze pobierania instrumentów płatniczych.
dpaIdstring
Identyfikator dpaId
visaobject
Dane konfiguracyjne dla Visa uzyskane w usłudze pobierania instrumentów płatniczych.
dpaIdstring
Identyfikator dpaId
acquirerBINstring
Identyfikator acquirerBIN
acquirerMerchantIdstring
Identyfikator acquirerMerchantId
Obiekt buyer
Informacje o płatniku.
emailstring
Adres e-mail płatnika. Używany w Click to Pay do rozpoznawania konta użytkownika.

Dostosowanie​

Wszystkie parametry są sprawdzane pod kątem odpowiedniego typu oraz czy zawierają poprawne wartości. W przypadku nieznanego lub niepoprawnego parametru jest on ignorowany, a informacje o tym zostaną zalogowane do konsoli przeglądarki na poziomie warn.

Parametry dostosowania
langstring
Dwuliterowy kod języka. Dostępne języki to: en, pl. W przypadku braku języka pobierany jest on z przeglądarki. W przypadku nieobsługiwanego języka używany jest en.
optionsobject
Dodatkowe opcje dostosowania.
stylesobject
Niestandardowe style. Pozwalają dostosować wygląd aplikacji tak, aby lepiej pasował do stylu Twojej strony. Jeśli nie podasz tej wartości, użyte zostaną style domyślne.
{
    lang: 'pl',
    options: {
        enableCardFormFieldsAutoJump: false
    },
    styles: {
        body: {
            margin: '10px'
        }
    }
}
Obiekt options
Opcje dostosowania.
enableCardFormFieldsAutoJumpboolean
Automatycznie przechodzi pomiędzy polami formularza karty po wprowadzeniu poprawnej wartości. Wartość domyślna: true.
showCardNumberBrandIconboolean
Wyświetla ikonę marki karty w polu numeru karty. Wartość domyślna: true.
skipStyleDefaultsboolean
Pomija domyślne style aplikacji. Wartość domyślna: false.
darkModeboolean
Włącza tryb ciemny dla aplikacji. Wartość domyślna: false.
Obiekt styles
Niestandardowe style.
baseobject
Właściwości bazowe.
fontSizeLengthString
Bazowy rozmiar czcionki.
fontFamilystring
Bazowa rodzina czcionek.
Maksymalna długość: 150 znaków. Dozwolone znaki: 0-9a-z-\s,"'
fontWeightFontWeightValue
Bazowa grubość czcionki.
lineHeightLengthString
Bazowa wysokość linii.
gapLengthString
Bazowy odstęp pomiędzy elementami aplikacji. Ta wartość bazowa będzie używana do wyliczania wszystkich odstępów w aplikacji.
fontsarray
Dodatkowe czcionki do załadowania.
familyrequiredstring
Nazwa rodziny czcionek.
Maksymalna długość: 150 znaków. Dozwolone znaki: -_ a-zA-Z0-9
srcrequiredarray
Lista źródeł.
urlrequiredstring
Adres URL do pliku czcionki.
Musi być poprawnym adresem URL.
formatrequiredstring
Format czcionki.
Wartość jedna z: "collection", "embedded-opentype", "opentype", "svg", "truetype", "woff", "woff2"
stylestring
Styl czcionki.
Wartość jedna z: "normal", "italic", "oblique"
weightstring
Grubość czcionki.
Wartość jedna z: "normal", "bold", "lighter", "bolder", "inherit", "initial", "unset", 100, 200, 300, 400, 500, 600, 700, 800, 900
stretchstring
Rozciągnięcie czcionki.
Wartość jedna z: "normal", "condensed", "expanded", "ultra-condensed", "extra-condensed", "semi-condensed", "semi-expanded", "extra-expanded", "ultra-expanded"
unicodeRangestring
Zakres znaków Unicode obsługiwanych przez czcionkę.
Musi być poprawną definicją zakresu Unicode i pasować do: U+([0-9a-f?]{1,6}|[0-9a-f]{1,6}-[0-9a-f]{1,6})(,U+([0-9a-f?]{1,6}|[0-9a-f]{1,6}-[0-9a-f]{1,6}))*
bodyobject
Style dla elementu body.
Wszystkie właściwości z: MarginStyles
buttonobject
primaryobject
defaultButtonStyles
Style przycisku głównego w stanie domyślnym.
hoverButtonStyles
Style przycisku głównego w stanie po najechaniu kursorem.
focusButtonStyles
Style przycisku głównego w stanie fokusu.
activeButtonStyles
Style przycisku głównego w stanie aktywnym / wciśniętym.
disabledButtonStyles
Style przycisku głównego w stanie wyłączonym.
loadingButtonStyles
Style przycisku głównego w stanie ładowania.
secondaryobject
defaultButtonStyles
Style przycisku drugorzędnego w stanie domyślnym.
hoverButtonStyles
Style przycisku drugorzędnego w stanie po najechaniu kursorem.
focusButtonStyles
Style przycisku drugorzędnego w stanie fokusu.
activeButtonStyles
Style przycisku drugorzędnego w stanie aktywnym / wciśniętym.
disabledButtonStyles
Style przycisku drugorzędnego w stanie wyłączonym.
loadingButtonStyles
Style przycisku drugorzędnego w stanie ładowania.
inputobject
defaultInputStyles
Style pola input w stanie domyślnym.
errorInputStyles
Style pola input w stanie błędu.
focusInputStyles
Style pola input w stanie fokusu.
disabledInputStyles
Style pola input w stanie wyłączonym.
placeholderInputStyles
Style tekstu podpowiedzi (placeholder) w polu input.
selectobject
defaultSelectStyles
Style elementu select w stanie domyślnym.
errorSelectStyles
Style elementu select w stanie błędu.
focusSelectStyles
Style elementu select w stanie fokusu.
disabledSelectStyles
Style elementu select w stanie wyłączonym.
menuSelectStyles
Style menu elementu select.
optionSelectStyles
Style opcji w menu elementu select.
placeholderSelectStyles
Style tekstu podpowiedzi (placeholder) w elemencie select.
radioobject
defaultRadioStyles
Style elementu radio w stanie domyślnym.
focusRadioStyles
Style elementu radio w stanie fokusu.
labelTypographyStyles
Style etykiety (label) elementu radio.
checkboxobject
defaultCheckboxStyles
Style elementu checkbox w stanie domyślnym.
focusCheckboxStyles
Style elementu checkbox w stanie fokusu.
labelTypographyStyles
Style etykiety (label) elementu checkbox.
helperTextTypographyStyles
Style tekstu pomocniczego elementu checkbox.
headerTypographyStyles
Style nagłówków.
paragraphTypographyStyles
Style akapitów.
labelTypographyStyles
Style etykiet (label).
helperTextTypographyStyles
Style tekstów pomocniczych.
errorTypographyStyles
Style komunikatów błędów.
Obiekty podstawowe
Podstawowe typy, które można wykorzystać w definicji stylów.
LengthStringstring
Wartość długości jako tekst (string).
Dopasowanie do wzorca: (\d{1,4}(.\d+)?|.\d+)(px|em|rem|%)
ColorStringstring
Wartość koloru jako tekst (string).
Dopasowanie do wzorca: #([0-9a-f]3|[0-9a-f]4|[0-9a-f]6|[0-9a-f]8)
Przykłady: #FFF, #abcdef, #AAA8, #88888810
FontWeightValuestring or number
Wartość grubości czcionki.
Wartość jedna z: "normal", "bold", "lighter", "bolder", "inherit", "initial", "unset", 100, 200, 300, 400, 500, 600, 700, 800, 900
Obiekt ButtonStyles
Obiekt opisujący wszystkie właściwości przycisku.
Zawiera wszystkie właściwości z: MarginStyles, PaddingStyles, BorderStyles, FontStyles, BackgroundStyles, ShadowStyles, OutlineStyles
Obiekt InputStyles
Obiekt opisujący wszystkie właściwości pola input.
Zawiera wszystkie właściwości z: MarginStyles, PaddingStyles, BorderStyles, FontStyles, BackgroundStyles, OutlineStyles
Obiekt SelectStyles
Obiekt opisujący wszystkie właściwości elementu select.
Zawiera wszystkie właściwości z: MarginStyles, PaddingStyles, BorderStyles, FontStyles, BackgroundStyles, OutlineStyles oraz:
iconColorColorString
Kolor ikony elementu select.
Obiekt CheckboxStyles
Obiekt opisujący wszystkie właściwości elementu checkbox.
Zawiera wszystkie właściwości z: MarginStyles, PaddingStyles, FontStyles, OutlineStyles oraz:
iconColorColorString
Kolor ikony elementu checkbox.
Obiekt RadioStyles
Obiekt opisujący wszystkie właściwości elementu radio.
Zawiera wszystkie właściwości z: MarginStyles, PaddingStyles, FontStyles, OutlineStyles oraz:
iconColorColorString
Kolor ikony elementu radio.
Obiekt TypographyStyles
Obiekt opisujący wszystkie właściwości typografii.
Zawiera wszystkie właściwości z: MarginStyles, PaddingStyles, BorderStyles, FontStyles, OutlineStyles.
Obiekt MarginStyles
marginLengthString
Właściwość margin.
marginLeftLengthString
Właściwość margin-left.
marginRightLengthString
Właściwość margin-right.
marginTopLengthString
Właściwość margin-top.
marginBottomLengthString
Właściwość margin-bottom.
Obiekt PaddingStyles
paddingLengthString
Właściwość padding.
paddingLeftLengthString
Właściwość padding-left.
paddingRightLengthString
Właściwość padding-right.
paddingTopLengthString
Właściwość padding-top.
paddingBottomLengthString
Właściwość padding-bottom.
Obiekt BorderStyles
borderRadiusstring
Właściwość border-radius.
borderSingleBorderStyles
Właściwość border.
borderLeftSingleBorderStyles
Właściwość border-left.
borderRightSingleBorderStyles
Właściwość border-right.
borderTopSingleBorderStyles
Właściwość border-top.
borderBottomSingleBorderStyles
Właściwość border-bottom.
Obiekt SingleBorderStyles
widthLengthString
Szerokość obramowania (border width).
stylestring
Styl obramowania (border style).
Wartość jedna z: "dotted", "dashed", "solid"
colorColorString
Kolor obramowania (border color).
Obiekt FontStyles
fontFamilystring
Rodzina czcionek.
Maksymalna długość: 150 znaków. Dozwolone znaki: 0-9a-z-\s,"'
fontColorColorString
Kolor czcionki.
fontSizeLengthString
Rozmiar czcionki.
fontWeightFontWeightValue
Grubość czcionki.
lineHeightLengthString
Wysokość linii.
letterSpacingLengthString
Odstęp między literami (letter spacing).
textDecorationstring
Dekoracja tekstu (text-decoration).
Wartość jedna z: "none", "underline", "overline", "line-through"
textAlignstring
Wyrównanie tekstu (text-align).
Wartość jedna z: "left", "right", "center", "justify", "start", "end"
Obiekt BackgroundStyles
backgroundColorColorString
Kolor tła (background-color).
Obiekt ShadowStyles
boxShadowobject
Cień (box-shadow).
offsetXLengthString
Przesunięcie cienia w osi X.
offsetYLengthString
Przesunięcie cienia w osi Y.
blurRadiusLengthString
Promień rozmycia cienia.
spreadRadiusLengthString
Promień rozprzestrzeniania cienia.
colorColorString
Kolor cienia.
Obiekt OutlineStyles
outlineBorderStyles
Właściwość outline.
outlineOffsetLengthString
Przesunięcie outline (outline-offset).

Zdarzenia​

Aplikacja emituje zdarzenia, do których można dołączyć własną funkcję zwrotną za pomocą metody on.

Zdarzenie ready
Zdarzenie to jest emitowane po wywołaniu metody render, gdy aplikacja zostanie wyświetlona.
Zdarzenie completed
Wyemitowane, gdy płatnik zakończy proces w aplikacji. Funkcja zwrotna dołączona do tego zdarzenia otrzymuje jeden parametr, którym jest obiekt zawierający informacje o wyniku. Zawartość tego obiektu jest różna w zależności od tego, czy płatnik użył numeru karty, czy użył zapisanej karty z portfela Click to Pay.
Obiekt wyniku
PoleOpis
type
Typ odpowiedzi:
  • cardToken - w przypadku gdy płatnik użył numeru karty.
  • clickToPay - w przypadku gdy płatnik użył karty z Click to Pay.
details
Obiekt zawierający szczegółowe dane odpowiedzi.
Szczegóły wyniku - obiekt details
PoleOpisTylko dla
brand
Rodzaj wybranej karty: visa lub mastercard.
panLastFour
Ostatnie 4 znaki numeru karty.
panExpirationMonth
Miesiąc daty ważności karty
panExpirationYear
Rok daty ważności karty
token
Token karty.
Użyj tego tokena do wykonania płatności.
cardToken
artUri
Parametr opcjonalny. Zawiera adres url do obrazka karty.
clickToPay
srcDigitalCardId
Identyfikator karty w Click to Pay.
Użyj tego identyfikatora do wykonania płatności.
clickToPay
srcCorrelationId
Identyfikator transakcji w Click to Pay.
Użyj tego identyfikatora do wykonania płatności.
clickToPay

Poniższy przykład zawiera testowe dane.

{
    "type": "cardToken",
    "details": {
        "brand": "visa",
        "panLastFour": "1111",
        "panExpirationMonth": "02",
        "panExpirationYear": "2029",
        "token": "TOKD_1LOQUV5MMRNX70i7UXXXXXXXXX"
    }
}

Na tej stronie