Rajapintakuvaus verkkokaupalle TAPAHTUMAN TILAN KYSELY Maksuturva- ja emaksut-palvelulle

Transkriptio

1 Rajapintakuvaus verkkokaupalle TAPAHTUMAN TILAN KYSELY Maksuturva- ja emaksut-palvelulle Versio 4.0.3

2 2(8) Sisältö 1. Muutokset Yleistä Tapahtuman tilakyselyn tiedot Kenttien selitteet - Tapahtuman tilakyselyn tiedot Tapahtuman tilakyselyn vastaussanoman tiedot Kenttien selitteet - Tapahtuman tilakyselyn vastaussanoman tiedot... 5 Vastauskoodien arvot... 7 Toimituksen tilakoodien arvot... 8

3 3(8) 1. MUUTOKSET Muutospvm Dokumentin Muutos versio Paluusanoman kuvaukseen lisätty pmt_paymentmethod -kentän kuvaus. Tammikuu 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) 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 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 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) Tiedon pmtq_amount kuvausta korjattu Vastauksen tyyppinä tuetaan ainoastaan XML-muotoa.

4 4(8) 2. YLEISTÄ Tämä rajapintakuvaus mahdollistaa molempien palveluiden sekä Maksuturva- että emaksut-palvelun tapahtuman tilakyselyn integroinnin. Huomioithan, että Maksuturva-palvelussa vastauskoodien määrä on laajempi kuin emaksutpalvelussa. Ainoastaan Maksuturva-palvelua koskevat vastauskoodit on merkitty dokumenttiin tekstillä. 3. TAPAHTUMAN TILAKYSELYN TIEDOT Tapahtuman tilan kysely on sallittu maksulle heti kun maksun tiedot on vastaanotettu Suomen Maksuturva Oy:lle. Verkkokauppa välittää tapahtuman kyselyn tiedot FORM-tietoryhmässä piilomuuttujina. Tiedot lähetetään osoitteeseen Kentän Kenttä Tiedon nimi Arvo Muoto P/V numero input name= value= 1. Toiminnon tunniste pmtq_action PAYMENT_STATUS_QUERY AN50 P 2. Sanoman versio pmtq_version 0004 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ä AN xx tarkoittaa, että kenttä sisältää enintään xx aakkosnumeerista merkkiä. P tarkoittaa pakollista tietoa ja V valinnaista. 3.1 Kenttien selitteet - Tapahtuman tilakyselyn tiedot Kentän Kenttä numero 1. Toiminnon tunniste PAYMENT_STATUS_QUERY Selite 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 muoto 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. 4. TAPAHTUMAN TILAKYSELYN 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 merkistön merkkejä.

5 5(8) Kentän Kenttä Tiedon nimi Arvo Muoto P/V numero input name= value= 1. Toiminnon tunniste pmtq_action PAYMENT_STATUS_QUERY AN50 P 2. Sanoman versio pmtq_version 0004 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. Ostajan nimi luottotiedoista pmtq_buyername AN100 V 13. Ostajan osoite 1 pmtq_buyeraddress1 AN100 V luottotiedoista 14. Ostajan osoite 2 pmtq_buyeraddress2 AN100 V luottotiedoista 15. Ostajan postinumero pmtq_buyerpostalcode AN100 V luottotiedoista 16. Ostajan kaupunki pmtq_buyercity AN100 V luottotiedoista 17. Tarkiste pmtq_hash AN128 P 4.1 Kenttien selitteet - Tapahtuman tilakyselyn vastaussanoman tiedot Kentän Kenttä numero 1. Toiminnon tunniste PAYMENT_STATUS_QUERY Selite 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, 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

6 6(8) 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 FI80 FI90 Selite (tulee näkyä verkkokaupan hallintapaneelissa) Maksuturva-Tilisiirto Maksuturva-Nordea E-maksu Maksuturva-Sampo Pankki Verkkomaksu Maksuturva-Aktia/Sp/Pop-maksu (Aktia) Maksuturva-Aktia/Sp/Pop-maksu (Paikallisosuuspankki) 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-Lasku (luotto- ja rahoituspalvelu) Maksuturva-Osamaksu (luotto- ja rahoituspalvelu) Maksuturva-Paypal Maksuturva-KV-tilisiirto Jos ostajan valitsema maksutapa on FI70 (lasku) tai FI71 (osamaksu): Ohjelmiston tai kauppiaan täytyy maksun kuittauksen vastaanottamisen jälkeen suorittaa maksun tilan kysely (PaymentStatusQuery.pmt) tai hakea KauppiasExtranetista luottotietohausta palautuneet ostajan osoitetiedot. Näissä tapauksissa toimitus on tehtävä luottotietohausta palautuneeseen osoitteeseen, eikä ostajan itse verkkokauppaan syöttämään osoitteeseen. 11. Escrow käytössä Kertoo onko kyseessä Escrow-maksu. Arvot: Y/N Maksuturvan kautta tehdyissä maksuissa arvona palautetaan aina Y ja emaksut-palvelun kautta tehdyissä maksuissa aina N. 12. Ostajan nimi luottotiedoista Laskutusosoitteen (ostajan) nimi luottotiedoista. (palautetaan ainoastaan, mikäli käytetty luotto-/rahoituspalvelua) 13. Ostajan osoiterivi 1 luottotiedoista Laskutusosoitteen (ostajan) postiosoite 1 (katuosoite tai postilokero) luottotiedoista (palautetaan ainoastaan, mikäli käytetty luotto- /rahoituspalvelua) 14. Ostajan osoiterivi 2 luottotiedoista Laskutusosoitteen (ostajan) postiosoite 2 (katuosoite tai postilokero) luottotiedoista(palautetaan ainoastaan, mikäli käytetty luotto- /rahoituspalvelua) 15. Ostajan postinumero luottotiedoista Laskutusosoitteen (ostajan) postinumero luottotiedoista. (palautetaan ainoastaan, mikäli käytetty luotto-/rahoituspalvelua) 16. Ostajan kaupunki luottotiedoista Laskutusosoitteen (ostajan) kaupunki luottotiedoista. (palautetaan ainoastaan, mikäli käytetty luotto-/rahoituspalvelua) 17. 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)

7 7(8) Vastauskoodien arvot Vastauskoodi Lyhyt selite Kuvaus 00 Ei löydy 01 Kyselyn suoritus epäonnistui 10 Odottaa maksua, tilisiirto Ei maksettu, maksun saapuminen epävarmaa Odottaa maksua, mutta toimitusvahvistus annettu Maksettu mutta toimitusvahvistus on antamatta Maksettu, tilaus toimituksessa / kauppiasta ei ole vielä hyvitetty 40 Maksu on hyvitetty kauppiaalle Maksaja on peruuttanut tapahtuman Maksaja on peruuttanut osan tapahtumasta (hinnan alennus) Maksaja on peruuttanut osan tapahtumasta (hinnan alennus + tuotteiden palautus) Poikkeustilanne. Haettua tapahtumaa ei löydy Maksuturvasta. Poikkeustilanne. Haetun tapahtuman haku epäonnistui Maksuturvasta. Asiakas on valinnut maksutavaksi tilisiirron ja maksua ei ole vielä todettu saapuneeksi. Toimitus käynnistetään yleensä vasta kun tapahtuman tila on 20 / maksettu. 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ää. 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ää. Toimitus on kesken tai toimituksen jälkeinen karenssiaika on kesken. Hyvitystä verkkokauppiaalle ei ole vielä tehty. Maksu on hyvitetty verkkokauppiaalle. Maksu näkyy verkkokauppiaan ilmoittamalla tilillä pankkiyhteydestä riippuen muutaman arkipäivän sisällä. Tapahtuma on loppuun käsitelty. 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.

8 8(8) Vastauskoodi Lyhyt selite Kuvaus 95 Maksaja on tehnyt reklamaation 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. 99 Peruutettu (Myyjä peruuttanut / hyväksynyt ostajan peruutuksen) Olet tehnyt peruutuksen Maksuturvalle. Tapahtuma on loppuun käsitelty. Toimituksen tilakoodien arvot Tilakoodi Lyhyt selite Kuvaus 00 Koodi vastaanotettu 10 Toimitettavana 20 Odottaa noutoa 80 Toimitettu Perillä. Maksuturva on vastaanottanut koodin, mutta toimituksen ei ole todettu edenneen. Toimituksen on todettu edenneen. Tämä tapahtuu joko tietyn ajan kuluttua (seurantakoodittomat) tai kuljetusyrityksen järjestlmästä tehdyn kyselyn (seurantakoodilliset) perusteella. 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.