Rajapintakuvaus verkkokaupalle TAPAHTUMAN TILAN KYSELY Maksuturva- ja emaksut-palvelulle Versio 5.0.1 Lokakuu 2013
2(10) Sisältö 1 Muutokset... 3 2 Yleistä... 5 3 Tapahtuman tilan kyselyn tiedot... 5 3.1 Kenttien selitteet - Tapahtuman tilan kyselyn tiedot... 5 4 Tapahtuman tilan kyselyn vastaussanoman tiedot... 6 4.1 Kenttien selitteet - Tapahtuman tilan kyselyn vastaussanoman tiedot... 6 4.1.1 Vastauskoodien arvot... 8 4.1.2 Toimituksen tilakoodien arvot Maksuturva-palveluille)... 9 5 Miten ja milloin käytetään... 10
3(10) 1 MUUTOKSET Muutospäivä Dokumentin Muutos versio Marraskuu 2010 2.5 Paluusanoman kuvaukseen lisätty pmt_paymentmethod -kentän kuvaus. Tammikuu 2011 4.0 Uusi rajapintaversio: 0004 KYSELYN PYYNNÖN TIEDOT (IN) Uusia tietoja: - pmtq_action (PAYMENT_STATUS_QUERY) Uusia tietoja pyynnön tarkisteessa: - pmtq_action (PAYMENT_STATUS_QUERY) - pmtq_version KYSELYN VASTAUSSANOMAN TIEDOT (OUT) Syyskuu 2011 4.0.1 Lisätiedot emaksujen integrointiin. Versiosta 0004 alkaen vastaussanoman enkoodaus on UTF-8. Lisäksi ainoa tuettu vastauksen muoto on XML, eli HTML ei ole enää tuettuna. Nämä muutokset johtuvat siitä, että osamaksulle ja laskulle palautettavat luottotietohausta saadut ostajan osoitetiedot voivat sisältää muitakin kuin ISO-8859-1 merkistön merkkejä. Uusia tietoja: - pmtq_action (PAYMENT_STATUS_QUERY) - Tulevien ominaisuuksien tueksi (valinnainen): (pmtq_escrow) - Valittu maksutapa (valinnainen): (pmtq_paymentmethod) Uusia tietoja pyynnön tarkisteessa: - pmtq_action (PAYMENT_STATUS_QUERY) - pmtq_version - pmtq_paymentmethod - pmtq_escrow Maaliskuu 2012 4.0.2 Tiedon pmtq_amount kuvausta korjattu. Ostajan tiedot luottotiedoista (palautetaan ainoastaan, mikäli käytetty luotto-/rahoituspalvelua): - Laskutusosoitteen (ostajan) nimi luottotiedoista (pmtq_buyername) - Laskutusosoitteen (ostajan) osoiterivi 1 luottotiedoista (pmtq_buyeraddress1) - Laskutusosoitteen (ostajan) osoiterivi 2 luottotiedoista (pmtq_buyeraddress2) - Laskutusosoitteen (ostajan) postinumero luottotiedoista (pmtq_buyerpostalcode) - Laskutusosoitteen (ostajan) kaupunkin luottotiedoista (pmtq_buyercity) Elokuu 2012 4.0.3 Vastauksen tyyppinä tuetaan ainoastaan XML-muotoa. Toukokuu 2013 4.0.4 Poistettu ostajan osoitetiedot vastauksesta, sekä niihin liittyvät ohjeistukset.
4(10) Muutospäivä Dokumentin versio Maaliskuu 2012 5.0 Uusi rajapintaversio: 0005 Muutos KYSELYN VASTAUSSANOMAN TIEDOT (OUT) Uusia tietoja: - pmtq_certification - pmtq_externalcode1 - pmtq_externalcode2 - pmtq_externaltext - pmtq_paymentstarttimestamp - pmtq_paymentdate Uusia tietoja vastauksen tarkisteessa: - pmtq_certification (jos saatavilla) - pmtq_paymentdate (jos saatavilla) Lisäksi: Tiedon pmtq_amount kuvausta korjattu. Lokakuu 2013 5.0.1 Lisätty kappale Miten ja milloin käytetään
5(10) 2 YLEISTÄ Tämä rajapintakuvaus mahdollistaa molempien palveluiden sekä Maksuturva- että emaksut-palvelun tapahtuman tilan kyselyn integroinnin. Huomioithan, että Maksuturva-palvelussa vastauskoodien määrä on laajempi kuin emaksutpalvelussa. Ainoastaan Maksuturva-palvelua koskevat vastauskoodit on merkitty dokumenttiin tekstillä. 3 TAPAHTUMAN TILAN KYSELYN TIEDOT Tapahtuman tilan kysely on sallittu maksulle heti kun maksun tiedot on vastaanotettu ja tallennettu Suomen Maksuturva Oy:lle. Verkkokauppa välittää tapahtuman kyselyn tiedot FORM-tietoryhmässä piilomuuttujina. Tiedot lähetetään osoitteeseen https://www.maksuturva.fi/paymentstatusquery.pmt (tai http://test1.maksuturva.fi/paymentstatusquery.pmt testiympäristössä) # Kenttä Tiedon nimi Arvo Muoto P/V input name= value= 1. Toiminnon tunniste pmtq_action PAYMENT_STATUS_QUERY AN50 P 2. Sanoman versio pmtq_version 0005 AN4 P 3. Kauppiaan tunnus pmtq_sellerid AN15 P 4. Maksun tunnus pmtq_id AN20 P 5. Vastauksen tyyppi pmtq_resptype XML AN4 P 6. Tarkistetiedon versio pmtq_hashversion AN10 P 7. Tarkiste pmtq_hash AN128 P 8. Avaimen sukupolvi pmtq_keygeneration N3 P Merkintä ANxx tarkoittaa, että kenttä sisältää enintään xx aakkosnumeerista merkkiä. P tarkoittaa pakollista tietoa ja V valinnaista. 3.1 Kenttien selitteet - Tapahtuman tilan kyselyn tiedot # Kenttä Selite 1. Toiminnon tunniste PAYMENT_STATUS_QUERY 2. Sanoman versio Tapahtuman kyselysanoman sisällön määrittelyversio. 3. Kauppiaan tunnus Suomen Maksuturva Oy:n Kauppiaalle tunnistamista varten antama tunnus. 4. Maksun tunnus Kauppiaan maksulle antama yksilöivä tunnus. 5. Vastauksen tyyppi Määrittää missä muodossa vastaussanoma tehdään. Ainoa tuettu vaihtoehto on XML. 6. Tarkistetiedon versio Tarkisteen laskennassa käytetty laskentaversio (algoritmin nimi, katso tarkempi kuvaus Rajapintojen Integrointiohjeesta) 7. Tarkiste Sanoman kentistä ja Kauppiaan salaisesta avaimesta laskettu tarkiste. Tarkiste lasketaan kentistä: pmtq_action pmtq_version pmtq_sellerid pmtq_id Tarkemmat ohjeet tarkisteen laskennassa käytetyn merkkijonon muodostamisesta lötyyy SMT Rajapinnat Integrointiohje -dokumentin Tarkisteen laskenta -kappaleesta. 8. Avaimen sukupolvi Kauppiaan salaisen avaimen sukupolvinumero.
6(10) 4 TAPAHTUMAN TILAN KYSELYN VASTAUSSANOMAN TIEDOT Versiosta 0004 alkaen vastaussanoman enkoodaus on UTF-8. Lisäksi ainoa tuettu vastauksen muoto on XML, eli HTML ei ole enää tuettuna. Nämä muutokset johtuvat siitä, että osamaksulle ja laskulle palautettavat luottotietohausta saadut ostajan osoitetiedot voivat sisältää muitakin kuin ISO-8859-1 tai 15 merkistön merkkejä. # Kenttä Tiedon nimi Arvo Muoto P/V input name= value= 1. Toiminnon tunniste pmtq_action PAYMENT_STATUS_QUERY AN50 P 2. Sanoman versio pmtq_version 0005 AN4 P 3. Kauppiaan tunnus pmtq_sellerid AN15 P 4. Maksun tunnus pmtq_id AN20 P 5. Maksun rahamäärä pmtq_amount AN17 P 6. Vastauskoodi pmtq_returncode AN2 P 7. Vastausteksti pmtq_returntext AN100 P 8. Seurantakoodit pmtq_trackingcodes AN400 V 9. Myyjän kulut pmtq_sellercosts AN17 V 10. Maksutapa pmtq_paymentmethod AN4 V 11. Escrow käytössä pmtq_escrow Maksuturva=Y, emaksut=n AN1 V 12. Todennustieto pmtq_certification Y,N A1 V 13. Maksupalvelun tarjoajan pmtq_externalcode1 AN50 V koodi 1 14. Maksupalvelun tarjoajan pmtq_externalcode2 AN50 V koodi 2 15. Maksupalvelun tarjoajan pmtq_externaltext AN200 V vastausteksti 16. Hetki, jolloin maksaja siirtyi pmtq_paymentstarttimestamp dd.mm.yyyy hh:mm:ss AN19 V maksamaan 17. Maksupäivä pmtq_paymentdate dd.mm.yyyy AN10 V 18. Tarkiste pmtq_hash AN128 P 4.1 Kenttien selitteet - Tapahtuman tilan kyselyn vastaussanoman tiedot # Kenttä Selite 1. Toiminnon tunniste PAYMENT_STATUS_QUERY 2. Sanoman versio Tapahtuman kyselysanoman sisällön määrittelyversio. 3. Kauppiaan tunnus Suomen Maksuturva Oy:n Kauppiaalle tunnistamista varten antama tunnus. 4. Maksun tunnus Kauppiaan maksulle antama yksilöivä tunnus. 5. Maksun rahamäärä Sama kuin alkuperäisen maksutapahtuman pmt_amount tieto. Maksun rahamäärää tulee verrata tilauksen rahamäärään, sen on täsmättävä. Mikäli maksua ei löydy (vastauskoodi on 00 ), tässä kentässä on 0,00. 6. Vastauskoodi Kertoo maksun ja tapahtuman tilan. Katso vastauskoodien arvot ja niiden merkitykset kohdasta Vastauskoodien arvot. 7. Vastausteksti Lyhyt sanallinen kuvaus maksun tilasta. 8. Seurantakoodit Tapahtumaan liittyen Maksuturvalle välitetyt toimitustiedot/seurantakoodit. Muoto [XX XY YY] 0-n kpl peräkkäin riippuen montako toimitustietoa/seurantakoodia tapahtumalle on välitetty. XX = Toimitustapakoodi XY = Seurantakoodi tai koodittomissa välitetty teksti YY = Toimituksen tila ks Toimituksen tilakoodien arvot taulukko. 9. Myyjän kulut Jos alkuperäisessä maksussa oli mukana pmt_sellercosts, se tieto palautuu tässä. Mikäli tietoa ei ollut alkuperäisessä maksussa, tässä kentässä voi olla arvo 0,00
7(10) 10. Maksutapa Kertoo, millä maksutavalla maksu on suoritettu. Selitteet voivat muuttua, eikä niihin perustuen saa toteuttaa logiikkaa. Arvot ovat: Arvo FI00 FI01 FI02 FI03 FI04 FI05 FI06 FI07 FI08 FI09 FI10 FI50 FI70 FI71 Selite (tulee näkyä verkkokaupan hallintapaneelissa) Maksuturva - Tilisiirto Maksuturva - Nordea E-maksu Maksuturva - Danske Bank Verkkomaksu Maksuturva - Aktia/Sp/Pop-maksu (Aktia) Maksuturva - Aktia/Sp/Pop-maksu (POP Pankki) Maksuturva - Tapiola Pankki Verkkomaksu Maksuturva - Osuuspankki Verkkomaksu Maksuturva - Ålandsbanken E-maksu Maksuturva - Aktia/Sp/Pop-maksu (Säästöpankki) Maksuturva - Handelsbanken Verkkomaksu Maksuturva - S-pankki Verkkomaksu Maksuturva - Korttimaksu (Visa, Visa Electron, MasterCard) Maksuturva - SveaWebPay Lasku (luotto- ja rahoituspalvelu) Maksuturva - SveaWebPay Osamaksu (luotto- ja rahoituspalvelu) 11. Escrow käytössä Kertoo onko kyseessä Escrow-maksu. Arvot: Y/N Maksuturvan kautta tehdyissä maksuissa arvona palautetaan aina Y ja emaksutpalvelun kautta tehdyissä maksuissa aina N. 12. Todennustieto Y = maksu on todennettu, eli sen maksamisessa on käytetty jotain ostajan tunnistuskeinoa. Svea-maksutapojen yhteydessä Maksuturvalla on lisäksi tieto käyttäjän identiteetistä, muiden maksutapojen kanssa ei. N = maksua ei ole todennettu, tai todennuksesta ei ole tietoa. 13. Maksupalvelun tarjoajan koodi 1 Informatiivinen lisätieto. Käytetään virhetilanteissa välittämään ulkoisen maksupalveluntarjoajan virhekoodi 1. Korttimaksuille Luottokunnan LKPRC -koodi. OK-tapauksessa tässä kentässä voidaan välittää arkistointitunnus informatiivisena tietona. 14. Maksupalvelun tarjoajan koodi 2 Informatiivinen lisätieto. Käytetään virhetilanteissa välittämään ulkoisen maksupalveluntarjoajan virhekoodi 2. Korttimaksuille Luottokunnan LKSRC koodi. 15. Maksupalvelun tarjoajan vastausteksti Informatiivinen lisätieto. Teksti joko onnistumisesta tai virheestä. Jos ulkoinen maksupalveluntarjoaja ei palauta mitään erityistä tekstiä, tämä kenttä voi olla tyhjä, tai siinä voi olla maksun arkistointitunnus tai muu yksilöivä oleva tieto maksupalveluntarjoajalta. 16. Hetki, jolloin maksaja siirtyi maksamaan dd.mm.yyyy hh:mm:ss Ajanhetki, milloin ostaja siirtyi maksupalvelun tarjoajalle. 17. Maksupäivä dd.mm.yyyy Päivä, jona ostaja maksoin. Tai jos em. tietoa ei ole saatavilla, päivä jona Maksuturva näki rahat tiliotteella. 18. 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 kentistä: pmtq_action pmtq_version pmtq_sellerid pmtq_id pmtq_amount pmtq_returncode pmtq_returntext pmtq_sellercosts (jos saatavilla) pmtq_paymentmethod (jos saatavilla) pmtq_escrow (jos saatavilla) pmtq_certification (jos saatavilla) pmtq_paymentdate (jos saatavilla)
8(10) 4.1.1 Vastauskoodien arvot Vastauskoodi Lyhyt selite Kuvaus 00 Ei maksettu. Jos lisäksi pmtq_amount = 0,00: Tilausta ei ole olemassakaan TAI se on luotu muttei ole edetty maksamiseen asti. 00 Ei maksettu. Jos vastauksesta löytyy arvot tiedoille pmtq_paymentmethod ja pmtq_amount: Tilaus on luotu ja maksutapa valittu, mutta Maksuturvalla ei ole (vielä) tietoa, onko maksaminen onnistunut. Ei maksettu. Jos lisäksi pmtq_amount = 0,00: Tilausta ei ole olemassakaan TAI se on luotu muttei ole edetty maksamiseen asti. Ei maksettu. Jos vastauksesta löytyy arvot tiedoille pmtq_paymentmethod ja pmtq_amount: Tilaus on luotu ja maksutapa valittu, mutta Maksuturvalla ei ole (vielä) tietoa, onko maksaminen onnistunut. 01 Kyselyn suoritus epäonnistui Poikkeustilanne. Haetun tapahtuman haku epäonnistui Maksuturvasta. 10 Odottaa maksua, tilisiirto Asiakas on valinnut maksutavaksi tilisiirron ja maksua ei ole vielä todettu saapuneeksi. Toimitus käynnistetään yleensä vasta kun tapahtuman tila on 20 / maksettu. 11 Ei maksettu, maksun saapuminen epävarmaa Asiakas on siirtynyt tilisiirtosivulle ja on nähnyt maksun tiedot, mutta ei ole vahvistanut toimeksiantoa Maksuturvalle eikä näin ollen myöskään palannut verkkokauppaan tilauksen vahvistukseen.tapahtumalle voi tulla maksu, jolloin se siirtyy tilaan 20 / maksettu ja toimituksen voi käynnistää. 15 20 Odottaa maksua, mutta toimitusvahvistus annettu Maksettu mutta toimitusvahvistus on antamatta Asiakas on valinnut maksutavaksi tilisiirron ja maksua ei ole vielä todettu saapuneeksi. Tilauksen toimitustieto on kuitenkin annettu. Yleensä toimitusta ei käynnistetä ellei maksua ole todettu maksetuksi (eli ellei se ole siirtynyt tilaan 20 / maksettu). Hyvitystä verkkokauppiaalle ei tehdä vaikka toimitus menisi perille asti ellei maksua ole todettu maksetuksi. Asiakas on maksanut tilauksen Maksuturvan asiakasvarat -tilille, mutta toimitusvahvistusta ei ole vielä välitetty Maksuturvaan. Toimitus tulee käynnistää ja toimitustiedot tulisi välitää. 30 Maksettu, tilaus toimituksessa / kauppiasta ei ole vielä hyvitetty Toimitus on kesken tai toimituksen jälkeinen karenssiaika on kesken. Hyvitystä verkkokauppiaalle ei ole vielä tehty. 40 Maksu on hyvitetty kauppiaalle Maksu on hyvitetty verkkokauppiaalle. Maksu näkyy verkkokauppiaan ilmoittamalla tilillä pankkiyhteydestä riippuen muutaman arkipäivän sisällä. Tapahtuma on loppuun käsitelty. 91 92 93 95 Maksaja on peruuttanut tapahtuman Maksaja on peruuttanut osan tapahtumasta (hinnan alennus) Maksaja on peruuttanut osan tapahtumasta (hinnan alennus + tuotteiden palautus) Maksaja on tehnyt reklamaation Asiakas on tehnyt peruutuksen Maksuturvalle. Tapahtuma odottaa peruutusvahvistusta verkkokauppiaalta. Yleensä verkkokauppias peruuttaa tapahtuman vasta kuin mahdollinen tuotepalautus on vastaanotettu. Mikäli tuotetta ei ole ehditty lähettää, voi peruutuksen tehdä heti. Peruutuksen jälkeen rahat palautetaan asiakkaalle. Asiakas ehdottaa hinnan alennusta tilaukseen. Hinnan alennus odottaa vahvistusta verkkokauppiaalta. Mikäli tuotetta ei ole ehditty lähettää, voi hinnan alennuksen tehdä heti. Kauppiaan hyväksynnän jälkeen sovittu summa palautetaan asiakkaalle. Asiakas ehdottaa hinnan alennusta ja joidenkin tuotteiden palautusta. Peruutus odottaa vahvistusta verkkokauppiaalta. Yleensä verkkokauppias peruuttaa tapahtuman vasta kuin mahdollinen tuotepalautus on vastaanotettu. Mikäli tuotetta ei ole ehditty lähettää, voi peruutuksen vahvistaa heti. Kauppiaan hyväksynnän jälkeen sovittu summa palautetaan asiakkaalle. Maksaja on tehnyt reklamaation. Kauppiaan on sovittava ostajan kanssa, mitä tilaukselle tehdään. Sen jälkeen ostaja voi peruuttaa reklamaation ja tapahtumalle voidaan tehdä valitun kaltainen peruutus tai tapahtuman voidaan antaa edetä normaalisti.
9(10) Vastauskoodi Lyhyt selite Kuvaus 99 Peruutettu (Myyjä peruuttanut / hyväksynyt ostajan peruutuksen) 4.1.2 Toimituksen tilakoodien arvot Maksuturva-palveluille) Olet tehnyt peruutuksen Maksuturvalle. Tapahtuma on loppuun käsitelty. Tilakoodi Lyhyt selite Kuvaus 00 Koodi vastaanotettu Maksuturva on vastaanottanut koodin, mutta toimituksen ei ole todettu edenneen. 10 Toimitettavana Toimituksen on todettu edenneen. Tämä tapahtuu joko tietyn ajan kuluttua (seurantakoodittomat) tai kuljetusyrityksen järjestlmästä tehdyn kyselyn (seurantakoodilliset) perusteella. 20 Odottaa noutoa Seurantakoodilla suoritetulla kyselyllä on saatu kuljetusyritykseltä vastaus, joka ilmaisee lähetyksen saapuneen toimipisteeseen vastaanottajan noudettavaksi. Tämä tila on myös kotiin kuljetettavilla toimituksilla, joiden tila ilmaisee, että pakettia ollaan toimittamassa perille. 80 Toimitettu Perillä.
10(10) 5 MITEN JA MILLOIN KÄYTETÄÄN Tapahtuman tilan kyselyä suositellaan käytettävän myös niiden tilausten tapauksessa, jotka on peruutettu ennen maksamista tai vaikuttavat siltä. Eli myös niiden tapahtumien tilaa tulisi kysellä, joiden tapauksessa ostaja on palannut verkkokauppaan peruutus- tai virhepaluuosoitteella. Sopiva ajankohta ensimmäiselle tilan kyselylle on yksi (1) tai kaksi (2) tuntia tilauksen maksamisen aloittamisen jälkeen. Tällä tavoin tulee hoidettua suurin osa tilanteista. Mikäli Maksuturva ei tiedä maksun tilaa tuona ajanhetkenä, kysellään maksun tilaa pankista. Joissakin harvinaisissa, mutta ajoittain ilmenevissä, tapauksissa maksun tilan kysely pankista ei koskaan onnistukaan, mutta sitten myöhemmin yhden tai kahden pankkipäivän kuluttua ostajan rahat löydetäänkin Maksuturvan asiakasvaratpankkitililtä. Kun näin tapahtuu, Maksuturva merkitsee maksun maksetuksi, mistä eteenpäin Tapahtuman tilan kysely - rajapinta vastaa verkkokaupalle maksun olevan maksettu. Tästä johtuen tilauksille, joiden maksun tila on epäselvä, olisi suotavaa kysellä tilaa Tapahtuman tilan kysely -rajapinnan kautta esim. kerran päivässä joidenkin pankkipäivien ajan tilauksen luomisesta alkaen.