Erämaksulaskuri (Part payment widget)

Verkkokaupan sivuille lisättävällä erämaksulaskurilla ostaja voi kätevästi vertailla erilaisia maksusuunnitelmia, ja voit näyttää tuotesivulla alkaen-hinnan. Voit myös lisätä erämaksulaskurin ostoskoriin, jolloin ostaja voi suunnitella maksuaikataulua etukäteen ennen maksamiseen siirtymistä.

Palveluun kuuluva erämaksulaskuri tekee asiakkaalle sopivan maksusuunnitelman löytämisestä helppoa ja voi auttaa ostopäätöksen tekemisessä sekä kasvattaa keskiostosta, kun asiakkaasi saa joustavasti maksuaikaa hankinnoilleen.

Erämaksulaskurin voi luoda kahdella vaihtoehtoisella tavalla: joko Extranetin Materiaalit-välilehdellä tai voit luoda scriptin tältä sivulta löytyvän ohjeen mukaan. Alla ohjeistetaan molemmat tavat.

1 Erämaksulaskurin luominen Extranetissä
- 1.1 Asetukset
- 1.2 Ulkoasu
- 1.3 Tekstit
- 1.4 HTML-script verkkokaupan sivuille
- 1.5 Tuotteen hinta erämaksulaskurissa
2 Erämaksulaskurin scriptin luominen
3 API
4 Rakenna dynaamisesti erämaksulaskurin scripti
- 4.1 Example of Dynamically constructing Part Payment Calculator script for a product in Shopify

Erämaksulaskurin luominen Extranetissä

Voit generoida haluamasi näköisen erämaksulaskurin Extranetissä määrittelemällä laskurin ominaisuudet ja sen jälkeen kopioimalla scriptin verkkokaupan sivuille. Erämaksulaskuri hakee verkkokaupan palvelun tiedot kauppiastunnuksella rajapinnasta ja näyttää mm. kyseiselle palvelulle aktivoidut kampanjat. Uudessa Extranetissä Materiaalit-välilehdellä voi erämaksulaskurin asetuksissa määritellä mm. värit, laskurin tyylin, tekstejä ja oletusmaksuajan.

Erämaksulaskuri luo ja päivittää scriptiä tekemiesi määrittelyjen mukaisesti ja näyttää sivulla koko ajan erämaksulaskurin esikatselun.

Asetukset

Erämaksulaskurin asetuksissa voit määritellä, haluatko erämaksulaskurista kokonaisen vai mini-version. Voit myös asettaa hinnan esimerkinomaisesti. Varsinainen tuotteen hinta välitetään verkkokaupasta data-price parametrina, tai hinta-kentän voi jättää tyhjäksi. Lue lisää tästä: Erämaksulaskuri (Part payment widget) | Tuotteen hinta erämaksulaskurissa

Voit halutessasi asettaa myös oletusmaksuajalle hintarajoja. Tämä tarkoittaa sitä, minkä maksuajan laskuri näyttää oletuksena tietyille hinnoille. Esimerkiksi tässä 50 euron ja yli tuotteille näytetään oletuksena 3 kuukauden maksuaika, 500 euron ja yli tuotteille näytetään oletuksena 6 kuukauden maksuaika ja 1500 euron ja yli tuotteille näytetään oletuksena 24 kuukauden maksuaika:

Mikäli et aseta hintarajoja, näyttää erämaksulaskuri oletuksena aina pisimmän maksuajan eli alkaen-hinnan.

Ulkoasu

Ulkoasu-parametreilla voit asettaa laskuriin haluamasi värit ja reunaviivan tyylin:

Tekstit

Lisäksi voit määritellä erämaksulaskurissa näytettävät tekstit erilaisissa tilanteissa.

Aluksi voit määritellä erämaksulaskurin kielen. Vaihtoehdot ovat suomi, ruotsi ja englanti. Voit luoda vaikka useamman laskurin eri kielillä, jos tarpeen.
Seuraavissa kohdissa voit määritellä ns. fallback-tekstit eri kielillä. Tämä teksti näytetään, jos esimerkiksi tuotteen hinta ei osu erämaksulle määriteltyjen minimi- ja maksimirajojen sisään, eikä laskuria voida näyttää.
Voit myös määritellä kampanjatekstit eri kielillä. Tämä on teksti, joka näytetään erämaksulaskurin yläosassa

Erämaksulaskuri_Extranet_kampanjateksti.PNG

tässä esimerkissä teksti “Tämä on kampanjateksti”

HTML-script verkkokaupan sivuille

Kun olet tehnyt haluamasi määrittelyt erämaksulaskurille, tuloksena syntyy HTML-script jonka voit kopioida ja käyttää verkkokaupan sivuilla. Näet esikatselun sivulla koko ajan, joten voit tarvittaessa muokata ja kokeilla erilaisia asetuksia ja määrittelyjä. Esimerkiksi:

Tässä esimerkissä tuotteen hinta on 200 €, laskuriin on asetettu oletusmaksuaikoja eri summille, sekä fallback-teksti ja kampanjateksti.

Tuotteen hinta erämaksulaskurissa

Tuotteen hinta, tai ostoskorin hinta jos laskuria käytetään kassalla/ostoskorissa, tulee välittää verkkokaupasta data-price parametrina, tai vaihtoehtoisesti data-price kentän voi jättää tyhjäksi, jolloin käyttäjä voi itse täyttää laskuriin haluamansa summan ja esimerkiksi vertailla maksusuunnitelmia erilaisille summille. Tällöin laskurissa on hinnan sijaan syöttökenttä, johon käyttäjä voi syöttää haluamansa summan.

Erämaksulaskuri_Extranet_ilmanhintaa.PNG

Javascriptin avulla laskurin summaa voi myös päivittää mikäli käyttäjä muuttaa tuotesivulla tuotteiden kappalemäärää ja haluaa nähdä maksusuunnitelmat niiden yhteissummalle, tai jos käytät laskuria ostoskorissa ja ostoskorin summa muuttuu.
Hinta- ja maksusuunnitelmalaskelmat voidaan päivittää ohjelmallisesti lähettämällä javascript-tapahtuma "svea-partpayment-calculator-update-price", jonka detail ominaisuuteen on lisätty price arvo.

Esimerkki:
document.dispatchEvent(new CustomEvent("svea-partpayment-calculator-update-price", { "detail": { "price": "123.45" } }));

Erämaksulaskurin scriptin luominen

Jos et luo erämaksulaskurin “pohjaa” Extranetissä, niin voit halutessasi käyttää alla olevaa ohjetta erämaksulaskurin luomiseen.
Scriptiin voi määritellä seuraavat arvot (punaiset ovat pakollisia, vihreät vaihtoehtoisia), arvojen tulee olla lainausmerkeissä:

src= host-osoite: "https://payments.maksuturva.fi/tools/partpayment/partPayment.js"
class= "svea-pp-widget-part-payment"
data-sellerid= ko. verkkokaupan Svea Payments -palvelun seller id
data-layout= voit määritellä käytettäväksi laskurin miniversion, joka näyttää tarvittavat tiedot pienemmässä tilassa, mutta ei ole brändättävissä omilla väreillä. Jos haluat käyttää miniversiota, aseta tähän arvo "mini".
data-price= tuotteen hinta, joka välitetään laskuriin kaupasta.
- Kentän voi jättää myös tyhjäksi, eli tämä arvo ei ole pakollinen - jos arvoa ei ole annettu, laskuri näyttää hinnan syöttökentän, johon käyttäjä voi syöttää haluamansa summan ja vertailla sille maksuaikoja.
data-locale= laskurin kieli, vaihtoehdot "fi" (suomi) / "sv" (ruotsi) / "en" (englanti)
data-country= muuttaa laskurin valuuttaa ja osoitetta, vaihtoehdot "SE" (ruotsi) / "NO" (norja).
data-border-radius= reunaviivan paksuus pikseleinä, esim. "12px"
data-active-color= aktiivisen tekstin väri HEX-värikoodina, esim. "#00AECE"
data-text-color= tekstin väri HEX-värikoodina, esim. "#212121"
data-highlight-color= korostusväri HEX-värikoodina, esim. "#002C50"
data-border-color= reunaviivan väri HEX-värikoodina, esim. "#DEE1EC"
data-campaign-text-fi= kampanjateksti suomeksi, joka näkyy laskurin yläreunassa.
- Muut kielivaihtoehdot ovat data-campaign-text-sv (ruotsi) / data-campaign-text-en (englanti)
data-fallback-text-fi= teksti, joka näkyy virhetilanteessa.
- Muut kielivaihtoehdot ovat data-fallback-text-sv (ruotsi) / data-fallback-text-en (englanti)
data-threshold-prices= voit määritellä, mikä maksuaika/kampanja näytetään oletusarvoisesti eri hinnoilla.
- Esimerkiksi asetus "[[500, 6], [1000, 12], [1500, 24]]" tarkoittaa, että yli 500 euron tuotteilla näytetään oletusarvoisesti 6 kk maksuaika, yli 1000 euron tuotteilla 12 kk maksuaika, yli 1500 euron tuotteilla 24 kk maksuaika.
- Jos haluat että yllä esimerkissä olevat oletusmaksuajat näytetään esimerkiksi 500 euron ja sen yli menevillä tuotteilla, 1000 euron ja sen yli menevillä tuotteilla sekä 1500 euron ja sen yli menevillä tuotteilla, tulee hinnat määritellä näin (euron pienemmiksi): "[[499, 6], [999, 12], [1499, 24]]"
data-maksuturva-host= määrittää mistä osoitteesta haetaan erämaksu suunnitelmat. Tuotanossa ei pakollinen, mutta testiympäristössä tarpeellinen ("https://test1.maksuturva.fi").

Esimerkki, korvaa arvot sopivilla (väriarvoja voidaan käyttää sellaisenaan, jos verkkokauppa ei halua käyttää omia värejä):

<script
  src="https://payments.maksuturva.fi/tools/partpayment/partPayment.js"
  class="svea-pp-widget-part-payment"
  data-sellerid="<insertsellerid>"
  data-layout="mini"
  data-price="<priceparameterfromstore>"
  data-threshold-prices="[[price, month]]"
  data-active-color="#00AECE"
  data-text-color="#00325C"
  data-highlight-color="#00325C"
  data-border-color="#CCEEF5"
  data-border-radius="4"
  data-locale="fi"
  data-fallback-text-fi="<inserttext>"
  data-campaign-text-fi="<inserttext>"
></script>

You can define values in the script (red are mandatory, green are optional), the values must be in quotes:

src= host address: "https://payments.maksuturva.fi/tools/partpayment/partPayment.js"
class= "svea-pp-widget-part-payment"
data-sellerid= The seller ID of the respective online store's Svea Payments service
data-layout= You can define the use of the calculator's mini version, which displays the necessary information in a smaller space but cannot be branded with custom colors. If you want to use the mini version, set this value to "mini".
data-price= The product price, which is passed to the calculator from the store.
- The field can also be left empty, meaning this value is not mandatory—if no value is given, the calculator displays a price input field where the user can enter their desired amount and compare payment terms for it.
data-locale= The calculator's language, options: "fi" (Finnish) / "sv" (Swedish) / "en" (English)
data-country= Changes the calculator's currency and address, options: "SE" (Sweden) / "NO" (Norway).
data-border-radius= The border radius in pixels, e.g., "12px"
data-active-color= The color of active text in HEX color code, e.g., "#00AECE"
data-text-color= The text color in HEX color code, e.g., "#212121"
data-highlight-color= The highlight color in HEX color code, e.g., "#002C50"
data-border-color= The border color in HEX color code, e.g., "#DEE1EC"
data-campaign-text-fi= The campaign text in Finnish, which appears at the top of the calculator.
- Other language options: data-campaign-text-sv (Swedish) / data-campaign-text-en (English)
data-fallback-text-fi= The text displayed in case of an error.
- Other language options: data-fallback-text-sv (Swedish) / data-fallback-text-en (English)
data-threshold-prices= You can define which payment term/campaign is shown by default for different price ranges.
- For example, the setting "[[500, 6], [1000, 12], [1500, 24]]" means that products over 500 euros will default to a 6-month payment term, products over 1000 euros to a 12-month term, and products over 1500 euros to a 24-month term.
- If you want the default payment terms in the example above to apply to products priced at 500 euros and above, 1000 euros and above, and 1500 euros and above, the prices should be defined as follows (1 euro less): "[[499, 6], [999, 12], [1499, 24]]".
data-maksuturva-host= Specifies the address from which the installment payment plans are retrieved. Not mandatory in production but required in the test environment ("https://test1.maksuturva.fi").

API

Rekisteröi ylä-tason vakio SveaPartPayment.
Käytettävissä olevat metodit:

initializeWidgets(onSuccess): Alustaa widgetit uudelleen, esimerkiksi uuden sisällön lataamisen jälkeen AJAXin avulla. Ottaa vastaan palautefunktion, joka kutsutaan, kun kaikki widgetit on alustettu.

Registers top-level constant SveaPartPayment.
Available methods:

initializeWidgets(onSuccess): Re-initialized widgets for example after loading new content with AJAX. Takes a callback function which is called after all the widgets have been initialized.

Rakenna dynaamisesti erämaksulaskurin scripti

Tilanteissa, joissa hintaa ei ole saatavilla API:sta tai taustajärjestelmästä (esimerkiksi Shopify).

Käyttää JavaScriptiä luomaan ja lisäämään mukautetun <script> -elementin erämaksulaskurille DOM:iin.
Hakee hinnan meta-ominaisuudesta (tässä esimerkissä: <meta property="og:price:amount" content="...">). Hinnan voi myös hakea mistä tahansa muusta HTML-elementistä - mukauta vain var price_selector = document.querySelector(...); -funktiokutsua osoittamaan oikeaan elementtiin.
Hakee määrän kentästä (tässä esimerkissä: <input name="quantity" type="number" value="...">). Määrän voi myös hakea mistä tahansa muusta HTML-elementistä - mukauta vain var qty_selector = document.querySelector(...); -funktiokutsua osoittamaan oikeaan elementtiin. Lisäksi lisätään tapahtumakuuntelija muutoksille määräkenttään, jotta hinta lasketaan uudelleen määrän muuttuessa.
Erämaksulaskurin skripti voidaan lisätä mihin tahansa osaan DOM:ia / näyttää missä tahansa HTML-sivulla. Katso // Section 3 - Insert Part Payment Calculator -osio lähdekoodista esimerkkiä varten. Tämä esimerkki lisää sen "product-form"-elementin jälkeen.

KÄYTTÖ:

Lisää lähdekoodista  ja  -välille kenttään, johon voit lisätä raakaa HTML-koodia - esimerkiksi tuotteen kuvauskenttään Shopifyssa.
Mukauta var price_selector = document.querySelector(...); -funktiokutsua osoittamaan hintaelementtiin. Varmista, että haettu hintatieto sisältää vain numeroita (ilman valuuttasymboleja tai muita merkkejä).
Jos määrä on käytössä, mukauta var qty_selector = document.querySelector(...); -funktiokutsua osoittamaan määräkenttään.
Mukauta // Section 3 - Insert Part Payment Calculator -osio lisäämään erämaksulaskurin skripti oikeaan kohtaan sivulla.

For situations where access to price from API / backend, etc. is not available (for example Shopify).

Uses javascript to create and append a custom <script> element for the Part Payment Calculator onto the DOM.
Fetches the price from a meta property (in this example, from: <meta property="og:price:amount" content="..."> Can also fetch the quantity from any other HTML element - just customize the var price_selector = document.querySelector(...); function call to point to the correct element.
Fetches the quantity from a field (in this example, from: <input name="quantity" type="number" value="..."> Can also fetch the quantity from any other HTML element - just customize the var qty_selector = document.querySelector(...); function call to point to the correct element. Also, injects a change event listener to the quantity field, so that the price is recalculated when the quantity field value is changed.
The Part Payment Calculator script can be appended to any part of the DOM / shown on any part of the HTML page. See the // Section 3 - Insert Part Payment Calculator section in the source code for an example. This current example appends it after the "product-form" element.

USAGE:

Insert the <script> from the source code between  and  into a field where you can insert raw html - for example, the product description field in Shopify.
Customize the var price_selector = document.querySelector(...); function call to point to the price element. Make sure the fetched price value only contains numbers (without currency symbols or anything else).
If quantity is present, customize the var qty_selector = document.querySelector(...); function call to point to the quantity element.
Customize the // Section 3 - Insert Part Payment Calculator section to append the Part Payment Calculator script to the correct position on the page.

Example of Dynamically constructing Part Payment Calculator script for a product in Shopify

<!-- // Part Payment Calculator - create element - BEGIN -->
<script>
// Section 1 - Selectors to get: price (from the meta property in the page source)
//                               quantity (from a field)
var price_selector = document.querySelector('meta[property="og:price:amount"]').content;
var qty_selector = document.querySelector('[name="quantity"]');

// Change event listener to calculate total price when quantity is changed
if (qty_selector) {
  qty_selector.addEventListener("change", (e) => {
    var pp_price = "" + calculatePPTotalPrice();
    document.dispatchEvent(new CustomEvent("svea-partpayment-calculator-update-price", { "detail": { "price": pp_price } }));
  }, false);
}

function calculatePPTotalPrice() {
  var pp_price = price_selector;
  pp_price = parseFloat(preformatFloat(pp_price));

  // If quantity exists, multiply price with it
  if (qty_selector) {
    var pp_qty = qty_selector.value;
    if (pp_qty)
      pp_price = parseFloat(pp_price * preformatFloat(pp_qty));

  }

  return pp_price;
}

function preformatFloat(e){if(!e)return"";let r=e.indexOf(",");if(-1===r)return e;let t=e.indexOf(".");return -1===t?e.replace(/\,/g,"."):r<t?e.replace(/\,/g,""):e.replace(/\./g,"").replace(",",".")}

function generatePPCalculator() {
  var pp_price = calculatePPTotalPrice();

  // Section 2 - create Part Payment Calculator Script
  const sppScript = document.createElement("script");
  sppScript.src = "https://payments.maksuturva.fi/tools/partpayment/partPayment.js";
  sppScript.setAttribute('class', 'svea-pp-widget-part-payment');
  sppScript.setAttribute('data-sellerid', '<instertsellerid>');
  sppScript.setAttribute('data-price', pp_price);
  sppScript.setAttribute('data-locale', 'fi');
  //sppScript.setAttribute('async', '');
  sppScript.onload = () => {
    document.dispatchEvent(new CustomEvent("svea-partpayment-calculator"));
  };
  
  // Section 3 - Insert Part Payment Calculator - after product-form & before description
  var insertElement = document.getElementsByClassName("product-form")[0];
  insertElement.parentNode.append(sppScript);
}

window.onload = generatePPCalculator();
</script>
<!-- // Part Payment Calculator - create element - END -->

Svea Payments Palvelukuvaus