Rajapintakuvaus verkkokaupalle MAKSAMINEN Maksuturvan palveluille

Rajapintakuvaus verkkokaupalle MAKSAMINEN Maksuturvan palveluille Versio 4.1.9

2(15) Sisältö 1. Muutokset... 3 2. Yleistä... 5 3. Maksun välityksen tiedot... 5 3.1 Kenttien selitteet - Maksun välityksen tiedot... 7 3.2 Tilauserittely... 9 3.3 Tilauserittelyn laskentasäännöt... 10 4. Maksun vastaussanoman tiedot... 11 4.1 Vastauksen tietojen tarkistaminen... 11 4.2 Kenttien selitteet - Maksun vastaussanoman tiedot... 11 5. Tarkisteen laskenta... 13 5.1 Vinkkejä tarkisteen laskennan avuksi... 13 6. Kauppiaan sallittujen maksutapojen hakeminen... 14 7. Dynaamisen kuva-aineiston hakeminen... 15

3(15) 1. MUUTOKSET Ajankohta Dokumentin versio Muutos Marraskuu 2010 2.5 Paluusanoman kuvaukseen lisätty pmt_paymentmethod -kentän kuvaus. Helmikuu 2011 4.0 Uusi rajapintaversio: 0004 MAKSUN VÄLITYKSEN TIEDOT (IN): Valinnaiset tiedot pakolliseksi: - pakolliseksi maksun eräpäivä (pmt_duedate) - pakolliseksi virhe-paluuosoite (pmt_errorreturn) - pakolliseksi vastaanottajan nimi (pmt_deliveryname) - pakolliseksi vastaanottajan osoite (pmt_deliveryaddress) - pakolliseksi vastaanottajan posti (pmt_deliverypostalcode) - pakolliseksi tarkisteen laskentamerkistö (pmt_charset) Uusi pakollinen tieto: - pmt_action (NEW_PAYMENT_EXTENDED) - sisään tulevan datan ja verkkokaupan enkoodaus (pmt_charsethttp) Tuki maksutavan esivalinnalle verkkokaupassa: Verkkokaupassa esivalittu maksutapa (pmt_paymentmethod) Tulevien ominaisuuksien tueksi: - pakollinen escrow käytössä (pmt_escrow) - pakollinen escrow valittavissa (pmt_escrowchangeallowed) Kansainvälisten (luottokortti)maksujen tueksi: - pakollinen maksajan kaupunki (pmt_buyercity) - pakollinen maksajan maakoodi (pmt_buyercountry) - pakollinen toimituksen kaupunki (pmt_deliverycity) - pakollinen toimituksen maakoodi (pmt_deliverycountry) Erilaisten rahalaitosten myöntämien luottojen mahdollistamiseksi: - valinnainen parametri, joka kertoo lähettääkö kauppias laskun (pmt_invoicefromseller) - valinnainen ostajan hetu tai y-tunnus (pmt_buyeridentificationcode) - pakollinen tilauserittely: - Tilausrivien lukumäärä (pmt_rows) - Tilausrivin tuotteen nimi (pmt_row_namen) - Tilausrivin tuotteen kuvaus (pmt_row_descn) - Tilausrivin tuotteen määrä (pmt_row_quantityn) - Tilausrivin toimituksen tai palvelun suorituksen ajankohta (pmt_row_deliverydaten) - Tilausrivin tuotteen bruttohinta per yksikkö (ALV mukana) (pmt_row_price_grossn) - Tilausrivin tuotteen nettohinta per yksikkö (ilman ALV:a) (pmt_row_price_netn) - Tilausrivin tuotteeseen sovellettu ALV-prosentti (pmt_row_vatn) - Tilausrivin tyyppi (pmt_row_typen) Pakollinen myyjän tai toimittajan käsittely- ja postikulu: pmt_sellercosts Uusi tarkiste: pmt_action pmt_version pmt_selleriban (vain jos annettu) pmt_id pmt_orderid pmt_reference pmt_duedate pmt_amount pmt_currency pmt_okreturn pmt_errorreturn pmt_cancelreturn pmt_delayedpayreturn pmt_escrow pmt_escrowchangeallowed pmt_invoicefromseller (vain jos annettu) pmt_paymentmethod (vain jos annettu) pmt_buyeridentificationcode (vain jos annettu) pmt_buyername pmt_buyeraddress pmt_buyerpostalcode

4(15) Ajankohta Dokumentin versio Muutos pmt_buyercity pmt_buyercountry pmt_deliveryname pmt_deliveryaddress pmt_deliverypostalcode pmt_deliverycity pmt_deliverycountry pmt_sellercosts pmt_row_* kentät järjestyksessä riveittäin tilausrivi kerrallaan kaikki seuraavat (jos mukana tiedoissa): o pmt_row_namen o pmt_row_descn o pmt_row_quantityn o pmt_row_articlenrn o pmt_row_unitn o pmt_row_deliverydaten o pmt_row_price_grossn o pmt_row_price_netn o pmt_row_vatn o pmt_row_discountpercentagen o pmt_row_typen <salainen avain> MAKSUN VASTAUSSANOMAN TIEDOT (OUT) Valittu maksutapa (pmt_paymentmethod) uudet koodit ja selitteet: - FI70 - Maksuturva-Lasku (luotto- ja rahoituspalvelu) - FI71 - Maksuturva-Osamaksu (luotto- ja rahoituspalvelu) - FI80 - Maksuturva-Paypal - FI90 - Maksuturva-KV-tilisiirto Tulevien ominaisuuksien tueksi: (pmt_escrow) Uusi kenttä: - pmt_action (NEW_PAYMENT_EXTENDED) Uusia kenttiä tarkisteessa: - pmt_action (NEW_PAYMENT_EXTENDED) - pmt_version Toukokuu 2011 4.1 MAKSUN VÄLITYKSEN TIEDOT (IN): Uusia valinnaisia tietoja: - pmt_row_articlenrn tilausrivin tuotteen tuote verkkokaupassa - pmt_row_unitn tilausrivin määrän yksikkö (esim. kg, kpl) Yllä olevat tiedot lisätty myös tarkisteenlaskentaan. Syyskuu 2011 4.1.1 Lisätty - lisätiedot emaksujen integrointiin - ohje sallittujen maksutapojen hakemiseen - ohje maksubannerin hakemiseen. Joulukuu 2011 4.1.2 Lisätty - lisäohjeita hash-laskentaan Maaliskuu 2013 4.1.4 Pidennetty maksajan ja toimitustietojen nimi- ja osoitekenttiä. Kesäkuu 2013 4.1.5 Ei muutoksia Huhtikuu 2014 4.1.6 Lisätty uudet maksutavat: - Maksuturva Lasku - Maksuturva Erämaksu Toukokuu 2014 4.1.7 Lisätty sallittujen maksutapojen hakuun uusi parametri: - totalamount (tilauksen loppusumma) Heinäkuu 2014 4.1.8 Lisätty huomautus toimitusosoitteen paikkansapitävyyden tärkeydestä Elokuu 2014 4.1.9 Korvattu maksutapabannerin haun rajapintakuvaus viittauksella omaan dokumenttiinsa

5(15) 2. YLEISTÄ Tämä rajapintakuvaus mahdollistaa molempien palveluiden sekä Maksuturvan että emaksut-palvelun maksamisen integroinnin. Myös maksubannereiden sekä maksutapojen hauissa voidaan käyttää samoja palvelurajapintoja. 3. MAKSUN VÄLITYKSEN TIEDOT Verkkokauppa välittää maksun tiedot FORM-tietoryhmässä piilomuuttujina. Tiedot lähetetään osoitteeseen https://www.maksuturva.fi/newpaymentextended.pmt Tiedon nimi Arvo Muoto Minimi- P/V input name= value= pituus 1. Toiminnon tunniste pmt_action NEW_PAYMENT_EXTENDED AN50 4 P 2. Sanoman versio pmt_version 0004 AN4 4 P 3. Kauppiaan tunnus pmt_sellerid AN15 P 4. Kauppiaan tili pmt_selleriban AN30 18 V 5. Maksun tunnus pmt_id AN20 P 6. Tilaus pmt_orderid AN50 P 7. Maksun viite pmt_reference N20 4 P 8. Maksun eräpäivä pmt_duedate kuluva päivä muodossa AN10 10 P dd.mm.yyyy 9. Ostajan locale pmt_userlocale fi_fi, sv_fi, en_fi AN5 5 V 10. Maksun rahamäärä pmt_amount AN17 4 P 11. Maksun valuutta pmt_currency EUR AN3 3 P 12. Ok -paluuosoite pmt_okreturn AN200 P 13. Virhe -paluuosoite pmt_errorreturn AN200 P 14. Peruutus -paluuosoite pmt_cancelreturn AN200 P 15. Viivästetty maksu - pmt_delayedpayreturn AN200 P paluuosoite 16. Escrow käytössä pmt_escrow Maksuturva=Y, emaksut=n A1 1 P 17. Escrow valittavissa pmt_escrowchangeallowed N A1 1 P 18. Lähettääkö kauppias pmt_invoicefromseller Y/N A1 1 V laskun 19. Verkkokaupassa esivalittu pmt_paymentmethod Finn AN4 4 V maksutapa 20. Ostajan hetu tai y-tunnus pmt_buyeridentificationcode AN11 9 V 21. Ostajan nimi pmt_buyername AN100 P 22. Ostajan osoite pmt_buyeraddress AN100 P 23. Ostajan posti pmt_buyerpostalcode N20 P 24. Ostajan kaupunki pmt_buyercity AN100 P 25. Ostajan maakoodi (FI, SE, pmt_buyercountry A2 P EN ) 26. Ostajan puheli pmt_buyerphone AN40 V 27. Ostajan sähköposti pmt_buyeremail AN100 V 28. Vastaanottajan nimi pmt_deliveryname AN100 P 29. Vastaanottajan osoite pmt_deliveryaddress AN100 P 30. Vastaanottajan pmt_deliverypostalcode N20 P posti 31. Vastaanottajan kaupunki pmt_deliverycity AN100 P 32. Vastaanottajan maakoodi pmt_deliverycountry A2 P (FI, SE, EN ) 33. Myyjän / toimittajan pmt_sellercosts n,nn AN17 4 P käsittelykulut 34. Tilausrivien lukumäärä pmt_rows N4 1 P 35. Tilausrivin tuotteen nimi pmt_row_namen AN40 1 P 36. Tilausrivin tuotteen pmt_row_descn AN1000 1 P kuvaus 37. Tilausrivin tuotteen pmt_row_quantityn N8 1 P määrä 38. Tilausrivin tuotteen tuote kaupassa pmt_row_articlenrn AN10 0 V

6(15) 39. Tilausrivin määrän yksikkö 40. Tilausrivin toimituksen tai palvelun suorituksen ajankohta 41. Tilausrivin tuotteen bruttohinta per yksikkö (ALV mukana) Tiedon nimi input name= Arvo value= Muoto Minimipituus P/V pmt_row_unitn esim. kg, kpl AN3 0 V pmt_row_deliverydaten dd.mm.yyyy AN10 10 P pmt_row_price_grossn n,nn AN17 4 P/V 42. Tilausrivin tuotteen nettohinta per yksikkö (ilman ALV:a) 43. Tilausrivin tuotteeseen sovellettu ALV-prosentti 44. Tilausrivin alennusprosentti 45. Tilausrivin tyyppi 1 = tuote 2 = postikulu 3 = käsittelykulu 4 = räätälöity tuote (ei palautusoikeutta) 5 = palvelu 6 = alennus (rahamäärä) 46. Tarkisteen laskentamerkistö 47. Sisään tulevan datan enkoodaus (ja verkkokaupan enkoodaus selaimen suuntaan) pmt_row_price_netn n,nn AN17 4 P/V pmt_row_vatn n,nn esim. 23,00 AN5 4 P pmt_row_discountpercentagen n,nn AN5 4 P e.g. 10,00 pmt_row_typen N5 1 P pmt_charset pmt_charsethttp ISO-8859-1, ISO-8859-15 tai UTF-8 ISO-8859-1, ISO-8859-15, UTF-8 48. Tarkistetiedon versio pmt_hashversion AN10 P 49. Tarkiste pmt_hash AN128 32 P 50. Avaimen sukupolvi pmt_keygeneration N3 P Merkintä AN xx tarkoittaa, että kenttä sisältää enintään xx aakkosnumeerista merkkiä. P tarkoittaa pakollista tietoa ja V valinnaista. P/V tarkoittaa pakollista tietoa siinä tapauksessa, jos siihen liittyvä valinnainen tieto on annettu. Minimipituus valinnaisten kenttien kohdalla ei tarkoita, että kyseisessä kentässä pitää aina olla sen mittainen merkkijono. Valinnainen kenttä voi olla tyhjä, tai vähintään minimipituuden mittainen. AN15 AN15 P P

7(15) 3.1 Kenttien selitteet - Maksun välityksen tiedot 1. Toiminnon tunniste NEW_PAYMENT_EXTENDED 2. Sanoman versio Maksusanoman sisällön määrittelyversio. 3. Kauppiaan tunnus Suomen Maksuturva Oy:n Kauppiaalle tunnistamista varten antama tunnus. 4. Kauppiaan tili Ei käytössä toistaiseksi. Hyvityksen kohdetili (IBAN-muodossa), jos hyvitys halutaan eri tilille kuin mikä sopimukselta löytyy. Toistaiseksi hyväksytään vain suomalaisia tiliita IBAN -muodossa. 5. Maksun tunnus Kauppiaan maksulle antama yksilöivä tunnus. 6. Tilaus Tilaus, jolla tilaus löytyy Kauppiaan järjestelmästä ja joka on ostajalla tiedossa. 7. Maksun viite Viite, jota Suomen Maksuturva Oy käyttää hyvittäessään rahat toimituksen jälkeen kauppiaalle. Viiten tulee täyttää Finanssialan keskusliiton (FK, http://www.fkl.fi) säännöt viiten muodolle. Viiten minimipituus on 4, joista viimeinen on tarkiste. 8. Maksun eräpäivä Nykyisin: Kuluva päivä. PP.KK.VVVV 9. Ostajan locale Tieto, joka kertoo ostajan kielen ja maan esim. fi_fi, sv_fi tai en_fi kun toimitaan Suomessa. Jos ei annettu, palvelu käyttää sisäisesti arvoa fi_fi Kieli: ISO 639-1 Maa: ISO 3166-1 alpha-2 10. Maksun rahamäärä Loppusumma, sisältäen tilausrivit tyyppejä 1,4,5,6. Jos myyjän kuluja ei ole, tämä on sama kuin koko tilauksen loppusumma. Summa tulee esittää aina kahden desimaalin tarkkuudella. Desimaalierottimena käytetään pilkkua esim. 94,80 11. Maksun valuutta Maksussa käytettävä valuutta. Aina EUR. 12. Ok -paluuosoite Osoite, mihin käyttäjän selain ohjataan onnistuneen maksun jälkeen. 13. Virhe -paluuosoite Osoite, mihin käyttäjän selain ohjataan, jos maksamisessa tapahtuu virhe. Osoitteen perään lisätään ns. querystring -parametrina sisään tullut maksun tunnus pmt_id nimellä. 14. Peruutus -paluuosoite Osoite, mihin käyttäjän selain ohjataan hänen valitessaan maksun peruutuksen. Jos Virhe-paluuosoitetta ei ole annettu, ohjataan käyttäjän selain myös virhetilanteissa Peruutus-paluuosoitteeseen. Osoitteen perään lisätään ns. querystring -parametrina sisään tullut maksun tunnus pmt_id nimellä. 15. Viivästetty maksu -paluuosoite Osoite, mihin käyttäjän selain ohjataan hänen valitessaan maksutavakseen esim. tilisiirron. Osoitteen perään lisätään ns. querystring -parametrina sisään tullut maksun tunnus pmt_id nimellä. 16. Escrow käytössä Kertoo onko kyseessä Escrow-maksu. Arvot: Y/N Tyytyväisyystakuun sisältävissä Maksuturva-palveluissa (esim. Maksuturva Basic tai Gold) arvo on aina Y. Suoramaksupalveluissa (esim. emaksut) arvo on aina N. 17. Escrow valittavissa Toistaiseksi aina N. 18. Lähettääkö kauppias laskun Parametria voidaan käyttää, mikäli maksutapa on lasku tai osamaksu: Y = kauppias lähettää laskun N (OLETUS) = Maksuturva tai rahoituspalvelun tarjoaja lähettää laskun ostajalle 19. Esivalittu maksutapa VALINNAINEN. Maksutavan koodi Finn. Kts. maksutavat vastauksen tiedoista aivan dokumentin lopusta! 20. Ostajan hetu tai y-tunnus Ostajan henkilö- tai y-tunnus. 21. Ostajan nimi Laskutusosoitteen (ostajan) nimi. 22. Ostajan osoite Laskutusosoitteen (ostajan) postiosoite (katuosoite tai postilokero). 23. Ostajan posti Laskutusosoitteen (ostajan) posti. Selite 24. Ostajan kaupunki Laskutusosoitteen (ostajan) kaupunki tai muu paikkakunta. 25. Ostajan maa Laskutusosoitteen (ostajan) maan maakoodi. (ISO 3166-1 alpha-2 standardin mukainen 2-merkkinen maakoodi http://fi.wikipedia.org/wiki/iso_3166) 26. Ostajan puhelin Laskutusosoitteen (ostajan) puhelin. 27. Ostajan sähköposti Laskutusosoitteen (ostajan) sähköpostiosoite. 28. Vastaanottajan nimi Toimitusosoitteen (vastaanottajan) nimi.

8(15) Selite 29. Vastaanottajan osoite Toimitusosoitteen (vastaanottajan) osoite. (* 30. Vastaanottajan posti Toimitusosoitteen (vastaanottajan) posti. (* 31. Vastaanottajan kaupunki Toimitusosoitteen (vastaanottajan) kaupunki tai paikkakunta. (* 32. Vastaanottajan maa Toimitusosoitteen (vastaanottajan) maan maakoodi. (* 2 merkkiä; ISO 3166-1 alpha-2 33. Myyjän / toimittajan käsittelykulut Summa tulee esittää aina kahden desimaalin tarkkuudella. Desimaalierottimena käytetään pilkkua esim. 21,00 pmt_sellercosts kentän arvon on oltava tilausriveillä esiintyvien posti- ja käsittelykulujen yhteenlaskettu summa (rivityypit 2 ja 3). 34. Tilausrivien lukumäärä Tilauksessa on eriteltävä tilatut tuotteet (versiosta 0004 alkaen). Tässä kerrotaan tilausrivien lukumäärä kokonaislukuna. 35. Tilausrivin tuotteen nimi Tilausrivin tuotteen nimi. Voi olla myös muuta kuin fyysinen tuote. Tällöin kentässä Tilausrivin tyyppi voi olla muu tyyppi kuin 1. Max 40 merkkiä. 36. Tilausrivin tuotteen kuvaus Tilausrivin tuotteen tarkempi kuvaus. 37. Tilausrivin tuotteen määrä Kokonaisluku. Kuinka monta ko. tilausrivillä olevaa tuotetta tilaus sisältää. Ks. kohta Tilauserittelyn laskentasäännöt. 38. Tilausrivin tuotteen tuote Tuotteen tai koodi verkkokaupassa. Valinnainen tieto. verkkokaupassa 39. Tilausrivin tuotteen määrän Yksikkö määrälle, esim. kg, l, m, kpl yksikkö 40. Tilausrivin toimituksen tai palvelun suorituksen ajankohta Päivämäärä muodossa dd.mm.yyyy - annetaan kuluva päivä, mikäli tilausrivi ei sisällä arvoa 41. Tilausrivin tuotteen bruttohinta per yksikkö (ALV mukana) Tilausrivin yksittäisen tuotteen bruttohinta, eli hinta joka sisältää ALV:n, mutta ei ole alennettu. Netto- tai bruttohinta on välitettävä, mutta ei molempia! Ks. kohta Tilauserittelyn laskentasäännöt. 42. Tilausrivin tuotteen nettohinta per yksikkö (ilman ALV:a) 43. Tilausrivin tuotteeseen sovellettu ALV-prosentti Tilausrivin yksittäisen tuotteen nettohinta, eli hinta ilman ALV:a, ei ole alennettu. Netto- tai bruttohinta on välitettävä, mutta ei molempia! Ks. kohta Tilauserittelyn laskentasäännöt. Tilausrivin tuotteeseen sovellettu ALV-prosentti. Desimaaliluku kahdella desimaalilla. Esim. 23,00. Ks. kohta Tilauserittelyn laskentasäännöt. 44. Tilausrivin alennus-prosentti Tilausriviin sovellettava alennusprosentti. Ks. kohta Tilauserittelyn laskentasäännöt. 45. Tilausrivin tyyppi 1 = tuote 2 = postikulu 3 = käsittelykulu 4 = räätälöity tuote (ei palautusoikeutta) 5 = palvelu 6 = alennus (aina negatiivinen) 46. Tarkisteen laskentamerkistö Tämä kertoo missä merkistössä tarkisteen laskentaan käytetty merkkijono oli tarkistetta laskettaessa. Sallitut arvot toistaiseksi ovat ISO-8859-1, ISO-8859-15 ja UTF-8. 47. Sisään tulevan datan enkoodaus (ja verkkokaupan enkoodaus selaimen suuntaan) Tarkiste lasketaan binäärisestä muodosta, eikä merkkijonosta, kuten hashalgoritmien toteuttavien funktioiden rajapinnoista voisi päätellä. Muunnos merkkijonomuotoisesta binääriseksi on osattava tehdä oikeassa merkistössä. Mikäli merkistö ei ole määriteltävissä käytettävälle hash-toteutukselle, on selvitettävä mitä merkistöä se sisäisesti käyttää. Tämä kertoo sisään tulevan datan enkoodauksen. Maksurajapinta käsittelee http request parametrit tämän merkistön mukaisesti. Käytännössä se on siis se merkistö, minkä selain kertoo olevan käytössä kun verkkokaupassa asioidaan. 48. Tarkistetiedon versio Tarkisteen laskennassa käytetty laskentaversio (algoritmin nimi, katso tarkempi kuvaus Rajapintojen Integrointiohjeesta)

9(15) Selite 49. Tarkiste Sanoman kentistä ja Kauppiaan salaisesta avaimesta laskettu tarkiste. Tarkiste lasketaan seuraavista kentistä: pmt_action pmt_version pmt_selleriban (vain jos annettu) pmt_id pmt_orderid pmt_reference pmt_duedate pmt_amount pmt_currency pmt_okreturn pmt_errorreturn pmt_cancelreturn pmt_delayedpayreturn pmt_escrow pmt_escrowchangeallowed pmt_invoicefromseller (vain jos annettu) pmt_paymentmethod (vain jos annettu) pmt_buyeridentificationcode (vain jos annettu) pmt_buyername pmt_buyeraddress pmt_buyerpostalcode pmt_buyercity pmt_buyercountry pmt_deliveryname pmt_deliveryaddress pmt_deliverypostalcode pmt_deliverycity pmt_deliverycountry pmt_sellercosts tilausrivi kerrallaan kaikki seuraavat (jos mukana tiedoissa): o pmt_row_namen o pmt_row_descn o pmt_row_quantityn o pmt_row_articlenrn o pmt_row_unitn o pmt_row_deliverydaten o pmt_row_price_grossn o pmt_row_price_netn o pmt_row_vatn o pmt_row_discountpercentagen o pmt_row_typen <salainen avain> Tarkemmat ohjeet tarkisteen laskennassa käytetyn merkkijonon muodostamisesta lötyyy SMT Rajapinnat Integrointiohje -dokumentin Tarkisteen laskenta -kappaleesta. 50. Avaimen sukupolvi Kauppiaan salaisen avaimen sukupolvi. * ) Tilauksen vastaanottajan osoitteen tulee aina vastata osoitetta, johon tilaus tosiasiallisesti lähetetään. Jos esimerkiksi tilaaja antaa kotiosoitteensa, mutta valitsee lähetyksen noudettavaksi myymälästä tai pakettiautomaatista, tulee tilauksen toimitusosoitteina antaa myymälän tai pakettiautomaatin osoite. 3.2 Tilauserittely Tilauserittely eli pmt_row -alkuiset tiedot on rajapinnassa 0004 pakollinen, ja sisältää kattavat tiedot tilauksesta. Tilauserittelyn loppusumman on täsmättävä tilauksen kokonaissumman kanssa (pmt_amount + pmt_sellercosts). Tilauserittelyssä voidaan välittää joko tuotekohtainen netto- tai bruttohinta. Molempia ei saa välittää. Hintojen välittäminen nettona Mikäli verkkokaupassa lähtötietona on nettohinta, josta verkkokauppa laskee bruttohinnan, on suositeltavaa välittää nettohinta (pmt_row_price_net) ja ALV-prosentti. Tällöin myös Maksuturvan järjestelmä laskee summia tarkistaessaan bruttohinnan lähtien nettohinnasta ja ALV-prosentista.

10(15) Välitettävä hinta: pmt_row_price_net = tuotteen yksikköhinta, ilman ALVia, ilman alennuksen huomiointia Hintojen välittäminen bruttona Mikäli verkkokaupassa lähtötietona on bruttohinta (ALVillinen hinta), josta verkkokauppa laskee tilauserittelyä varten nettohinnan, on suositeltavaa välittää bruttohinta ja ALV-prosentti. Tällöin Maksuturvan järjestelmä laskee tarvittaessa nettohinnan tilauserittelyyn välittäessään tiedot eteenpäin sellaisille maksu- tai luottopalveluille, jotka tietoja vaativat. Mikäli Maksuturvan laskemista nettohinnoista saatu tilauserittelyn kokonaishinta ei täsmää alkuperäiseen verkkokaupan pyytämään kokonaishintaan, Maksuturva lisää tilauserittelyyn pyöristyksen korjausrivin. Välitettävä hinta: pmt_row_price_gross = tuotteen yksikköbruttohinta, sisältäen ALV:n, mutta ilman alennuksen huomiointia Alennusten käsittely Alennus voidaan välittää joko rivikohtaisena alennusprosenttina tai vaihtoehtoisesti voidaan välittää erillisiä negatiivisia alennusrivejä. Suositeltavaa on välittää alennukset prosentteina kunkin tuoterivin yhteydessä. Tällöin niitä on helpompi käsitellä esim. peruutustilanteissa, kun alennus ei näy erillisenä rivinä ja alennusta ei siten tarvitse erikseen peruuttaa. 3.3 Tilauserittelyn laskentasäännöt Alla olevassa kuvauksessa pmt -alkuiset tiedot ovat rajapinnassa välitettyjä tietoja. Calc -alkuiset tiedot ovat laskettuja ja niitä käytetään tilauserittelyn summien tarkistamisessa. Rivin tuotteen yksikköbruttohinnalla ja yksikkönettohinnalla on seuraava suhde: pmt_row_price_gross = round ( pmt_row_price_net * ( 1 + 0.01 * pmt_row_vat ) ) JOS on välitetty nettohinta (ALViton hinta), eli pmt_row_price_net: Rivin summa alennus huomioiden, ilman ALVia: CalcRowAmountExVAT = round ( round ( pmt_row_quantity * pmt_row_price_net ) * ( 1-0.01 * pmt_row_discountpercentage ) ) JOS on välitetty bruttohinta (ALVillinen hinta), eli pmt_row_price_gross: Rivin summa alennus huomioiden, ilman ALVia: CalcRowUnitNetPrice = round ( pmt_row_price_gross / ( 1 + 0.01 * pmt_row_vat ) ) CalcRowAmountExVAT = round ( round ( pmt_row_quantity * CalcRowUnitNetPrice ) * ( 1-0.01 * pmt_row_discountpercentage ) ) Rivin ALV-rahasumma (ALV lasketaan alennetun nettohinnan päälle, alennus huomioidaan): CalcRowVAT = round (CalcRowAmountExVAT * ( 0.01 * pmt_row_vat )) Rivin kokonaissumma (vaikutus maksettavaan bruttosummaan): CalcTotalRowAmount = round ( CalcRowAmountExVAT + CalcRowVAT ) Koko tilauksen bruttosumma: == pmt_amount + pmt_sellercosts == summa ( CalcTotalRowAmount ) pmt_amount == CalcTotalRowAmount yhteenlaskettu summa (tilausrivin tyypit 1, 4, 5, 6) pmt_sellercosts == posti- ja käsittelykulurivien yhteenlaskettu summa (tilausrivin tyypit 2, 3)

11(15) 4. MAKSUN VASTAUSSANOMAN TIEDOT Maksun vastaussanoma välitetään ok-paluuosoitteeseen, mikäli asiakas on maksanut maksun. Tällöin toimituksen voi aloittaa. Mikäli asiakas vahvisti käyttävänsä tilisiirtoa, välitetään maksun tunnus viivästetty maksu -paluuosoitteeseen. Mikäli maksaja perui tapahtuman, maksun tunnus välitetään peruutus-paluuosoitteeseen. Virhetapauksissa maksun tunnus välitetään virhe-paluuosoitteeseen tai sen puuttuessa peruutus-paluuosoitteeseen. HUOM! Maksajan peruuttamasta tapahtumasta, virheestä ja viivästetystä maksusta välitetään paluu-osoitteeseen ainoastaan tieto pmt_id. 4.1 Vastauksen tietojen tarkistaminen Verkkokaupasta Maksuturvalle ja takaisin välitettävien tietojen osalta on ehdottomasti tarkistettava tietojen muuttumattomuus. Maksuturvan välittämät erilliset vastaustiedot on lisäksi tarkistettava muodollisesti, rajapintakuvauksen mukaan. Vastauksen tiedoista on laskettava tarkiste ja verrattava sitä vastauksessa olevaan tarkisteeseen. Jos kaikki yllä olevat vaiheet menevät onnistuneesti läpi, voidaan melko suurella varmuudella katsoa vastaussanoman olevan validi ja käsitellä se asianmukaisesti. Tiedon nimi Arvo Muoto P/V input name= value= 1. Toiminnon tunniste pmt_action NEW_PAYMENT_EXTENDED AN50 P 2. Sanoman versio pmt_version AN4 P 3. Maksun tunnus pmt_id AN20 P 4. Maksun viite pmt_reference N20 P 5. Maksun rahamäärä pmt_amount N17 P 6. Maksun valuutta pmt_currency AN3 P 7. Myyjän kulut pmt_sellercosts N17 P 8. Maksutapa pmt_paymentmethod AN4 P 9. Escrow käytössä pmt_escrow Y / N AN1 P 10. Tarkiste pmt_hash AN128 P 4.2 Kenttien selitteet - Maksun vastaussanoman tiedot 1. Toiminnon tunniste NEW_PAYMENT_EXTENDED 2. Sanoman versio Maksusanoman sisällön määrittelyversio. Sama kuin vastaanotetussa sanomassa. Selite 3. Maksun tunnus Kauppiaan maksulle antama yksilöivä tunnus. 4. Maksun viite Viite, jota Suomen Maksuturva Oy käyttää hyvittäessään rahat toimituksen jälkeen kauppiaalle. Tämä on aina ns. teknisessä muodossa, eli etunollilla ilman välilyöntejä. Myös vastauksen tarkiste on laskettu käyttäen teknistä muotoa. 5. Maksun rahamäärä Tilauksen loppusumma toimituskuluineen. Summa esitetään aina kahden desimaalin tarkkuudella. Desimaalierottimena käytetään pilkkua esim. 94,80 6. Maksun valuutta Maksussa käytetty valuutta. 7. Myyjän kulut Myyjän kulut (sama kuin pyyntösanomassa). Summa esitetään aina kahden desimaalin tarkkuudella. Desimaalierottimena käytetään pilkkua esim. 94,80

12(15) Selite 8. Maksutapa Kertoo, millä maksutavalla maksu on suoritettu. Koodi Selite (tulee näkyä verkkokauppapaikan hallintapaneelissa) FI01 Nordea E-maksu FI02 Danske Bank Verkkomaksu FI03 Aktia/Sp/Pop-maksu (Aktia) FI04 Aktia/Sp/Pop-maksu (POP Pankki) FI05 Tapiola Pankki Verkkomaksu FI06 Osuuspankki Verkkomaksu FI07 Ålandsbanken E-maksu FI08 Aktia/Sp/Pop-maksu (Säästöpankki) FI09 Handelsbanken Verkkomaksu FI10 S-pankki Verkkomaksu FI50 Korttimaksu (Visa, Visa Electron, MasterCard) FI60 Maksuturva Lasku FI61 Maksuturva Erämaksu FI70 SveaWebPay Lasku FI71 SveaWebPay Osamaksu 9. Escrow käytössä Kertoo onko kyseessä Escrow-maksu. Arvot: Y/N Tyytyväisyystakuun sisältävissä Maksuturva-palveluissa (esim. Maksuturva Basic tai Gold) arvo on aina Y. Suoramaksupalveluissa (esim. emaksut) arvo on aina N. 10. Tarkiste Sanoman kentistä ja Kauppiaan salaisesta avaimesta laskettu tarkiste. Tarkisteen laskennassa käytetään samoja versio-, avain- ym. tietoja kuin sisään tulevalla sanomalla. Tarkiste lasketaan näistä kentistä: pmt_action pmt_version pmt_id pmt_reference pmt_amount pmt_currency pmt_sellercosts pmt_paymentmethod pmt_escrow

13(15) 5. TARKISTEEN LASKENTA Jokainen sanoma sisältää tarkisteen (hash), joka on laskettu rajapintakuvauksessa nimetyistä tiedoista (yleensä sanoman pakollisista tiedoista). Tarkisteen laskennassa voi käyttää seuraavia algoritmeja: Algoritmin nimi Algoritmi SHA-512 SHA-256 SHA-1 MD5 512 -bittinen SHA-2 256 -bittinen SHA-2 160 -bittinen SHA-1 MD5 Tarkiste lasketaan siis kunkin sanoman rajapintakuvauksessa määritellyistä kentistä. Tarkisteen laskennassa välitettävät tiedot laitetaan luetellussa järjestyksessä peräkkäin ja jokaisen tiedon perään laitetaan & -merkki. Lueteltujen tietojen perään laitetaan Suomen Maksuturva Oy:n toimittama salainen avain ja tämän perään vielä & - merkki. Näin syntyneestä merkkijonosta muodostetaan tarkiste käyttäen yhtä sallituista algoritmeista. Tarkistetiedon versio -kenttään laitetaan tämän algoritmin nimi siinä muodossa kuin se näkyy sallittujen algoritmien listauksessa. Mikäli tieto on valinnainen ja mukana tarkisteessa, mutta sitä ei välitetä tai se on tyhjä, tarkisteen laskennassa EI tällöin laiteta myöskään & merkkiä sen tiedon kohdalle. Tarkiste voidaan välittää isoilla tai pienillä kirjaimilla, mutta vastauksissa tarkiste on aina isoilla kirjaimilla. Esimerkki: Oletetaan, että tarkiste lasketaan seuraavista kentistä (suluissa esimerkissä käytettävä arvo): kentta1 (123) kentta2 (ABC) kentta3 (K) Salaisena avaimena käytössä on testiavain ilman lainausmerkkejä. Tarkiste lasketaan tällöin seuraavasta merkkijonosta: Salaisena avaimena käytössä on testiavain ilman lainausmerkkejä. Tarkiste lasketaan tällöin seuraavasta merkkijonosta: 123&ABC&K&testiavain& Oletuksena tarkiste on laskettava ISO-8859-1 muotoisesta merkkijonosta, mutta muutkin merkistöt ovat sallittuja. Maksurajapinnalle tarkisteenlaskennassa käytetty merkistö voidaan välittää pmt_charset parametrina. Sen arvoina sallitaan ainakin ISO-8859-1, ISO-8859-15 ja UTF-8. Lisäksi riippumatta tarkisteen laskennan merkistöstä, pitää maksurajapinnan versiosta 0004 alkaen välittää parametri pmt_charsethttp, joka kertoo verkkokaupan käyttämän merkistön. 5.1 Vinkkejä tarkisteen laskennan avuksi Kopioi salainen avain ja kauppiastunnus uudelleen vaikka Notepadin kautta. Niihin tulee usein näkymättömiä spacetai rivinvaihtomerkkejä Outlookista tai Wordista. Kokeile toimiiko hash oikein jos tilauksessa ei ole mitään erikoismerkkejä, ääkkösiä tai ylipäätään US-ASCII merkistön ulkopuolisia merkkejä. Jos toimii, niin vika on merkistöjen enkoodauksissa tai niiden ilmoittamisessa Maksuturvan maksurajapinnalle: Tietojen välityksen merkistö / pmt_charsethttp: Verkkokaupan selaimen suuntaan käyttämä enkoodaus. Selaimen pitää oikeasti välittää tiedot tässä

14(15) enkoodauksessa. Selaimen tiedoista (view page info yms.) näkyy missä muodossa se välittää tiedot. Ne ovat siinä muodossa kuin se verkkokaupan sivu mikä viimeisenä näkyy ennen Maksamiseen siirtymistä. Hash-laskennan merkistö / pmt_charset: Hash-laskenta (MD5 ja kaikki muutkin) ovat binäärioperaatioita. Merkkijono muunnetaan binääriksi ennen laskentaa. Siten esim "Ä" UTF-8-merkistössä saa eri hash-arvon kuin "Ä" Latin-1-merkistössä. Koodaajan on tiedettävä tai määriteltävä hash-funktiolle, mitä merkistöä se käyttää muuntaessaan merkkijonon binääriksi ennen hashin laskemista, ja tämä sama merkistö on välitettävä Maksuturvalle parametrissa pmt_charset Tarkista ettei hashattavassa merkkijonossa missään välissä ole kahta & merkkiä (ampersand) peräkkäin, sillä sellainen tulee vain hashiin mukaan tulevien tietojen perään, tyhjiä kenttiä ei laiteta hashiin eikä niiden perässä olevia & merkkejä myöskään. Merkkijonon viimeinen merkki on myös & Katso läpi tarkisteenlaskennan parametrilista rajapintakuvauksesta. Se on erilainen kuin välitettävien parametrien lista erinäisten valinnaisuuksien yms. vuoksi. 6. KAUPPIAAN SALLITTUJEN MAKSUTAPOJEN HAKEMINEN Kauppiaalle sallitut maksutavat on haettavissa XML-muotoisena tiedostona rajapinnasta https://www.maksuturva.fi/getpaymentmethods.pmt Pyynnön voi lähettää GET tai POST metodilla. Vastauksessa saatuja koodeja (code) voi käyttää maksurajapinnan kentässä pmt_paymentmethod, mikäli verkkokaupassa on mahdollista esivalita maksutapa. Esimerkki pyynnöstä: https://www.maksuturva.fi/getpaymentmethods.pmt?sellerid=sellerid&request_locale=fi&totalamount=47,50 Tiedon nimi Arvo Muoto Minimi- P/V input name= value= pituus 1. Kauppiaan tekninen tunnus sellerid AN50 4 P 2. Kielikoodi, jolla maksutapojen request_locale fi, en, sv. Oletus: fi A2 2 V nimet halutaan 3. Tilauksen loppusumma, jota tullaan maksamaan totalamount esim. 20,00 AN17 4 V Esimerkki vastauksesta: <?xml version="1.0" encoding="iso-8859-1" standalone="no"?> <paymentmethods> <paymentmethod> <code>fi01</code> <displayname>nordea E-maksu</displayname> </paymentmethod> <paymentmethod> <code>fi06</code> <displayname>osuuspankki Verkkomaksu</displayname> </paymentmethod> </paymentmethods>

15(15) 7. DYNAAMISEN KUVA-AINEISTON HAKEMINEN Verkkokaupan käytössä olevan palvelun mukaiset maksupalvelun logot ja maksutapavaihtoehdot esittävät bannerit ovat haettavissa PNG-muodossa Maksuturvan palvelulta käyttäen Maksuturvan dynaamisten kuva-aineistojen rajapintaa. Rajapintakuvaus on ladattavissa osoitteesta https://www.maksuturva.fi/fi/ohjeet/palvelunkayttoonotto/integrointiohjeet-ja-rajapintakuvaukset/.