Maksuturva-palvelun rajapintakuvaus verkkokaupalle / MAKSUN PERUUTUS Versio 4.0
2(5) Sisältö 1. Muutokset... 3 2. Maksun peruutuksen tiedot... 3 2.1 Kenttien selitteet Maksun peruutuksen tiedot... 4 3. Maksun peruutuksen vastaussanoman tiedot... 4 3.1 Kenttien selitteet Maksun peruutuksen vastaussanoman tiedot... 5 Vastauskoodien arvot... 5
3(5) 1. MUUTOKSET Muutospvm Helmikuu 2011 Dokumentin versio 4.0 MAKSUN PERUUTUKSEN TIEDOT (IN) Uusia tietoja: Muutos Osaperuutukseen vaatimat uudet tiedot: - Peruutuksen tyyppi (pmtc_canceltype) - Peruutettava rahamäärä (pmtc_cancelamount) Uusia tietoja pyynnön tarkisteessa: - pmtc_version - pmtc_canceltype - pmtc_cancelamount (jos canceltype = PARTIAL_REFUND / PARTIAL_REFUND_AND_RETURN_OF_DELIVERIES) MAKSUN PERUUTUKSEN VASTAUSSANOMAN TIEDOT (OUT) Uusia kenttiä tarkisteessa: - pmtc_version - Muutettu kenttien järjestystä tarkisteessa. Uusi vastauskoodi 31: Peruutustiedot eivät täsmää 2. MAKSUN PERUUTUKSEN TIEDOT Maksun peruutus on sallittu, kun Suomen Maksuturva Oy on vastaanottanut maksun tiedot, mutta hyvitystä ei ole vielä maksettu verkkokaupalle. Verkkokauppa välittää tapahtuman peruutuksen tiedot FORM-tietoryhmässä piilomuuttujina. Tiedot lähetetään osoitteeseen https://www.maksuturva.fi/paymentcancel.pmt Tiedon nimi Arvo Muoto P/V input name= value= 1. Toiminnon tunnus pmtc_action CANCEL AN6 P 2. Sanoman versio pmtc_version 0004 AN4 P 3. Kauppiaan tunnus pmtc_sellerid AN15 P 4. Maksun tunnus pmtc_id AN20 P 5. Maksun rahamäärä pmtc_amount N17 P 6. Maksun valuutta pmtc_currency AN3 P 7. Peruutuksen tyyppi pmtc_canceltype FULL_REFUND / AN40 P PARTIAL_REFUND/ PARTIAL_REFUND_ AND_RETURN_OF_ DELIVERIES 8. Peruutettava rahamäärä pmtc_cancelamount N17 V 9. Vastauksen tyyppi pmtc_resptype XML/HTML AN4 P 10. Paluuosoite pmtc_return AN200 V 11. Tarkistetiedon versio pmtc_hashversion AN10 P 12. Tarkiste pmtc_hash AN128 P 13. Avaimen sukupolvi pmtc_keygeneration N3 P Merkintä AN xx tarkoittaa, että kenttä sisältää enintään xx aakkosnumeerista merkkiä. P tarkoittaa pakollista tietoa ja V valinnaista.
4(5) 2.1 Kenttien selitteet Maksun peruutuksen tiedot Selite 1. Toiminnon tunnus Kutsuttavan toiminnon tunnus (CANCEL). 2. Sanoman versio Tapahtuman peruutussanoman 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. Täsmättävä alkuperäisen maksun kanssa. 5. Maksun rahamäärä Alkuperäisen maksun summa. Summa tulee esittää aina kahden desimaalin tarkkuudella. Desimaalierottimena käytetään pilkkua esim. 94,80 6. Maksun valuutta Alkuperäisessä maksussa käytetty valuutta. 7. Peruutuksen tyyppi Kertoo onko kyseessä koko peruutus (FULL_REFUND) hinnan alennus (PARTIAL_REFUND) osapalautus (PARTIAL_REFUND_AND_RETURN_OF_DELIVERIES) 8. Peruutettava rahamäärä Peruutettava rahamäärä. ANNETAAN VAIN, KUN KYSEESSÄ EI OLE KOKO TILAUKSEN PERUUTUS/PALAUTUS. 9. Vastauksen tyyppi Määrittää missä muodossa vastaussanoma tehdään. Vaihtoehdot ovat HTML ja XML. 10. Paluuosoite Jos vastauksen tyyppi on HTML, niin voidaan määrittää paluuosoite. Jos paluuosoite on määritetty, niin vastauksen tiedot tullaan välittämään suoraan tähän osoitteeseen lisättynä osoitteseen ns. querystring parametreina. 11. Tarkistetiedon versio Tarkisteen laskennassa käytetty laskentaversio (algoritmin nimi, katso tarkempi kuvaus Rajapintojen Integrointiohjeesta) 12. Tarkiste Sanoman kentistä ja Kauppiaan salaisesta avaimesta laskettu tarkiste. Tarkiste lasketaan tiedoista: pmtc_action pmtc_version pmtc_sellerid pmtc_id pmtc_amount pmtc_currency pmtc_canceltype pmtc_cancelamount (jos peruutuksen tyyppi on PARTIAL_REFUND / PARTIAL_REFUND_AND_RETURN_OF_DELIVERIES) 13. Avaimen sukupolvi Kauppiaan salaisen avaimen sukupolvi. 3. MAKSUN PERUUTUKSEN VASTAUSSANOMAN TIEDOT Tiedon nimi Arvo Muoto P/V input name= value= 1. Toiminnon tunniste pmtc_action CANCEL AN6 P 2. Sanoman versio pmtc_version 0004 AN4 P 3. Kauppiaan tunnus pmtc_sellerid AN15 P 4. Maksun tunnus pmtc_id AN20 P 5. Vastauskoodi pmtc_returncode AN2 P 6. Vastausteksti pmtc_returntext AN100 P 7. Tarkiste pmtc_hash AN128 P
5(5) 3.1 Kenttien selitteet Maksun peruutuksen vastaussanoman tiedot 1. Toiminnon tunniste CANCEL Selite 2. Sanoman versio Tapahtuman peruutussanoman 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. Täsmättävä alkuperäisen maksun tunnukseen. 5. Vastauskoodi Kertoo peruutuksen onnistumisen. Vastauskoodien arvot ja selitteet löytyvät kohdasta Vastauskoodien arvot 6. Vastausteksti Kuvaa lyhyesti peruutuksen epäonnistumisen syyn. Peruutuksen onnistuessa tyhjä. 7. 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 tiedoista: pmtc_action pmtc_version pmtc_sellerid pmtc_id pmtc_returntext pmtc_returncode Vastauskoodien arvot HUOM! Järjestystä vaihdettu rajapinnan edellisestä versiosta! Vastauskoodi Lyhyt selite Kuvaus 00 Ok Peruutus on otettu onnistuneesti vastaan. 20 Tapahtumaa ei löytynyt Poikkeustilanne. Tapahtumaa ei löytynyt eikä peruutusta voitu tehdä. 30 Maksu on hyvitetty tai Tapahtumaa ei voi perua koska se on jo käsitelty loppuun joko tapahtuma peruutettu hyvityksen tai peruutuksen muodossa. 31 Peruutustiedot eivät täsmää Myyjän ja ostajan antamat peruutustiedot eivät täsmää. 99 Peruutuksen suoritus epäonnistui Poikkeustilanne. Peruutuksen käsittely epäonnistui.