Skip to content

4 - API

Information regarding test URLs for Valitor's Web Payments Page and other test information can be found in Chapter 2.

When a buyer is sent to the Valitor Web Payments Page the following parameters must be sent with the request.

Both HTTP GET and HTTP POST can be used

4.1. Parameters

Field Type Len. min Len. max Usage Description
MerchantID N 1 9 M Unique merchant/online store identification issued by Valitor.
Language A 2 2 O Language
IS is default if parameter is not sent in.
Possible values:
  • IS = Icelandic
  • EN = English
  • DA = Danish
  • DE = German
Currency A 3 3 M E.g. ISK.
Must match the currency associated with the merchant's contract with Valitor.
AuthorizationOnly N 1 1 M Currently not in use
Must use value 0
ReferenceNumber S 0 100 O Unique reference number issued by merchant.
Product_X_Description S 1 500 M Text description of product.
X is replaced with a number from 1 to 500.
If HTTP GET is being used then it is best to HTML encode this string and URL encode it if HTTP POST is being used.
Note! If CreateVirtualCardOnly parameter is set as 1 then this parameter is not mandatory and should be omitted.
Product_X_Quantity N 1 5 M Quantity of product number X.
Replace X with a number from 1 to 500.
Note! If CreateVirtualCardOnly parameter is set as 1 then this parameter is not mandatory and should be omitted.
Product_X_Price D 1 12 M Price of one unit of product number X.
Use a comma as a decimal separator for currencies other than ISK.
Replace X with a number from 1 to 500.
Note! If CreateVirtualCardOnly parameter is set as 1 then this parameter is not mandatory and should be omitted.
Product_X_Discount D 1 12 M Amount of discount for each unit of product number X.
Use a comma as a decimal separator for currencies other than ISK.
Replace X with a number from 1 to 500.
Note! If CreateVirtualCardOnly parameter is set as 1 then this parameter is not mandatory and should be omitted.
PaymentSuccessfulURL S 0 500 O URL displayed on the receipt page that is a link the user can use to return to the merchant's website.
The URL may include querystring parameters.
The Web Payments Page adds its own parameters to this URL that contain information about the sale. If HTTP GET is being used then this should be html encoded. See section 4.2.1.2.
PaymentSuccessfulURLText S 0 500 O Text displayed by the link (PaymentSuccessfulURL), which is displayed on the receipt page.
PaymentSuccessfulAutomaticRedirect N 1 1 O 0 or 1.
Indicates whether or not to redirect the user automatically to PaymentSuccessfulURL if payment is successful.
Note! If this parameter is set to 1 then the merchant/online store must display its own receipt/confirmation for the sale.
PaymentSuccessfulServerSideURL S 0 500 O A URL that Valitor requests to inform the merchant that payment was successful.
The URL may include parameters.
This page must return a response (HTTP status 200) and be on port 80 (HTTP) or 443 (HTTPS).
The Web Payments Page adds its own parameters to this URL that contain information about the sale. If HTTP GET is being used then this should be html encoded. See section 4.2.1.2.
PaymentCancelledURL S 0 500 O URL which the user is sent to if payment is cancelled, i.e. the ”Cancel”/”Hætta við” button is clicked.
If HTTP GET is being used then this should be HTML encoded.
DigitalSignature S 0 500 M MD5/SHA256 hash which is used to ensure the validity of the information sent to the Web Payments Page. See section 4.2.1.1.
SessionExpiredTimeoutInSeconds N 0 9 O If this value is sent in then the user is redirected to SessionExpiredRedirectURL when the time has expired.
SessionExpiredRedirectURL S 0 500 O URL that user is sent to if session expires.
If HTTP GET is being used then this should be HTML encoded.
DisplayBuyerInfo N 1 1 O 0 or 1.
Indicates whether or not to display input fields for buyer's ssn, name, address, postal code, city, country, phone number, e-mail address and comments.
RequireSSN N 1 1 O 0 or 1.
Indicates whether or not input field for buyer's ssn should be a required field.
RequireName N 1 1 O 0 or 1.
Indicates whether or not input field for buyer's name should be a required field.
RequireAddress N 1 1 O 0 or 1.
Indicates whether or not input field for buyer's address should be a required field.
RequirePostalCode N 1 1 O 0 or 1.
Indicates whether or not input field for buyer's postal code should be a required field.
RequireCity N 1 1 O 0 or 1.
Indicates whether or not input field for buyer's city should be a required field.
RequireCountry N 1 1 O 0 or 1.
Indicates whether or not input field for buyer's country should be a required field.
RequirePhone N 1 1 O 0 or 1.
Indicates whether or not input field for buyer's phone number should be a required field.
RequireEmail N 1 1 O 0 or 1.
Indicates whether or not input field for buyer's e-mail address should be a required field.
RequireComments N 1 1 O 0 or 1.
Indicates whether or not input field for buyer's comments should be a required field.
HideSSN N 1 1 O 0 or 1.
Indicates whether or not input field for buyer's ssn should be hidden.
HideName N 1 1 O 0 or 1.
Indicates whether or not input field for buyer's name should be hidden.
HideAddress N 1 1 O 0 or 1.
Indicates whether or not input field for buyer's address should be hidden.
HidePostalCode N 1 1 O 0 or 1.
Indicates whether or not input field for buyer's postal code should be hidden.
HideCity N 1 1 O 0 or 1.
Indicates whether or not input field for buyer's city should be hidden.
HideCountry N 1 1 O 0 or 1.
Indicates whether or not input field for buyer's country should be hidden.
HidePhone N 1 1 O 0 or 1.
Indicates whether or not input field for buyer's phone number should be hidden.
HideEmail N 1 1 O 0 or 1.
Indicates whether or not input field for buyer's e-mail address should be hidden.
HideComments N 1 1 O 0 or 1.
Indicates whether or not input field for buyer's comments should be hidden.
IsCardLoan N 1 1 O 0 or 1.
Indicates whether or not card loan is to be used for the purchase.
If this field is empty the payment will be made with a credit card.
The amount of the loan needs to be higher than 30.000 kr. to be successfully created.
MerchantName N 0 100 O The merchant name is needed if card loan is to be used. See chapter 4.2.1.3.
IsInterestFree N 1 1 O 0 or 1.
Indicates whether or not the card loan is interest free. If this value is empty, the loan is created according to the merchants contract with Valitor.
CreateVirtualCardOnly N 1 1 O 0 or 1.
Indicates whether or not the payment page should only be used to create new virtual card.
Note! If this parameter is set to 1 then only new virtual card is created and no payment is made.

4.1.1 - DigitalSignature

MD5/SHA256 hash to ensure the validity of the information sent to the Web Payments Page.
The Web Payments Page calculates the MD5/SHA256 for the same sale and compares it to the submitted hash.

The components of the string used to seed the MD5/SHA256 hash must be ordered in the following way:

VerificationCode (Öryggisnúmer) + 
AuthorizationOnly + 
Product_x_y + //only when CreateVirtualCardOnly=0 or is omitted*
MerchantID + 
ReferenceNumber + 
PaymentSuccessfulURL + 
PaymentSuccessfulServerSideURL + 
Currency +
IsInterestFree //only when creating card loan*

Where Product_x_y is a list of all the products in the following format:

Product_1_Quantity + 
Product_1_Price + 
Product_1_Discount + 
Product_2_Quantity + 
Product_2_Price + 
Product_2_Discount + 
etc.

Info

If card loan is to be created with IsCardLoan=1 and IsInterestFree parameter is used and SHA256, then the value for IsInterestFree needs to be appended to the DigitalSignature string, i.e. 1 or 0. Otherwise it should not be added to the string.
If CreateVirtualCardOnly parameter is used and is set as 1 then the Product_x_y should be omitted from the calculation of DigitalSignature.

Attention

It is important to use SHA256, but not MD5 when connecting to the payment page because at some point in the near future the support for MD5 will be removed from the payment page.

4.1.1.1 - Example

Using the following values:

VerificationCode: 2ef8ec654c 
(Information about the verification code can be found on Valitor's Service Web under 
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

The string will be:

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

The MD5 hash for this string is A704F243D9373D6F757257544781FD76 and that is the value for DigitalSignature.

The following values are also valid for each corresponding hash type:

Hash Value
MD5 A704F243D9373D6F757257544781FD76
MD5 ASCII 85a55dc4948a4e0139c8951224df8d5f
SHA256 c5e360e87eb1a6b402718d82904bc2b08c51bc3be92867db5b5eacb3483fe58f
SHA256 ASCII 8573f2a43f4d5fed99aaee4c8d098f14903afaf709ea1e0e7840e5e56edd962a

If the creation of a digital signature fails, check that the correct MD5/SHA256 function is being used.

Another example for the string "abc":

Hash Value
Nothing abc
MD5 CE1473CF80C6B3FDA8E3DFC006ADC315
MD5 ASCII 900150983cd24fb0d6963f7d28e17f72
SHA256 13e228567e8249fce53337f25d7970de3bd68ab2653424c7b8f9fd05e33caedf
SHA256 ASCII ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

4.1.2 - PaymentSuccesfulURL and PaymentSuccesfulServerSideURL

If the parameters PaymentSuccessfulURL or PaymentSuccessfulServerSideURL were sent in then the following querystring parameters are added to the URLs:

Field Type Len. min Len. max Usage Description
CardType AN - - - Card type.
Examples:
  • VISA
  • VISA Debit
  • MasterCard
  • MasterCard Debit
  • American Express
  • JCB
  • Diners
  • Discover
CardNumberMasked S - - - For PaymentSuccessfulURL then this is the last 4 numbers in the card number with * symbols in front.
For PaymentSuccessfulServerSideURL then this is the first 6 and last 4 numbers in the card number with * symbols in between.
Date S - - - Date of sale
Format: dd.MM.yyyy
AuthorizationNumber AN - - - Authorization number
TransactionNumber N - - - Transaction number.
SaleID S - - - GUID created by the Web Payments Page.
ReferenceNumber S - - - Merchant's reference number.
DigitalSignatureResponse S - - - MD5/SHA256 hash of the string created by concatenating VerificationCode+ReferenceNumber.
It is important that the value of DigitalSignatureResponse is calculated on the page that Valitor requests and that the value is compared with the value sent by Valitor to ensure that this is not a case of theft, i.e. an attempt to create a fraudulent sales link.
ContractNumber N - - - Contract number for sale.
ContractType S - - - Type of contract for sale.
ORUGGS for regular Web Payment Page contract
CardLoanNumber S - - - Card loan number for sale.
CardTypeCode N - - - Three digit code for the type of card.
SSN N - - - If DisplayBuyerInfo is 1 then the buyer's SSN is returned (if that field was filled out).
Name S - - - If DisplayBuyerInfo is 1 then the buyer's name is returned (if that field was filled out).
Address N - - - If DisplayBuyerInfo is 1 then the buyer's address is returned (if that field was filled out).
PostalCode N - - - If DisplayBuyerInfo is 1 then the buyer's postal code is returned (if that field was filled out).
City N - - - If DisplayBuyerInfo is 1 then the buyer's city is returned (if that field was filled out).
Country N - - - If DisplayBuyerInfo is 1 then the buyer's country is returned (if that field was filled out).
Phone N - - - If DisplayBuyerInfo is 1 then the buyer's phone number is returned (if that field was filled out).
Email N - - - If DisplayBuyerInfo is 1 then the buyer's e-mail address is returned (if that field was filled out).
Comments N - - - If DisplayBuyerInfo is 1 then the buyer's comments are returned (if that field was filled out).
VirtualCard AN - - - If CreateVirtualCardOnly is 1 then the virtual card is returned.

4.1.3 - IsCardLoan and MerchantName

If card loan is to be used, the merchant name is needed.

If not, the parameter can be empty.

4.1.4 - CreateVirtualCardOnly

If the payment page is to be used to create virtual card by sending CreateVirtualCardOnly parameter as 1 then the following parameters are returned in PaymentSuccesfulURL og PaymentSuccesfulServerSideURL:

CardNumberMasked
ReferenceNumber
DigitalSignatureResponse
ContractNumber
VirtualCard