Przejdź do głównej zawartości

Widget kredytowy

W celu poinformowania klienta o możliwościach płatności kredytowej dla konkretnego produktu, zalecamy umieszczenie widgetu kredytowego przy produktach w listach produktów, opisie (szczegółach) wybranego produktu, koszyku i przy finalizacji zamówienia (przed płatnością).

Widget kredytowy pozwala na prezentowanie szczegółowych informacji o możliwości zapłaty za pomocą płatności ratalnych (PayU | Raty) oraz płatności PayU Płacę później. Klient otrzyma informację o dostępnych opcjach kredytowania zakupu, liczbie rat, oprocentowaniu, czy czasie na spłatę w przypadku płatności PayU Płacę później.

W przypadku listy produktów (kilka widgetów kredytowych na stronie) należy pamiętać o unikalnych identyfikatorach dla widgetów. Dobrym rozwiązaniem jest uzależnienie id od id produktu np. dla produktu o id="3241" id="installment-mini-3241"

Aby umieścić widżet na swojej stronie internetowej:

  1. Otwórz kod źródłowy strony.
  2. Wklej poniższy skrypt w sekcji <head>.
    <meta charset="utf-8" />
    <script src="https://static.payu.com/res/v2/widget-mini-installments.js"></script>
    Uważaj

    Nie kopiuj pliku na swój serwer, ponieważ skrypty PayU zawierają właściwe informacje na temat aktualnych ustawień dotyczących pożyczek. W przypadku wysyłania nagłówków content-security-policy do listy dozwolonych domen należy dodać static.payu.com, credit-widget-config.payu.com oraz secure.payu.com

  3. Wklej poniższy kod, po wcześniejszej edycji pól creditAmount, posId (tu wpisz swoje dane) i key (tu wpisz swoje dane) w sekcji <body> pliku źródlowego.
    <p><span id="installment-mini"></span></p>
    <script type="text/javascript">
    var value = 1234.56
    var options = {
    creditAmount: value, // wartość jako number (w PLN)
    posId: '00000', // identyfikator punktu płatności
    key: 'a0', // pierwsze dwa znaki klucza api
    showLongDescription: true,
    }
    OpenPayU.Installments.miniInstallment('#installment-mini', options)
    .then(function (result) {
    // Ten fragment kodu zostanie wykonany po pokazaniu widgetu
    // Opis obiektu 'result' znajduje się w pkt. 2.3.2 Dodatkowe sposoby integracji widgetu
    })
    .catch(function (e) {
    console.error(e.toString()) // Wypisanie błędów konfiguracji na konsolę
    })
    </script>
    Parametry dostępne dla panelu
    ParametrDomyślna wartośćWymagalnośćOpis
    creditAmount
    none
    tak
    Wartość zakupu, kwota powinna być we właściwym przedziale – sprawdź zakres na stronie Metody płatności Raty i Płacę później. Gdy kwota jest spoza przedziału widget nie wyświetli się.
    posId
    none
    tak
    Identyfikator punktu płatności posId. Identyfikator składa się z samych cyfr.
    key
    none
    tak
    Klucz definiowany w zależności od rodzaju punktu płatności. Klucz składa się z cyfr oraz liter a-f. Dla:
    • REST API - pierwsze dwa znaki klucza Protokół OAuth - client_secret
    • Classic API - pierwsze dwa znaki klucza Klucz (MD5)
    showLongDescription
    false
    nie
    Pozwala na dodnie opisu przed wyświetlaną kwotą. W zależności od dostępnych produktów kredytowych może zostać wyświetlony tekst:
    • Rata 0% już od
    • Rata już od
    • Zapłać później
    Rekomenduje się ustawienie parametru z wartością true. W przypadku zmian globalnych parametrów produktów kredytowych opis zostanie wtedy automatycznie zaktualizowany.
    currencySign
    PLN
    nie
    Waluta, wartości dopuszczalne PLN, CZK.
    lang
    pl
    nie
    Język używany w komponencie. Wartości dopuszczalne: en, pl, cs.
    excludedPayTypes
    []
    nie
    Lista metod płatności, które mają zostać pominięte w trakcie prezentacji widgetu. Należy podawać wartości z pierwszej kolumny tabeli w sekcji Metody płatności Raty i Płacę później.
    Rekomenduje się pozostawienie pustej listy i wykluczanie metod w wyjątkowych przypadkach, Widget automatycznie filtruje metody płatności na podstawie metod włączonych na punkcie płatności.
  4. Zapisz zmiany.
  5. Odśwież stronę w przeglądarce.
Notatka

Jeśli zmiany nie są widoczne w przeglądarce pomimo odświeżenia strony, być może trzeba wyczyścić cache lub należy sprawdzić, czy kwota znajduje się we właściwym przedziale – sprawdź zakres kwot w sekcji Metody płatności Raty i Płacę Poźniej.

Wizualizacja widgetu

  1. Domyślnie widżet wyświetla możliwie najniższą kwotę raty 0% (wraz z walutą) oferowaną przez Raty PayU, o ile taka forma finansowania jest dostępna. W przypadku braku rat 0%, widżet pokazuje możliwie najniższą kwotę raty z marżą (również wraz z walutą). Jeśli metoda Raty PayU nie jest dostępna, wyświetlana jest kwota do spłaty w ramach usługi PayU Płacę Później. Domyślnie wszystkie te kwoty mają kolor niebieski: rgb(29, 175, 236).
  2. Aby zastosować specyficzne stylowanie widgetu należy w pliku CSS dodać wpis, który nadpisuje domyślne wartości. Przykładowo dla zmiany koloru, można zastosować poniższy fragment styli css:
Nadpisanie selektora css
payu-mini-installments-widget-details {
color: black !important;
}
  1. W przypadku zastosowania opcji showLongDescription: true widget pokazuje tekst "Rata już od: 50,36 zł." lub ”Zapłać póżniej: 320,00 zł”. W tym przypadku można osobno ostylować tekst (klasa payu-mini-installments-widget-details), separator (klasa payu-mini-installments-widget-separator) oraz kwotę (klasa payu-mini-installments-widget-amount).
  2. Niezależnie od zastosowania opcji showLongDescription, całość widgetu opakowana jest w element oznaczony klasą payu-mini-installments-widget, który również można ostylować.

Dodatkowe sposoby integracji widgetu

Funkcja OpenPayu.Installments.miniInstallment zwraca obiekt Promise z wartością result.

Parametry obiektu result
ParametrTypWymagalnośćOpis
isWidgetAvailable
boolean
tak
Przyjmuje wartość true, gdy parametry wejściowe pozwalają na wyświetlenie widżetu. W przeciwnym razie false, gdy np. kwota kredytu jest poza prawidłowym zakresem - sprawdź obowiązujący zakres w sekcji Metody płatności Raty i Płacę później.
element
HTMLElement
dostępne dla isWidgetAvailable = true
Element DOM zawierający tekst z kwotą raty lub kwotą dla metody PayU Płacę później i link otwierający wyskakujące okienko ze szczegółami.
openWidget
function
dostępne dla isWidgetAvailable = true
Funkcja wyświetla wyskakujące okienko ze szczegółami metod spłaty.

Wykorzystanie obiektu element

Przykład użycia obiektu element
<p><span id="installment-mini"></span></p>
<script type="text/javascript">
var value = 1234.56
var options = {
creditAmount: value, // wartość jako number (w PLN)
posId: '00000', // identyfikator punktu płatności
key: 'a0', // pierwsze dwa znaki klucza api
showLongDescription: false,
}
OpenPayU.Installments.miniInstallment('', options) // selektor nie jest wymagany
.then(function (result) {
if (result.isWidgetAvailable) {
// sprawdzenie czy widget jest dostępny
const customText = document.createElement('span')
customText.innerText = 'Raty PayU już od: '
document.getElementById('installment-mini').append(customText)
document.getElementById('installment-mini').append(result.element) // element można dołączyć do dowolnego miejsca na stronie
}
})
.catch(function (e) {
console.error(e.toString()) // Wypisanie błędów konfiguracji na konsolę
})
</script>

Szczegóły obiektu element:

  • Po wywołaniu funkcji OpenPayU.Installments.miniInstallment('', options) oraz dodaniu obsługi obiektu Promise otrzymasz dostęp do obiektu element, który jest elementem DOM z kowtą spłaty oraz linkiem otwierającym okienko ze szczegółami metod spłaty.
  • Obiekt element jest dostępny także, gdy do funkcji został przekazany pusty selektor (undefined, null lub ""). W tym przypadku samodzielnie obsłuż dodanie elementu do strony.
  • Obiekt element jest dostępny, gdy parametr isWidgetAvailable ma wartość true. Przed wykorzystaniem obiektu sprawdź, czy warunek jest spełniony.
  • Dobrą praktyką jest ukrycie wszystkich elementów strony, które są związane z wyświetleniem widgetu w przypadku, gdy parametr isWidgetAvailable ma wartość false.

Manualne otwarcie popup ze szczegółami metod spłaty

Przykładowy kod umożliwiający otwieranie popupu po kliknięciu na grafikę
<img
id="payuLogo"
src="https://poland.payu.com/wp-content/themes/global-website/assets/src/images/payu-logo.svg"
hidden
/>
<script>
var options = { creditAmount: 2200, posId: '00000', key: 'a0' }
window.OpenPayU.Installments.miniInstallment('', options)
.then(function (result) {
if (result.isWidgetAvailable) {
document.querySelector('#payuLogo').removeAttribute('hidden') // wyświetla element
document.querySelector('#payuLogo').onclick = function () {
result.openWidget()
} // dodaje akcję na kliknięcie
}
})
.catch(function (e) {
console.error(e.toString())
})
</script>

Szczegóły funkcji openWidget():

  • Po wywołaniu funkcji OpenPayU.Installments.miniInstallment('', options) oraz dodaniu obsługi obiektu Promise otrzymamy dostęp do funkcji openWidget(), która umożliwia otwarcie popupu.
  • Funkcja openWidget() jest dostępna, gdy parametr isWidgetAvailable ma wartość true. Przed wywołaniem funkcji sprawdź, czy warunek jest spełniony.
  • Dobrą praktyką jest ukrycie elementu, do którego przypisujesz funkcję openWidget(), gdy widget nie jest dostępny (parametr isWidgetAvailable ma wartość false).
  • Jeżeli nie zależy Ci na prezentacji kwoty, a jedynie na pokazaniu popupu ze szczegółami rat, mozesz przekazać pusty selektor (undefined, null lub "").

FAQ

Po dodaniu kodu na stronie, wyświetla się pusta strona.

Podczas modyfikacji kodu została uszkodzona struktura pliku HTML w wyniku czego strona działa częściowo lub wcale (pusty ekran). Plik HTML jest ustrukturyzowanym plikiem, który musi zachować właściwy format.

Po dodaniu kodu na stronie, nie widzę żadnych zmian, widgeta nie widać.

Prawdopodbnymi przyczynami są:

  • Kwota nie znajduje się we właściwym przedziale – zobacz zakres kwot w sekcji Metody płatności Raty i Płacę później.
  • Sprawdź czy nie widać widgetu na dole strony. Jeśli widget jest widoczny na stronie (ale w złej lokalizacji) patrz punkt 3.
  • Sprawdź, czy nie występują błędy walidacji konfiguracji widżetu. Są one logowane do konsoli w przeglądarce internetowej.
  • Kod z backendu (np. z PHP) został wklejony do stony HTML, należyto poprawić.
  • Widget składa się z trzech elementów: link do naszego skryptu (w tagu head), tag HTML z widgetem (w tagu body), kod wykonujący funkcję Javascript. Prawdopodobnie na stronie zabrakło któregoś z tych elementów.
  • Na liście produktów widget należy dodać przy każdym z produktów.

Widget wyświetla się, ale w złym miejscu.

Należy odnaleźć na stronie element (prawdopodobnie z ceną) pod którym ma być umieszczona informacja o możliwościach spłaty i tam przenieść tag HTML.

Widget wyświetla błędne dane.

Prawdopodobnymi przyczynami są:

  • Dodanie właściwych kodów, we właściwych miejscach, tylko do widgeta została przekazana błędna kwota.
  • Na stronie istnieją tagi HTML o zduplikowanych identyfikatorach (id).

Na jakich stronach warto umieścić widget?

Rekomendujemy umieszcze widgetu na:

  • Opis/karta produktu,
  • Lista produktów -dla każdego produktu odrębny widge. Należy uważać żeby każdy widget miał unikalne id (np. id="installment-mini-2903" następny np. id="installment-mini-2821"),
  • Koszyk,
  • Checkout – finalizacja zamówienia.

Gdzie mam znaleźć POS_ID i KEY?

W instrukcji instalacji widgeta, pewne dane wskazane w kodzie html są przykładowe i należy w ich miejsce podstawić swoje dane. Są to np. POS_ID i KEY.

  • Zaloguj się do panelu menedżerskiego.
  • Wybierz Moje sklepy.
  • Wybierz punkt płatności w wybranym sklepie - kliknij odpowiedni punkt płatnosci. Po kliknięciu pojawi się strona z ramką, z danymi:
    • POS_ID składa się z samych cyfr
    • Cały klucz ukazany w panelu menedżerskim (pod nazwą Protokół OAuth – client_secret lub w przypadku jego braku - Drugi klucz (MD5)) składa się z 32 znaków (cyfr lub małych liter a-f). Wymagane są tylko i wyłącznie pierwsze dwa znaki klucza.

Korzystam z tzw. systemu pudełkowego. Czy widget u mnie zadziała?

Aby widget zadziałał, potrzebna jest zmiana kodu źródłowego strony, zgodnie z instrukcją. W przypadku niektórych systemów pudełkowych modyfikacja kodu może być utrudniona. W takim przypadku, skontaktuj się z dostawcą oprogramowania.

  • Jeśli korzystasz z PrestaShop, nie musisz osobno instalować widgetu, PayU udostępnia oficjalny plugin do PrestaShop z opcją promowania kredytowych metod płatności, którego częścią jest widget. Zalecana wersja pluginu do PrestaShop to przynajmniej 3.1.14. Jeśli wykorzystujesz starszą wersję, zalecamy uaktualnienie pluginu.
  • Jeśli korzystasz z WooCommerce nie musisz osobno instalować widgetu, PayU udostępnia oficjalny plugin do Woocomerce z opcją promowania kredytowych metod płatności, którego częścią jest widget.