Rajapintakuvaus verkkokaupalle MAKSAMINEN Maksuturvan palveluille Versio 4.1.9 Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | info@maksuturva.fi 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 Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | info@maksuturva.fi 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 postinumero (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 Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | info@maksuturva.fi 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) Toukokuu 2011 4.1 Uusia kenttiä tarkisteessa: pmt_action (NEW_PAYMENT_EXTENDED) pmt_version MAKSUN VÄLITYKSEN TIEDOT (IN): Uusia valinnaisia tietoja: pmt_row_articlenrN tilausrivin tuotteen tuotenumero 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 Joulukuu 2011 4.1.2 Maaliskuu 2013 4.1.4 Kesäkuu 2013 Huhtikuu 2014 4.1.5 4.1.6 Toukokuu 2014 4.1.7 Heinäkuu 2014 Elokuu 2014 4.1.8 4.1.9 Lisätty - lisätiedot eMaksujen integrointiin ohje sallittujen maksutapojen hakemiseen ohje maksubannerin hakemiseen. Lisätty lisäohjeita hash-laskentaan Pidennetty maksajan ja toimitustietojen nimi- ja osoitekenttiä. Ei muutoksia Lisätty uudet maksutavat: Maksuturva Lasku Maksuturva Erämaksu Lisätty sallittujen maksutapojen hakuun uusi parametri: totalamount (tilauksen loppusumma) Lisätty huomautus toimitusosoitteen paikkansapitävyyden tärkeydestä Korvattu maksutapabannerin haun rajapintakuvaus viittauksella omaan dokumenttiinsa Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | info@maksuturva.fi 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 Kentän numero 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. Kenttä Toiminnon tunniste Sanoman versio Kauppiaan tunnus Kauppiaan tilinumero Maksun tunnus Tilausnumero Maksun viite Maksun eräpäivä Ostajan locale Maksun rahamäärä Maksun valuutta Ok -paluuosoite Virhe -paluuosoite Peruutus -paluuosoite Viivästetty maksu paluuosoite Escrow käytössä Escrow valittavissa Lähettääkö kauppias laskun Verkkokaupassa esivalittu maksutapa Ostajan hetu tai y-tunnus Ostajan nimi Ostajan osoite Ostajan postinumero Ostajan kaupunki Ostajan maakoodi (FI, SE, EN…) Ostajan puhelinumero Ostajan sähköposti Vastaanottajan nimi Vastaanottajan osoite Vastaanottajan postinumero Vastaanottajan kaupunki Vastaanottajan maakoodi (FI, SE, EN…) Myyjän / toimittajan käsittelykulut Tilausrivien lukumäärä Tilausrivin tuotteen nimi Tilausrivin tuotteen kuvaus Tilausrivin tuotteen määrä Tilausrivin tuotteen tuotenumero kaupassa Tiedon nimi input name= pmt_action pmt_version pmt_sellerid pmt_selleriban pmt_id pmt_orderid pmt_reference pmt_duedate pmt_userlocale pmt_amount pmt_currency pmt_okreturn pmt_errorreturn pmt_cancelreturn pmt_delayedpayreturn Arvo value= NEW_PAYMENT_EXTENDED 0004 kuluva päivä muodossa dd.mm.yyyy fi_FI, sv_FI, en_FI Muoto AN50 AN4 AN15 AN30 AN20 AN50 N20 AN10 Minimipituus 4 4 18 4 10 P/V P P P V P P P P AN5 AN17 AN3 AN200 AN200 AN200 AN200 5 4 3 V P P P P P P A1 A1 A1 1 1 1 P P V AN4 4 V pmt_buyeridentificationcode pmt_buyername pmt_buyeraddress pmt_buyerpostalcode pmt_buyercity pmt_buyercountry AN11 AN100 AN100 N20 AN100 A2 9 V P P P P P pmt_buyerphone pmt_buyeremail pmt_deliveryname pmt_deliveryaddress pmt_deliverypostalcode AN40 AN100 AN100 AN100 N20 V V P P P pmt_deliverycity pmt_deliverycountry AN100 A2 P P EUR pmt_escrow pmt_escrowchangeallowed pmt_invoicefromseller Maksuturva=Y, eMaksut=N N Y/N pmt_paymentmethod Finn pmt_sellercosts AN17 4 P N4 AN40 AN1000 1 1 1 P P P pmt_row_quantityN N8 1 P pmt_row_articlenrN AN10 0 V pmt_rows pmt_row_nameN pmt_row_descN n,nn Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | info@maksuturva.fi 6(15) Kentän numero 39. 40. 41. 42. 43. 44. 45. Kenttä Tilausrivin määrän yksikkö Tilausrivin toimituksen tai palvelun suorituksen ajankohta Tilausrivin tuotteen bruttohinta per yksikkö (ALV mukana) Tilausrivin tuotteen nettohinta per yksikkö (ilman ALV:a) Tilausrivin tuotteeseen sovellettu ALV-prosentti Tilausrivin alennusprosentti Tilausrivin tyyppi 1 = tuote 2 = postikulu 3 = käsittelykulu 4 = räätälöity tuote (ei Tiedon nimi input name= pmt_row_unitN Arvo value= esim. kg, kpl Muoto P/V AN3 Minimipituus 0 pmt_row_deliverydateN dd.mm.yyyy AN10 10 P pmt_row_price_grossN n,nn AN17 4 P/V pmt_row_price_netN n,nn AN17 4 P/V pmt_row_vatN n,nn esim. 23,00 n,nn e.g. 10,00 AN5 4 P AN5 4 P N5 1 P pmt_row_discountpercentageN pmt_row_typeN V palautusoikeutta) 46. 47. 48. 49. 50. 5 = palvelu 6 = alennus (rahamäärä) Tarkisteen laskentamerkistö Sisään tulevan datan enkoodaus (ja verkkokaupan enkoodaus selaimen suuntaan) Tarkistetiedon versio Tarkiste Avaimen sukupolvi pmt_charset pmt_charsethttp pmt_hashversion pmt_hash pmt_keygeneration ISO-8859-1, ISO-8859-15 tai UTF-8 ISO-8859-1, ISO-8859-15, UTF-8 AN15 P AN15 P AN10 AN128 N3 32 P P 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. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | info@maksuturva.fi 7(15) 3.1 Kenttien selitteet - Maksun välityksen tiedot Kentän numero 1. Kenttä Selite 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 tilinumero 5. Maksun tunnus Ei käytössä toistaiseksi. Hyvityksen kohdetilinumero (IBAN-muodossa), jos hyvitys halutaan eri tilille kuin mikä sopimukselta löytyy. Toistaiseksi hyväksytään vain suomalaisia tilinumeroita IBAN -muodossa. Kauppiaan maksulle antama yksilöivä tunnus. 6. Tilausnumero 7. Maksun viite 8. Maksun eräpäivä 9. Ostajan locale 10. Maksun rahamäärä 11. Maksun valuutta 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 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 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 14. Peruutus -paluuosoite 15. Viivästetty maksu -paluuosoite 16. Escrow käytössä 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ä. 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ä. 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ä. Kertoo onko kyseessä Escrow-maksu. Arvot: Y/N 17. Escrow valittavissa Tyytyväisyystakuun sisältävissä Maksuturva-palveluissa (esim. Maksuturva Basic tai Gold) arvo on aina Y. Suoramaksupalveluissa (esim. eMaksut) arvo on aina N. Toistaiseksi aina N. 18. Lähettääkö kauppias laskun 19. Esivalittu maksutapa 20. Ostajan hetu tai y-tunnus 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 VALINNAINEN. Maksutavan koodi Finn. Kts. maksutavat vastauksen tiedoista aivan dokumentin lopusta! Ostajan henkilö- tai y-tunnus. 21. Ostajan nimi Laskutusosoitteen (ostajan) nimi. 22. Ostajan osoite Laskutusosoitteen (ostajan) postiosoite (katuosoite tai postilokero). 23. Ostajan postinumero Laskutusosoitteen (ostajan) postinumero. 24. Ostajan kaupunki Laskutusosoitteen (ostajan) kaupunki tai muu paikkakunta. 25. Ostajan maa 26. Ostajan puhelinnumero Laskutusosoitteen (ostajan) maan maakoodi. (ISO 3166-1 alpha-2 standardin mukainen 2-merkkinen maakoodi http://fi.wikipedia.org/wiki/ISO_3166) Laskutusosoitteen (ostajan) puhelinnumero. 27. Ostajan sähköposti Laskutusosoitteen (ostajan) sähköpostiosoite. 28. Vastaanottajan nimi Toimitusosoitteen (vastaanottajan) nimi. Tilausnumero, jolla tilaus löytyy Kauppiaan järjestelmästä ja joka on ostajalla tiedossa. Viitenumero, jota Suomen Maksuturva Oy käyttää hyvittäessään rahat toimituksen jälkeen kauppiaalle. Viitenumeron tulee täyttää Finanssialan keskusliiton (FK, http://www.fkl.fi) säännöt viitenumeron muodolle. Viitenumeron minimipituus on 4, joista viimeinen on tarkiste. Nykyisin: Kuluva päivä. PP.KK.VVVV Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | info@maksuturva.fi 8(15) Kentän numero 29. Kenttä Selite Vastaanottajan osoite Toimitusosoitteen (vastaanottajan) osoite. (* 30. Vastaanottajan postinumero Toimitusosoitteen (vastaanottajan) postinumero. (* 31. Vastaanottajan kaupunki Toimitusosoitteen (vastaanottajan) kaupunki tai paikkakunta. (* 32. Vastaanottajan maa 33. Myyjän / toimittajan käsittelykulut 34. Tilausrivien lukumäärä 35. Tilausrivin tuotteen nimi 36. Tilausrivin tuotteen kuvaus Toimitusosoitteen (vastaanottajan) maan maakoodi. (* 2 merkkiä; ISO 3166-1 alpha-2 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). Tilauksessa on eriteltävä tilatut tuotteet (versiosta 0004 alkaen). Tässä kerrotaan tilausrivien lukumäärä kokonaislukuna. 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ä. Tilausrivin tuotteen tarkempi kuvaus. 37. Tilausrivin tuotteen määrä 38. Tilausrivin tuotteen tuotenumero verkkokaupassa Tilausrivin tuotteen määrän yksikkö Tilausrivin toimituksen tai palvelun suorituksen ajankohta Tilausrivin tuotteen bruttohinta per yksikkö (ALV mukana) 39. 40. 41. 42. Tilausrivin tuotteen nettohinta per yksikkö (ilman ALV:a) 43. Tilausrivin tuotteeseen sovellettu ALV-prosentti 44. Tilausrivin alennus-prosentti 45. Tilausrivin tyyppi 46. Tarkisteen laskentamerkistö 47. 48. Sisään tulevan datan enkoodaus (ja verkkokaupan enkoodaus selaimen suuntaan) Tarkistetiedon versio Kokonaisluku. Kuinka monta ko. tilausrivillä olevaa tuotetta tilaus sisältää. Ks. kohta “Tilauserittelyn laskentasäännöt”. Tuotteen numero tai koodi verkkokaupassa. Valinnainen tieto. Yksikkö määrälle, esim. kg, l, m, kpl Päivämäärä muodossa dd.mm.yyyy - annetaan kuluva päivä, mikäli tilausrivi ei sisällä arvoa 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”. 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”. Tilausriviin sovellettava alennusprosentti. Ks. kohta “Tilauserittelyn laskentasäännöt”. 1 = tuote 2 = postikulu 3 = käsittelykulu 4 = räätälöity tuote (ei palautusoikeutta) 5 = palvelu 6 = alennus (aina negatiivinen) 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. 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. Tarkisteen laskennassa käytetty laskentaversio (algoritmin nimi, katso tarkempi kuvaus Rajapintojen Integrointiohjeesta) Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | info@maksuturva.fi 9(15) Kentän numero 49. Kenttä Tarkiste Selite 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 sukupolvinumero. * ) 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. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | info@maksuturva.fi 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) Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | info@maksuturva.fi 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. Kentän numero 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. Kenttä Toiminnon tunniste Sanoman versio Maksun tunnus Maksun viite Maksun rahamäärä Maksun valuutta Myyjän kulut Maksutapa Escrow käytössä Tarkiste Tiedon nimi input name= pmt_action pmt_version pmt_id pmt_reference pmt_amount pmt_currency pmt_sellercosts pmt_paymentmethod pmt_escrow pmt_hash Arvo value= NEW_PAYMENT_EXTENDED Y/N Muoto AN50 AN4 AN20 N20 N17 AN3 N17 AN4 AN1 AN128 P/V P P P P P P P P P P 4.2 Kenttien selitteet - Maksun vastaussanoman tiedot Kentän numero 1. Kenttä Selite Toiminnon tunniste NEW_PAYMENT_EXTENDED 2. Sanoman versio Maksusanoman sisällön määrittelyversio. Sama kuin vastaanotetussa sanomassa. 3. Maksun tunnus Kauppiaan maksulle antama yksilöivä tunnus. 4. Maksun viite 5. Maksun rahamäärä 6. Maksun valuutta 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. Tilauksen loppusumma toimituskuluineen. Summa esitetään aina kahden desimaalin tarkkuudella. Desimaalierottimena käytetään pilkkua esim. 94,80 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 Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | info@maksuturva.fi 12(15) Kentän numero 8. 9. 10. Kenttä Selite 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 Escrow käytössä Kertoo onko kyseessä Escrow-maksu. Arvot: Y/N Tarkiste Tyytyväisyystakuun sisältävissä Maksuturva-palveluissa (esim. Maksuturva Basic tai Gold) arvo on aina Y. Suoramaksupalveluissa (esim. eMaksut) arvo on aina N. 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 Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | info@maksuturva.fi 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 SHA-512 SHA-256 SHA-1 MD5 Algoritmi 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ä Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | info@maksuturva.fi 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 Kentän numero 1. 2. 3. Kenttä Kauppiaan tekninen tunnus Kielikoodi, jolla maksutapojen nimet halutaan Tilauksen loppusumma, jota tullaan maksamaan Tiedon nimi input name= Arvo value= Muoto sellerid request_locale fi, en, sv. Oletus: fi AN50 A2 Minimipituus 4 2 totalamount esim. 20,00 AN17 4 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> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | info@maksuturva.fi P/V V P V 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/. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | info@maksuturva.fi
© Copyright 2024