Maksuturva-palvelun käyttöönottolomakkeen rajapintakuvaus verkkokauppaohjelmistolle Versio 1.1 11.1.2010
2(8) Sisältö 1. Palvelun käyttöönoton tiedot... 3 Kenttien selitteet Palvelun käyttöönoton tiedot... 5 2. Palvelun käyttöönoton vastaussanoman tiedot... 7 Kenttien selitteet Palvelun käyttöönoton vastaussanoman tiedot... 7
3(8) 1. PALVELUN KÄYTTÖÖNOTON TIEDOT Verkkokauppaohjelmisto välittää verkkokauppayrityksen, verkkokaupan ja Maksuturva-palvelun tiedot FORMtietoryhmässä piilomuuttujina. Tiedot lähetetään osoitteeseen https://www.maksuturva.fi/merchantsubscription.pmt Tiedon nimi Arvo Muoto Minimi- P/V input name= value= pituus 1. Palvelun käyttöönoton versio srv_version 0002 AN4 4 P 2. Verkkokauppapalvelun tarjoajan srv_webstoreserviceid AN15 1 P tunnus 3. Verkkokauppayrityksen y-tunnus srv_businessid AN15 9 V 4. Verkkokauppayrityksen nimi srv_businessname AN80 1 V 5. Verkkokauppayrityksen srv_marketingname AN80 1 V markkinointinimi 6. Verkkokauppayrityksen www-osoite srv_businesswww AN200 4 V 7. Verkkokauppayrityksen srv_businessemail AN80 4 V 8. Verkkokauppayrityksen puhelin srv_businessphone AN40 1 V 9. Verkkokauppayrityksen faksi srv_businessfax AN40 1 V 10. Verkkokaupan oletustili srv_webstoreiban AN30 18 V 11. Verkkokaupan nimi srv_webstorename AN80 1 V 12. Verkkokaupan www-osoite srv_webstorewww AN200 4 P 13. Verkkokaupan asiakaspalvelun srv_webstorecustomerservice AN100 1 V yhteystieto 14. Verkkokauppayrityksen katuosoite srv_businessaddress AN100 5 V 15. Verkkokauppayrityksen postilokero srv_businesspobox AN10 4 V 16. Verkkokauppayrityksen posti srv_businesspostalcode AN5 5 V 17. Verkkokauppayrityksen srv_businesscity AN40 1 V postitoimipaikka 18. Verkkokauppayrityksen maa srv_businesscountrycode AN2 2 V 19. Verkkokauppayrityksen srv_billingaddress AN100 5 V laskutuskatuosoite 20. Verkkokauppayrityksen srv_billingpobox AN10 4 V laskutuspostilokero 21. Verkkokauppayrityksen srv_billingpostalcode AN5 5 V laskutusposti 22. Verkkokauppayrityksen srv_billingcity AN40 1 V laskutuspostitoimipaikka 23. Verkkokauppayrityksen laskutusmaa srv_billingcountrycode AN2 2 V 24. Verkkokaupan katuosoite srv_webstoreaddress AN100 5 V 25. Verkkokaupan postilokero srv_webstorepobox AN10 4 V 26. Verkkokaupan posti srv_webstorepostalcode AN5 5 V 27. Verkkokaupan postitoimipaikka srv_webstorecity AN40 1 V 28. Verkkokaupan maa srv_webstorecountrycode AN2 2 V 29. Verkkokauppayrityksen yhteyshenkilön srv_contactpersonname AN80 1 V nimi 30. Verkkokauppayrityksen yhteyshenkilön srv_contactpersonemail AN80 4 V 31. Verkkokauppayrityksen yhteyshenkilön srv_contactpersonphone AN40 1 V puhelin 32. Verkkokauppayrityksen yhteyshenkilön srv_contactpersonmobile AN40 1 V matkapuhelin 33. Verkkokauppayrityksen yhteyshenkilön srv_contactpersonfax AN40 1 V faksi 34. Verkkokauppayrityksen srv_billingpersonname AN80 1 V nimi 35. Verkkokauppayrityksen srv_billingpersonemail AN80 4 V
4(8) Tiedon nimi Arvo Muoto Minimi- P/V input name= value= pituus 36. Verkkokauppayrityksen srv_billingpersonphone AN40 1 V puhelin 37. Verkkokauppayrityksen srv_billingpersonmobile AN40 1 V matkapuhelin 38. Verkkokauppayrityksen srv_billingpersonfax AN40 1 V faksi 39. Verkkokaupan teknisen yhteyshenkilön srv_webstorepersonname AN80 1 V nimi 40. Verkkokaupan teknisen yhteyshenkilön srv_webstorepersonemail AN80 4 V 41. Verkkokaupan teknisen yhteyshenkilön srv_webstorepersonphone AN40 1 V puhelin 42. Verkkokaupan teknisen yhteyshenkilön srv_webstorepersonmobile AN40 1 V matkapuhelin 43. Verkkokaupan teknisen yhteyshenkilön srv_webstorepersonfax AN40 1 V faksi 44. Verkkokaupan Maksuturva-maksutavat srv_paymentmethodinfo AN200 1 V 45. Verkkokaupan Maksuturvatoimitustavat srv_deliverymethodinfo AN200 1 V 46. Verkkokaupan Maksuturva-palvelun srv_servicebegindate dd.mm.yyyy AN10 10 V voimaantulopäivä 47. Kampanjakoodi srv_campaigncode AN10 5 V 48. Lisätietoa tilauksesta srv_additionalinformation AN2000 1 V 49. Vastauksen tyyppi srv_resptype POST AN4 3 V 50. Ok paluuosoite srv_okreturn AN200 11 P 51. Virhe paluuosoite srv_errorreturn AN200 11 V 52. Peruutus-paluuosoite srv_cancelreturn AN200 11 V 53. Tarkisteen laskentamerkistö srv_charset ISO-8859-1, AN15 5 V ISO-8859-15 tai UTF-8 54. Tarkistetiedon versio srv_hashversion AN10 1 P 55. Tarkiste srv_hash AN128 32 P 56. Avaimen sukupolvi srv_keygeneration N3 1 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.
5(8) Kenttien selitteet Palvelun käyttöönoton tiedot 1. Palvelun käyttöönoton versio Palvelun käyttöönottosanoman sisällön määrittelyversio. 2. Verkkokauppapalvelun tarjoajan tunnus Suomen Maksuturva Oy:n Verkkokauppaohjelmistotalolle tunnistamista varten antama tunnus. 3. Verkkokauppayrityksen y-tunnus Verkkokauppaa harjoittavan yrityksen Patentti- ja rekisterihallitukselta saama yritystunnus (y-tunnus) 4. Verkkokauppayrityksen nimi Verkkokauppaa harjoittavan yrityksen virallinen nimi 5. Verkkokauppayrityksen markkinointinimi Verkkokauppaa harjoittavan yrityksen markkinointinimi, se nimi, jolla esim. posti toimitetaan. 6. Verkkokauppayrityksen wwwosoite Verkkokauppaa harjoittavan yrityksen kotisivut. 7. Verkkokauppayrityksen Verkkokauppaa harjoittavan yrityksen, yleinen info-osoite. 8. Verkkokauppayrityksen puhelin Verkkokauppaa harjoittavan yrityksen puhelin, pääasiallinen puhelin, esim. vaihde. 9. Verkkokauppayrityksen Verkkokauppaa harjoittavan yrityksen faksi, pääasiallinen faksi. faksi 10. Verkkokaupan oletustili Verkkokaupan tili, jolle Maksuturvan kautta hoidetut maksut hyvitetään kun tilaus on toimitettu perille. Tili tulee olla IBAN-muodossa (FI + tarkiste 2 mrk + kotimainen tili 14 mrk) 11. Verkkokaupan nimi Verkkokaupan nimi, se nimi, jota käytetään ostajille. 12. Verkkokaupan www-osoite Verkkokaupan www-osoite, se osoite, jossa Maksuturva-palvelu tulee käyttöön 13. Verkkokaupan asiakaspalvelun yhteystieto Verkkokaupan asiakaspalvelun yhteystieto. Yhteystieto tulostetaan vahvistussähköpostiin Maksuturva-palvelua käyttävälle tilaajalle/ostajalle. Yhteystiedon ei tule sisältää nimeä, mutta sen tulee toimia suomeksi, ruotsiksi ja englanniksi. Esim. info@verkkokauppa.fi, (09) 123 4567. 14. Verkkokauppayrityksen Verkkokauppaa harjoittavan yrityksen pääasiallinen osoite. katuosoite 15. Verkkokauppayrityksen Pääasiallisen osoitteen postilokero. postilokero 16. Verkkokauppayrityksen Pääasiallisen osoitteen posti posti 17. Verkkokauppayrityksen Pääasiallisen osoitteen postitoimipaikka / kaupunki / kunta postitoimipaikka 18. Verkkokauppayrityksen maa Pääasiallisen osoitteen maakoodi, standardin ISO 3166-1 mukainen. Oletusarvo FI (Suomi). 19. Verkkokauppayrityksen laskutuskatuosoite Verkkokauppaa harjoittavan yrityksen laskutusosoitteen katuosoite. Laskutusosoite annetaan, mikäli se poikkeaa pääasiallisesta osoitteesta. 20. Verkkokauppayrityksen Laskutusosoitteen postilokero. laskutuspostilokero 21. Verkkokauppayrityksen Laskutusosoitteen posti. Pakollinen jos laskutuskatuosoite annetaan. laskutusposti 22. Verkkokauppayrityksen laskutuspostitoimipaikka Laskutusosoitteen postitoimipaikka / kaupunki / kunta. Pakollinen jos laskutuskatuosoite annetaan. 23. Verkkokauppayrityksen Laskutusosoitteen maakoodi, standardin ISO 3166-1 mukainen. Oletusarvo FI (Suomi). laskutusmaa 24. Verkkokaupan katuosoite Verkkokaupan osoitteen katuosoite. Verkkokaupan osoite annetaan, mikäli se poikkeaa pääasiallisesta osoitteesta. 25. Verkkokaupan postilokero Verkkokaupan postilokero. 26. Verkkokaupan posti Verkkokaupan posti. Pakollinen jos verkkokaupan katuosoite annetaan. 27. Verkkokaupan postitoimipaikka Verkkokaupan postitoimipaikka / kaupunki / kunta. Pakollinen jos verkkokaupan katuosoite annetaan. 28. Verkkokaupan maa Verkkokaupan maakoodi, standardin ISO 3166-1 mukainen. Oletusarvo FI (Suomi). 29. Verkkokauppayrityksen yhteyshenkilön nimi Verkkokauppaa harjoittavan yrityksen pääasiallinen yhteyshenkilö Suomen Maksuturvalle. 30. Verkkokauppayrityksen Yhteyshenkilön yhteyshenkilön 31. Verkkokauppayrityksen yhteyshenkilön puhelin Yhteyshenkilön puhelin
6(8) 32. Verkkokauppayrityksen yhteyshenkilön matkapuhelin 33. Verkkokauppayrityksen yhteyshenkilön faksi 34. Verkkokauppayrityksen nimi 35. Verkkokauppayrityksen 36. Verkkokauppayrityksen puhelin 37. Verkkokauppayrityksen matkapuhelin 38. Verkkokauppayrityksen faksi 39. Verkkokaupaan teknisen yhteyshenkilön nimi 40. Verkkokaupan teknisen yhteyshenkilön 41. Verkkokaupan teknisen yhteyshenkilön puhelin 42. Verkkokaupan teknisen yhteyshenkilön matkapuhelin 43. Verkkokaupan teknisen yhteyshenkilön faksi 44. Verkkokaupan Maksuturvamaksutavat 45. Verkkokaupan Maksuturvatoimitustavat 46. Verkkokaupan Maksuturvapalvelun voimaantulopäivä Yhteyshenkilön matkapuhelin Yhteyshenkilön faksi Verkkokauppaa harjoittavan yrityksen laskutusyhteyshenkilö Suomen Maksuturvalle. Laskutusyhteyshenkilön. Pakollinen jos laskutusyhteyshenkilö annetaan. Laskutusyhteyshenkilön puhelin. Pakollinen jos laskutusyhteyshenkilö annetaan. Laskutusyhteyshenkilön matkapuhelin Laskutusyhteyshenkilön faksi Verkkokaupan tekninen yhteyshenkilö Suomen Maksuturvalle. Teknisen yhteyshenkilön. Pakollinen jos tekninen yhteyshenkilö annetaan. Teknisen yhteyshenkilön puhelin. Pakollinen jos tekninen yhteyshenkilö annetaan. Teknisen yhteyshenkilön matkapuhelin Teknisen yhteyshenkilön faksi Verkkokaupan käyttämien toimitustapojen tunnisteet. Tunnisteet löytyvät osoitteesta https://www.maksuturva.fi/palvelut/kauppiaille/kauppiasmateriaali.html ensimmäinen merkki määrittelee käytetyn erotusmerkin, joka ei saa esiintyä osana maksutapoja. Suosituksena puolipiste. Ensimmäisenä merkkinä tulee olla erotinmerkki, vaikka kenttä sisältäisi vain yhden maksutavan. Jos maksutapatietoa ei anneta, perustetaan Maksuturva-palvelun kaikilla sillä hetkellä tarjottavilla maksutavoilla. Verkkokaupan käyttämien toimitustapojen tunnisteet. Tunnisteet löytyvät osoitteesta https://www.maksuturva.fi/palvelut/kauppiaille/kauppiasmateriaali.html ensimmäinen merkki määrittelee käytetyn erotusmerkin, joka ei saa esiintyä osana toimitustapoja. Suosituksena puolipiste. Ensimmäisenä merkkinä tulee olla erotinmerkki, vaikka kenttä sisältäisi vain yhden toimitustavan. Päivämäärä, josta alkaen Maksuturvaa halutaan käyttää verkkokaupassa. Jos jätetään antamatta, palvelu astuu voimaan heti kun sopimus on allekirjoitettu ja käsitelty Suomen Maksuturvassa. 47. Kampanjakoodi Ei käytössä. Suomen Maksuturvan kanssa sovittava palvelun ehtoihin ja/tai hintaan vaikuttava kampanjakoodi. 48. Lisätietoa tilauksesta Vapaamuotoista tietoa tilauksesta. 49. Vastauksen tyyppi Määrittää missä muodossa vastaussanoma tehdään. Vaihtoehdot ovat POST ja XML MerchantSubscription osoitetta käytettäessä POST, NewService osoitetta käytettäessa XML. 50. Ok paluuosoite Osoite, johon vastaussanoma ohjataan onnistuneen palvelun perustamisen jälkeen. Osoitteen tulee sisältää myös protokolla (http/https). 51. Virhe paluuosoite Osoite, johon vastaussanoma ohjataan, jos perustamisessa tapahtuu virhe. Osoitteen tulee sisältää myös protokolla (http/https). 52. Peruutus-paluuosoite Osoite, johon vastaussanoma ohjataan, jos perustaminen keskeytetään käyttäjän toimesta. Osoitteen tulee sisältää myös protokolla (http/https). 53. Tarkisteen laskentamerkistö Kertoo, missä merkistössä tarkisteen laskentaan käytetty merkkijono oli tarkistetta laskettaessa. Sallitut arvot ovat ISO-8859-1, ISO-8859-15 ja UTF-8, oletus on ISO-8859-1. 54. Tarkistetiedon versio Tarkisteen laskennassa käytetty laskentaversio (algoritmin nimi, katso tarkempi kuvaus Rajapintojen Integrointiohjeesta)
7(8) 55. Tarkiste Sanoman kentistä ja Kauppiaan salaisesta avaimesta laskettu tarkiste. Tarkiste lasketaan seuraavista kentistä: srv_webstorewww 56. Avaimen sukupolvi Kauppiaan salaisen avaimen sukupolvi. 2. PALVELUN KÄYTTÖÖNOTON VASTAUSSANOMAN TIEDOT Kun palvelu perustettiin onnistuneesti, seuraavanlainen tietosisältö välitetään onnistuneen palvelun käyttöönoton jälkeen ok-osoitteeseen (srv_okreturn). Tiedon nimi Arvo Muoto P/V input name= value= 1. Palvelun käyttöönoton versio srv_version 0002 AN4 P 2. Verkkokauppayrityksen y-tunnus srv_businessid AN15 P 3. Verkkokaupan www-osoite srv_webstorewww AN200 P 4. Verkkokaupan tekninen tunnus srv_interfaceuserid AN50 P 5. Verkkokaupan salainen avain srv_interfacecredential AN1056 P 6. KauppiasExtranet-tunnus srv_extranetuserid AN50 P 7. KauppiasExtranet-salasana srv_extranetcredential AN1056 P 8. Palvelun käyttöönoton tila srv_state AN5 P 9. Tarkiste srv_hash AN128 P Kun palvelua ei perustettu, seuraavanlainen tietosisältö välitetään epäonnistuneen tai kauppiaan keskeyttämän palvelun käyttöönoton jälkeen virhe-osoitteeseen (srv_erroreturn) tai keskeytys-osoitteeseen (srv_cancelreturn). Tiedon nimi Arvo Muoto P/V input name= value= 1. Palvelun käyttöönoton versio srv_version 0002 AN4 P 2. Verkkokauppayrityksen y-tunnus srv_businessid AN15 P 3. Verkkokaupan www-osoite srv_webstorewww AN200 P 10. Palvelun käyttöönoton virhekoodi srv_errorcode AN5 P 11. Palvelun käyttöönoton virheen selite srv_errordescription AN1000 P Kenttien selitteet Palvelun käyttöönoton vastaussanoman tiedot 1. Palvelun käyttöönoton versio Palvelun käyttöönottosanoman sisällön määrittelyversio. 2. Verkkokauppayrityksen y-tunnus Verkkokauppaa harjoittavan yrityksen Patentti- ja rekisterihallitukselta saama yritystunnus (y-tunnus) 3. Verkkokaupan www-osoite Verkkokaupan www-osoite, se osoite, jossa Maksuturva-palvelu tulee käyttöön 4. Verkkokaupan tekninen tunnus Suomen Maksuturva Oy:n Kauppiaalle tunnistamista varten antama tunnus rajapintojen käyttöön. 5. Verkkokaupan salainen avain Tekniseen tunnukseen liittyvä salainen avain tarkisteiden laskentaa varten. 6. KauppiasExtranet-tunnus Suomen Maksuturva Oy:n Kauppiaalle tunnistamista varten antama tunnus KauppiasExtranetin käyttöön. 7. KauppiasExtranet-salasana KauppiasExtranetin käyttöön liittyvä salasana. 8. Palvelun käyttöönoton tila Asiakkaan ja palvelun perustamiseen liittyvä tilatieto. 10 = asiakas ja palvelu on perustettu 20 = palvelu on perustettu 30 = aiemmin perustettu palvelu allekirjoitettiin
8(8) 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ä: srv_businessid srv_webstorewww srv_interfaceuserid srv_interfacecredential srv_extranetuserid srv_extranetcredential srv_state Kursivoidut tulivat tarkisteeseen uusina rajapinnan versiossa 1.1 (sanoma 0002). 11. Palvelun käyttöönoton virhekoodi Virheeseen liittyvä tarkennus: 10 = Virheitä rajapinnassa välitetyissä tiedoissa 20 = Verkkokaupalle on jo perustettu palvelu 30 = Tekninen virhe 40 = Kauppias keskeytti palvelun käyttöönoton 12. Palvelun käyttöönoton virheen selite Virheestä riippuvainen selite, joka edelleen selventää mistä virhe johtui (esim. luettelo puuttuvista tai virheellisistä tiedoista).