Maksaminen v4.1. Maksuturva ja eMaksut (pdf)

Transcription

Rajapintakuvaus verkkokaupalle
MAKSAMINEN
Maksuturvan palveluille
Versio 4.1.9
Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected]
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
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
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ä:
Toukokuu 2011
4.1
Uusia kenttiä tarkisteessa:
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
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
määrä
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
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
AN40
AN100
AN100
AN100
N20
V
V
P
P
P
pmt_deliverycity
pmt_deliverycountry
AN100
A2
P
P
EUR
pmt_escrow
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
6(15)
Kentän
numero
39.
40.
41.
42.
43.
44.
45.
Kenttä
Tilausrivin määrän
yksikkö
Tilausrivin toimituksen tai
palvelun suorituksen
ajankohta
bruttohinta per yksikkö
(ALV mukana)
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
dd.mm.yyyy
AN10
10
P
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_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.
7(15)
3.1 Kenttien selitteet - Maksun välityksen tiedot
Kentän
numero
1.
Kenttä
Selite
Toiminnon tunniste
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
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!
Tilausrivin yksittäisen tuotteen nettohinta, eli hinta ilman ALV:a, ei ole alennettu.
Netto- tai bruttohinta on välitettävä, mutta ei molempia!
Tilausrivin tuotteeseen sovellettu ALV-prosentti.
Desimaaliluku kahdella desimaalilla. Esim. 23,00.
Tilausriviin sovellettava alennusprosentti.
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)
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_escrow
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_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
o
o
pmt_row_price_netN
o
pmt_row_vatN
o
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.
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)
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=
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
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
Maksussa käytetty valuutta.
7.
Myyjän kulut
Myyjän kulut (sama kuin pyyntösanomassa). Summa esitetään aina kahden
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
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ä
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>
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/.

Maksaminen v4.1. Maksuturva ja eMaksut (pdf)

Transcription

Similar documents

Asennus- ja käyttöohjeet Käynnistys ja himmennys

Kempact MIG 2530, Pulse 3000

Kansainvälinen toiminta Amistossa

Maksupalvelun integrointiohje (pdf)

lataa Maksuturvan maksupalvelun integrointiohjeet pdf

455kb - Wärtsilä

TerveKuu 5.01 – Muuttuneet ja uudet ominaisuudet 1

SÄÄSTÖPANKIN TUNNISTUSPALVELU KÄYTTÖOHJE