4 - Forritunarskil

Upplýsingar um prófanavefslóð Greiðslusíðu Valitor og fleira tengt prófunum má finna í kafla 2.

Þegar kaupandi er sendur á Greiðslusíðu Valitor þarf að senda neðangreindar færibreytur með.

Hægt er að nota bæði HTTP GET og HTTP POST.

4.1 - Parameters

Svæði	Type	Len. min	Len. max	Notk.	Lýsing
MerchantID	N	1	9	M	Einkvæmt auðkenni söluaðila.
Language	A	2	2	O	Tungumál. IS er sjálfgefið ef ekkert er sent inn. Leyfileg gildi: IS = íslenska EN = enska DA = danska DE = þýska
Currency	A	3	3	M	Gjaldmiðill, t.d. ISK. Verður að passa við gjaldmiðil sem er á samningi söluaðila.
AuthorizationOnly	N	1	1	M	Ekki notað í dag. Verður að nota gildið 0.
ReferenceNumber	S	0	100	O	Einkvæmt tilvísunarnúmer söluaðila.
Product_X_Description	S	1	500	M	Lýsing á vöru. X stendur fyrir tölustaf frá 1 til 500. Ef verið er að nota HTTP GET er best að HTML enkóða þennan streng og URL enkóða strenginn ef verið er að nota HTTP POST. ATH! Ef CreateVirtualCardOnly færibreytan er sett sem 1 þá skal sleppa þessari færibreytu.
Product_X_Quantity	N	1	5	M	Magn vöru. X stendur fyrir tölustaf frá 1 til 500. ATH! Ef CreateVirtualCardOnly færibreytan er sett sem 1 þá skal sleppa þessari færibreytu.
Product_X_Price	D	1	12	M	Verð á einni einingu af vörunni. Nota skal kommu til að aðgreina aukastafi fyrir erlenda gjaldmiðla. X stendur fyrir tölustaf frá 1 til 500. ATH! Ef CreateVirtualCardOnly færibreytan er sett sem 1 þá skal sleppa þessari færibreytu.
Product_X_Discount	D	1	12	M	Upphæð afsláttar á vöru per einingu. Nota skal kommu til að aðgreina aukastafi fyrir erlenda gjaldmiðla. X stendur fyrir tölustaf frá 1 til 500. ATH! Ef CreateVirtualCardOnly færibreytan er sett sem 1 þá skal sleppa þessari færibreytu.
PaymentSuccessfulURL	S	0	500	O	Slóð sem birtist á kvittanasíðu og bendir notanda á að halda áfram á vef söluaðila. Hægt er að hafa færibreytur (e.parameter) á þessari slóð. Greiðslusíðan bætir færibreytum sem innihalda upplýsingar um söluna aftan við slóðina. Ef verið er að nota HTTP GET er best að HTML enkóða þennan streng. Sjá nánar í kafla 4.1.2.
PaymentSuccessfulURLText	S	0	500	O	Texti sem birtist á tengli (PaymentSuccessfulURL) sem birtist á kvittanasíðu.
PaymentSuccessfulAutomaticRedirect	N	1	1	O	0 eða 1. Segir til um hvort flytja eigi kaupanda sjálfkrafa yfir á PaymentSuccessfulURL ef að greiðsla tekst. ATH! Ef þessi færibreyta er sett á 1 þá verður söluaðili að birta kvittun/staðfestingu fyrir kaupum á sinni síðu.
PaymentSuccessfulServerSideURL	S	0	500	O	Slóð sem Valitor kallar á til að láta söluaðila vita að greiðsla tókst. Hægt er að hafa færibreytur (e.parameter) á þessari slóð. Þessi síða þarf að skila HTTP Status Code 200 og verður að svara á porti 80 (HTTP) eða 443 (HTTPS). Greiðslusíðan bætir færibreytum sem innihalda upplýsingar um söluna aftan við slóðina. Ef verið er að nota HTTP GET er best að HTML enkóða þennan streng. Sjá nánar í kafla 4.1.2.
PaymentCancelledURL	S	0	500	O	Slóð sem notandi er sendur á ef hann hættir við kaup, þ.e. smellir á ”Hætta við” hnapp. Ef verið er að nota HTTP GET er best að HTML enkóða þennan streng.
DigitalSignature	S	0	500	M	MD5/SHA256 hash sem notað er til að tryggja réttmæti upplýsinga sem sendar eru á Greiðslusíðuna. Sjá nánar í kafla 4.1.1.
SessionExpiredTimeoutInSeconds	N	0	9	O	Ef að þetta gildi er sent inn þá er kaupandi sendur á SessionExpiredRedirectURL þegar tíminn er liðinn.
SessionExpiredRedirectURL	S	0	500	O	Slóð sem notandi er sendur á ef að session rennur út. Ef verið er að nota HTTP GET er best að HTML enkóða þennan streng.
DisplayBuyerInfo	N	1	1	O	0 eða 1. Segir til um hvort að birta eigi innsláttarsvæði fyrir kennitölu, nafn, heimilisfang, póstnúmer, stað, land, síma, netfang og athugasemdir kaupanda.
RequireSSN	N	1	1	O	0 eða 1. Segir til um hvort að svæði fyrir kennitölu kaupanda verði að vera útfyllt.
RequireName	N	1	1	O	0 eða 1. Segir til um hvort að svæði fyrir nafn kaupanda verði að vera útfyllt.
RequireAddress	N	1	1	O	0 eða 1. Segir til um hvort að svæði fyrir heimilisfang kaupanda verði að vera útfyllt.
RequirePostalCode	N	1	1	O	0 eða 1. Segir til um hvort að svæði fyrir póstnumer kaupanda verði að vera útfyllt.
RequireCity	N	1	1	O	0 eða 1. Segir til um hvort að svæði fyrir stað kaupanda verði að vera útfyllt.
RequireCountry	N	1	1	O	0 eða 1. Segir til um hvort að svæði fyrir land kaupanda verði að vera útfyllt.
RequirePhone	N	1	1	O	0 eða 1. Segir til um hvort að svæði fyrir síma kaupanda verði að vera útfyllt.
RequireEmail	N	1	1	O	0 eða 1. Segir til um hvort að svæði fyrir netfang kaupanda verði að vera útfyllt.
RequireComments	N	1	1	O	0 eða 1. Segir til um hvort að svæði fyrir athugasemdir kaupanda verði að vera útfyllt.
HideSSN	N	1	1	O	0 eða 1. Segir til um hvort að fela eigi svæði fyrir kennitölu kaupanda.
HideName	N	1	1	O	0 eða 1. Segir til um hvort að fela eigi svæði fyrir nafn kaupanda.
HideAddress	N	1	1	O	0 eða 1. Segir til um hvort að fela eigi svæði fyrir heimilisfang kaupanda.
HidePostalCode	N	1	1	O	0 eða 1. Segir til um hvort að fela eigi svæði fyrir póstnumer kaupanda.
HideCity	N	1	1	O	0 eða 1. Segir til um hvort að fela eigi svæði fyrir stað kaupanda.
HideCountry	N	1	1	O	0 eða 1. Segir til um hvort að fela eigi svæði fyrir land kaupanda.
HidePhone	N	1	1	O	0 eða 1. Segir til um hvort að fela eigi svæði fyrir síma kaupanda.
HideEmail	N	1	1	O	0 eða 1. Segir til um hvort að fela eigi svæði fyrir netfang kaupanda.
HideComments	N	1	1	O	0 eða 1. Segir til um hvort að fela eigi svæði fyrir athugasemdir kaupanda.
IsCardLoan	N	1	1	O	0 eða 1. Segir til um hvort að kaup séu kortalán. Ef ekkert er sett í þennan reit fer greiðsla fram með greiðslukorti. Upphæð láns þarf að vera yfir 30.000 kr. til að hægt sé að stofna lán.
MerchantName	N	0	100	O	Senda þarf inn notandanafn söluaðila ef um kortalán er að ræða. Sjá nánar í kafla 4.1.3.
IsInterestFree	N	1	1	O	0 eða 1. Segir til um hvort að kortalán sé vaxtalaust. Ef gildið er óútfyllt eða tómt er lán samkvæmt samningi fyrirtækis við Valitor.
CreateVirtualCardOnly	N	1	1	O	0 eða 1. Segir til um hvort að greiðslusíðan sé eingöngu notuð til að stofna ný sýndarkort. ATH! Ef þessi færibreyta er sett sem 1 þá er eingöngu stofnað nýtt sýndarkort og engin greiðsla er framkvæmd.

4.1.1 - DigitalSignature

MD5/SHA256 hash til að auðkenna réttmæti upplýsinga sem sendar eru á Greiðslusíðuna en Greiðslusíðan reiknar út sama MD5/SHA256 og ber saman við það sem er sent inn.
Búinn er til langur strengur á ákveðinn hátt og svo er tekið MD5/SHA256 hash á strengnum.

Mikilvægt er að gögnin í strengnum komi í þessari röð:

VerificationCode (Öryggisnúmer) + 
AuthorizationOnly + 
Product_x_y + //eingöngu ef CreateVirtualCardOnly=0 eða er ekki sendur með*
MerchantID + 
ReferenceNumber + 
PaymentSuccessfulURL + 
PaymentSuccessfulServerSideURL + 
Currency +
IsInterestFree //eingöngu ef stofna á kortalán*

Þar sem Product_x_y eru allar vörurnar á eftirfarandi formi:

Product_1_Quantity + 
Product_1_Price + 
Product_1_Discount + 
Product_2_Quantity + 
Product_2_Price + 
Product_2_Discount + 
o.s.frv.

Til leiðbeiningar

Ef stofna á kortalán með IsCardLoan=1 og IsInterestFree færibreytan er send með og SHA256 er notað þá verður að bæta gildinu fyrir IsInterestFree aftast í DigitalSignature strenginn, þ.e. 1 eða 0. Annars er ekki þörf á því að bæta því við.
Ef CreateVirtualCardOnly færibreytan er notuð og er sett sem 1 þá skal sleppa Product_x_y úr útreikningi á DigitalSignature.

Vinsamlegast athugið

Mikilvægt er að velja SHA256 en ekki MD5 þegar skrifað er á móti greiðslusíðunni þar sem að á ákveðnum tímapunkti mun verða lokað fyrir notkun á MD5.

4.1.1.1 - Dæmi

Ef forsendur eru þessar:

VerificationCode: 2ef8ec654c 
(Upplýsingar um öryggisnúmer eru á Þjónustuvef undir Greiðslusíða -> Upplýsingar)

AuthorizationOnly: 0
Product_1_Quantity: 2
Product_1_Price: 1500
Product_1_Discount: 0
Product_2_Quantity: 1
Product_2_Price: 1000
Product_2_Discount: 0
MerchantID: 207 (MerchantID/VefverslunID is on Valitor's Service Web 
under Greiðslusíða -> Upplýsingar)
ReferenceNumber: 456
PaymentSuccessfulURL: http://www.minsida.is/takkfyrir
PaymentSuccessfulServerSideURL: http://www.minsida.is/sale.aspx?c=8282&ref=232
Currency: ISK

Verður strengurinn þessi:

2ef8ec654c0215000110000207456http://www.minsida.is/takkfyrirhttp://www.minsida.is/sale.aspx?c=8282&ref=232ISK

MD5 af þessum streng er A704F243D9373D6F757257544781FD76 og það er gildið fyrir DigitalSignature.

Eftirfarandi gildi eru öll rétt fyrir þennan streng og eru gildið fyrir DigitalSignature:

Hash	Rétt gildi
MD5	A704F243D9373D6F757257544781FD76
MD5 ASCII	85a55dc4948a4e0139c8951224df8d5f
SHA256	c5e360e87eb1a6b402718d82904bc2b08c51bc3be92867db5b5eacb3483fe58f
SHA256 ASCII	8573f2a43f4d5fed99aaee4c8d098f14903afaf709ea1e0e7840e5e56edd962a

Ef ekki tekst að búa til rafræna undirskrift er vert að athuga hvort viðkomandi kerfi sé ekki með rétt MD5/SHA256 fall.

Annað dæmi fyrir strenginn "abc":

Hash	Rétt gildi
ekkert	abc
MD5	CE1473CF80C6B3FDA8E3DFC006ADC315
MD5 ASCII	900150983cd24fb0d6963f7d28e17f72
SHA256	13e228567e8249fce53337f25d7970de3bd68ab2653424c7b8f9fd05e33caedf
SHA256 ASCII	ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

4.1.2 - PaymentSuccesfulURL og PaymentSuccesfulServerSideURL

Ef að færibreyturnar PaymentSuccessfulURL eða PaymentSuccessfulServerSideURL hafa einhver gildi þá eru eftirfarandi gildi hengd aftan á slóðirnar:

Field	Type	Len. min	Len. max	Usage	Description
CardType	AN	-	-	-	Kortategund Dæmi: VISA VISA Debit MasterCard MasterCard Debit American Express JCB Diners Discover
CardNumberMasked	S	-	-	-	Fyrir PaymentSuccesfulURL þá er þetta síðustu 4 stafir kortnúmers með * táknum fyrir framan. Fyrir PaymentSuccesfulServerSideURL er þetta fyrstu 6 og síðustu 4 stafir kortnúmers með * táknum á milli.
Date	S	-	-	-	Dagsetning sölu (á forminu dd.MM.yyyy).
AuthorizationNumber	AN	-	-	-	Heimildarnúmer.
TransactionNumber	N	-	-	-	Færslunúmer.
SaleID	S	-	-	-	GUID sem Greiðslusíðan býr til og er einkvæmt fyrir sölu.
ReferenceNumber	S	-	-	-	Tilvísunarnúmer söluaðila.
DigitalSignatureResponse	S	-	-	-	MD5/SHA256 hash sem er búið til með að taka MD5/SHA256 af strengnum VerificationCode + ReferenceNumber á sama hátt og gert er í kafla 4.1.1. Nauðsynlegt er að DigitalSignatureResponse sé reiknað út á þeirri síðu sem Greiðslusíðan kallar á og það gildi borið saman við gildið sem Greiðslusíðan sendir til að tryggja að ekki sé verið að búa til tengla og reyna að líkja eftir sölum án þess að greiðsla eigi sér stað.
ContractNumber	N	-	-	-	Samningsnúmer sem sala fór á.
ContractType	S	-	-	-	Tegund samnings sem sala fór á. ORUGGS fyrir venjulegan greiðslusíðusamning.
CardLoanNumber	S	-	-	-	Númer kortaláns
CardTypeCode	N	-	-	-	Þriggja stafa kóði fyrir tegund korts.
SSN	N	-	-	-	Ef að DisplayBuyerInfo er jafnt og 1 þá er kennitölu kaupanda skilað til baka (ef það svæði var fyllt út).
Name	S	-	-	-	Ef að DisplayBuyerInfo er jafnt og 1 þá er nafni kaupanda skilað til baka (ef það svæði var fyllt út).
Address	N	-	-	-	Ef að DisplayBuyerInfo er jafnt og 1 þá er heimilisfangi kaupanda skilað til baka (ef það svæði var fyllt út).
PostalCode	N	-	-	-	Ef að DisplayBuyerInfo er jafnt og 1 þá er póstnúmeri kaupanda skilað til baka (ef það svæði var fyllt út).
City	N	-	-	-	Ef að DisplayBuyerInfo er jafnt og 1 þá er stað kaupanda skilað til baka (ef það svæði var fyllt út).
Country	N	-	-	-	Ef að DisplayBuyerInfo er jafnt og 1 þá er landi kaupanda skilað til baka (ef það svæði var fyllt út).
Phone	N	-	-	-	Ef að DisplayBuyerInfo er jafnt og 1 þá er síma kaupanda skilað til baka (ef það svæði var fyllt út).
Email	N	-	-	-	Ef að DisplayBuyerInfo er jafnt og 1 þá er netfangi kaupanda skilað til baka (ef það svæði var fyllt út).
Comments	N	-	-	-	Ef að DisplayBuyerInfo er jafnt og 1 þá er athugasemdum kaupanda skilað til baka (ef það svæði var fyllt út).
VirtualCard	AN	-	-	-	Ef að CreateVirtualCardOnly er jafnt og 1 þá er sýndarkortinu skilað til baka.

4.1.3 - IsCardLoan og MerchantName

Ef að um kortalán er um að ræða þarf notandanafn söluaðila að fylgja með.

Svæðið má vera tómt ef svo er ekki.

4.1.4 - CreateVirtualCardOnly

Ef nota á greiðslusíðuna til að stofna sýndarkort með því að senda CreateVirtualCardOnly færibreytuna sem 1 þá er eftirfarandi færibreytum skilað til baka í PaymentSuccesfulURL og PaymentSuccesfulServerSideURL:

CardNumberMasked
ReferenceNumber
DigitalSignatureResponse
ContractNumber
VirtualCard