6 - 3DSecure Web Services
6.1 - FaAudkenningu
Returns an authentication HTML with Javascript that the merchant must execute in the cardholder browser.
This operation can be used for both virtual and actual card numbers. The merchant must identify whether he plans to use card number or virtual number in the field NotaKortnumer.
Attention
Please note that though the usage of cvv is not directly required in this web service, the merchant is required to request the cardholder's cvv data in a web form that implements the call to this web service.
To prevent storing card data on the merchant web server it is recommended that the merchant makes sure that card data (card number/virtual number, expiration date and cvv) is fully encrypted with a secure key and the encrypted data is used in the field Dulkodun (see below).
6.1.1 - Definitions
6.1.1.1 - Request
| Field | Type | Len. min | Len. max | Usage | Description |
|---|---|---|---|---|---|
| Notandanafn | AN | 1 | 50 | M | Merchant's Web Service user name. |
| Lykilord | AN | 1 | 50 | M | Merchant's Web Service password. |
| Samningsnumer | N | 6 | 6 | M | Merchant's contract no. |
| SamningsKennitala | N | 10 | 10 | M | Contract's Icelandic SS no. |
| PosiID | N | 1 | - | M | POS terminal ID received from Valitor. |
| NotaKortnumer | N | 1 | 1 | M | Identify whether card number (1) or virtual number (0) is being used. |
| KortnumerEdaSyndarkortanumer | N | 16 | 16 | M | Card number or virtual number to get authentication for. If virtual number then Valitor will fetch the card number behind the virtual number behind the scenes and forward to the authentication |
| Gildistimi | N | 4 | 4 | M | Card expiration date written in format MMYY. |
| Gjaldmidill | AN | 3 | 3 | M | Currency, e.g. ISK, USD, EUR, DKK. |
| Upphaed | N | 1 | - | O | Amount of the transaction. Optional when doing authentication for FaSyndarkortanumer.
If this is an authenticatino request for FaHeimild request, for Cardholder initiated virtual card, then this amount must be the same as the amount planned for the FaHeimild authorization. For ISK this needs to without minor units. For example 100kr must be sent in as 100. For other currencies this needs to be sent with minor units. For example 65,43$ needs to be sent in as 64,45 (with comma) If amount is 0 then no authorization request is performed, the service will just return an empty response with 0 error code. |
| GerdTaekis | N | 1 | 1 | M | Identify the cardholder device type. The following data is valid for this field. 0 : Web browser 1 : Phone app 4 : Digital tv software |
| AudkenningTokstUrl | AN | 1 | 2048 | M | Web path. When authentication is successfully completed, the cardholder will be redirected to this web path. In this path there must be a operation to capture the post back parameter that will identify the authentication results There is a number of parameters returned but only those listed here will be required to perform a call to FaSyndarkortnumer or UppfaeraGildistima. cavv : encrypted string for the authentication itself. Only cavv for a fully authenticated card can be used to create virtual card, see MdStatus below. xid : Valitor reference number to the authentication. MD : Possible values 0 = Not Authenticated, do not continue transaction 1 = Fully Authenticated, continue transaction 2,3,4 = authentication attempt, not possible to continue. 5 = Gray area, not possible to continue 6,7,8 = authentication failed, not possible to continue. It is only possible to call FaSyndarkortnumer to get virtual card when MdStatus is 1. dsTransId : A globally unique identifier (GUID) that represents the directory server transaction id, required when merchant is enrolled in 3DS2.x |
| AudkenningMistokstUrl | AN | 1 | 2048 | M | Web path. Upon failed authentication, the cardholder will be redirected to this web path. |
| Dulkodun | AN | 1 | 250 | M | Merchant data. This data is returned back in a post to the AudkenningTokstUrl. It's highly recommended that the merchant encrypts the card number/virtual number, expiration date and cvv using a secure key and sends it in this field. If the merchant chooses to do this then the merchant must ask the cardholder to enter the cvv along with cardnumber/virtual number and expiration date, even though it is not a specific field in this web service. |
| Stillingar | AN | 1 | 250 | O | Additional parameters. Not currently in use. |
6.1.1.2 - Response
| Field | Type | Len. min | Len. max | Usage | Description |
|---|---|---|---|---|---|
| Villuskilabod | AN | 1 | 16 | M | Error description. Is empty if there is no error. |
| Villunumer | N | 1 | 3 | M | Error no. Is 0 if no error. See table in 4.1.3. |
| VilluLogID | N | 1 | - | M | Error ID in Valitor logs. |
| AudkenningarHtml | N | - | - | M | HTML form with Javascript. The merchant must execute this form in the cardholder web browser. The cardholder in redirected to a 3DSecure web site hosted by Valitor and concurrently the cardholder will receive a SMS with a verification code. This verification code the cardholder must enter on the web site. If that is succesful then the cardholder is redirected back to the merchant website (AudkenningTokstUrl). See AudkenningTokstUrl above for more information on successful authentication. |
6.1.2 - Examples
6.1.2.1 - Request
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <FaSyndarkortnumer xmlns="http://api.valitor.is/Fyrirtaekjagreidslur/"> <Notandanafn>AbC123</Notandanafn> <Lykilord>84jkf</Lykilord> <Samningsnumer>60000</Samningsnumer> <SamningsKennitala>2112683579</SamningsKennitala> <PosiID>1</PosiID> <NotaKortnumer>1</NotaKortnumer> <KortnumerEdaSyndarkortanumer>4166453986006987</KortnumerEdaSyndarkortanumer> <Gildistimi>0315</Gildistimi> <Gjaldmidill>ISK</Gjaldmidill> <GerdTaekis>0</GerdTaekis> <AudkenningTokstUrl>https://www.webshop.is/success</AudkenningTokstUrl> <AudkenningMistokstUrl>https://www.webshop.is/failed</AudkenningMistokstUrl> <Dulkodun>https://www.webshop.is/failed</AudkenningMistokstUrl> <Stillingar></Stillingar> </FaSyndarkortnumer> </soap:Body> </soap:Envelope>
6.1.2.2 - Response
<?xml version="1.0" encoding="utf-8"?> <SyndarkortnumerSkilabod xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns=" http://api.valitor.is/Fyrirtaekjagreidslur/"> <Villunumer>0</Villunumer> <Villuskilabod /> <VilluLogID>0</VilluLogID> <AudkenningarHtml>Html form</AudkenningarHtml> </SyndarkortnumerSkilabod>
6.1.2.3 - Error response - Card is expired
<?xml version="1.0" encoding="utf-8"?> <SyndarkortnumerSkilabod xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns=" http://api.valitor.is/Fyrirtaekjagreidslur/"> <Villunumer>232</Villunumer> <Villuskilabod>Gildistími korts er útrunninn.</Villuskilabod> <VilluLogID>0</VilluLogID> <Syndarkortnumer /> </SyndarkortnumerSkilabod>
6.1.3 - Errors
| Error code | Description |
|---|---|
| 1 | The web service id does not exist. |
| 2 | Wrong username or password. |
| 3 | The username (xxx) does not have access to the web service id (VefthjonustaID=yyy). |
| 4 | The username (xxx) does not have access to the web service (VefthjonustaID yyy) from the ip address zzz. |
| 200 | Missing agreement number. |
| 201 | The agreement number must be 6 digits. it is possible to fill out with 0 in front. |
| 202 | Contract number x does not exist. |
| 204 | Contract number x is not associated with Icelandic SS number y. |
| 205 | The contract owner's Icelandic SS no. is missing. |
| 206 | The contract owner's Icelandic SS no. Must be 10 digits. |
| 207 | The SS no. does not exist. |
| 208 | User name x does not have access to the contract associated with Icelandic SS no. y. |
| 209 | POS terminal ID is missing. |
| 210 | POS terminal ID must be in digits only. |
| 306 | The posiId is not registered in the new Valitor authorization system (VAS). Please contact support to get the posiId moved over. |
| 309 | NotaKortnumer is required and needs to be either 0 (You want to send in virtual number) or 1 (You wan to send in card number). |
| 211 | Card no. is missing. This error is only possible when NotaKortnumer is 1. |
| 212 | Card no. must be 11 to 19 digits. This error is only possible when NotaKortnumer is 1. |
| 213 | Card no. is void. This error is only possible when NotaKortnumer is 1. |
| 235 | Received card numbers are virtual card numbers. Card numbers transmitted must be regular card numbers. This error is only possible when NotaKortnumer is 1. |
| 219 | Virtual card number is missing. This error is only possible when NotaKortnumer is 0. |
| 220 | Virtual card number is void. Virtual card number is 16 digits where digits 2 through 9 are 99999. This error is only possible when NotaKortnumer is 0. |
| 214 | Expiration date is missing. |
| 215 | Expiration date must be 4 digits. |
| 232 | Card expiration date is past. |
| 233 | POS terminal ID x is not associated with contract number y. |
| 300 | GerdTaekis must be 0 (Web browser), 1 (Phone app) or 4 (Digital tv software). |
| 301 | Invalid url. |
| 301 | Invalid url. |
| 308 | Dulkodun is missing. We recommend that an encrypted string containing card number/virtual number, expiration date and secure merchant key is sent into this field. |
| 500 | System error. (Explanation text may vary.) |
| 999 | Unknown error. (Explanation text may vary.) |
Tip
We suggest that integration on merchant's end allows for the possibility that Web Services may return other error numbers than those listed in this document.
6.2 - FaSyndarkortnumer
Before this function can be called, the cardholder must have gone through 3DSecure authentication made with FaAudkenningu web service. When authentication is complete, the cardholder should be redirected to a merchant web site (AudkenningTokstUrl in FaAudkenningu web service) that processes the authentication results and calls FaSyndarkortnumer. "FaSyndarkortnumer" is Icelandic for "get a virtual card number". An attempt is made to receive authorization for 0 ISK to verify the information received and that the card is authentic, if successful then the function returns a virtual card number. It is only possible to use virtual card numbers with the contract number it was created with.
6.2.1 - Definitions
6.2.1.1 - Request
| Field | Type | Len. min | Len. max | Usage | Description |
|---|---|---|---|---|---|
| Notandanafn | AN | 1 | 50 | M | Merchant's Web Service user name. |
| Lykilord | AN | 1 | 50 | M | Merchant's Web Service password. |
| Samningsnumer | N | 6 | 6 | M | Merchant's contract no. |
| SamningsKennitala | N | 10 | 10 | M | Contract's Icelandic SS no. |
| PosiID | N | 1 | - | M | POS terminal ID received from Valitor. |
| Kortnumer | N | 16 | 16 | M | Card no. used to create a virtual card no. for. We suggest that the card number is fetched from the MD field that is posted bach to AudkenningTokstUrl. See FaAudkenningu. |
| Gildistimi | N | 4 | 4 | M | Card expiration date written MMYY. e suggest that the expiration date is fetched from the MD field that is posted bach to AudkenningTokstUrl. See FaAudkenningu. |
| Oryggisnumer | N | 3 | 4 | M | Security number (cvv) on card back side. To get the cardholder to enter the cvv, the merchant must ask for it on the same website that is asking for card number and expiration date for the FaAudkenningu web service. Valitor suggests that the cvv is then encrypted, along with the card number, expiration date and a secure key, and sent through the Dulkodun field in FaAudkenningu. The cvv can then be fetched from the MD field returned from authentication response results. See FaAudkenningu. |
| HverNotarKortid | N | 1 | 1 | M | Single character 'C' or 'M' possible. Identify the initiator for future transactions made with this virtual card in FaHeimild. If the cardholder is initiating the transactions then put 'C' here. If the Merchant is initiating the transactions then put 'M' here. If you need to be able to perform both Merchant and Cardholder initiated transactions, then you need to create two virtual cards for each purpose. It is important that the virtual card is being used by the correct initiator in subsequent transactions in FaHeimild, in the case that any disputes arise. Please note that virtual cards created with 'C' in this field will need to go throgh the 3dSecure process in FaAudkenningu, before authorization is attempted with FaHeimild. |
| AudkenningNidurstada_TXID | N | 1 | - | M | Valitor ID for the card authentication. This needs to be captured from a post parameter called 'xid' on the AudkenningTokstUrl. See FaAudkenningu. |
| AudkenningNidurstada_CAVD | N | 1 | - | M | Encrypted string containing the authentication itself. This needs to be captured from a post paramerer called 'cavv' on the AudkenningTokstUrl. Only cavv for a fully authenticated card (mdStatus 1) can be submitted here. See FaAudkenningu |
| Stillingar | AN | 1 | 250 | O |
Additional parameters. dsTransId : This field is required when the merchant is enrolled in 3DS2.x and if a virtual card was created with the user defined as Cardholder (HverNotarKortid = C). This field is captured from a post parameter called 'TDS2.dsTransId' on the AudkenningTokstUrl. See FaAudkenningu. |
6.2.2 - Examples
6.2.2.1 - Request
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <FaSyndarkortnumer xmlns="http://api.valitor.is/Fyrirtaekjagreidslur/"> <Notandanafn>AbC123</Notandanafn> <Lykilord>84jkf</Lykilord> <Samningsnumer>60000</Samningsnumer> <SamningsKennitala>2112683579</SamningsKennitala> <PosiID>1</PosiID> <Kortnumer>4166453986006987</Kortnumer> <Gildistimi>0315</Gildistimi> <Oryggisnumer>123</Oryggisnumer> <Stillingar></Stillingar> </FaSyndarkortnumer> </soap:Body> </soap:Envelope>
6.2.2.2 - Response
<?xml version="1.0" encoding="utf-8"?> <SyndarkortnumerSkilabod xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns=" http://api.valitor.is/Fyrirtaekjagreidslur/"> <Villunumer>0</Villunumer> <Villuskilabod /> <VilluLogID>0</VilluLogID> <Syndarkortnumer>6244d066-6e5f-4aad-b027-af64acdac38e</Syndarkortnumer> </SyndarkortnumerSkilabod>
6.2.2.3 - Error response - Card is expired
<?xml version="1.0" encoding="utf-8"?> <SyndarkortnumerSkilabod xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns=" http://api.valitor.is/Fyrirtaekjagreidslur/"> <Villunumer>232</Villunumer> <Villuskilabod>Gildistími korts er útrunninn.</Villuskilabod> <VilluLogID>0</VilluLogID> <Syndarkortnumer /> </SyndarkortnumerSkilabod>
6.2.3 - Error Codes
| Error code | Description |
|---|---|
| 1 | Web Service ID does not exist. |
| 2 | Wrong user name or password. |
| 3 | User name (xxx) does not have access to the Web Service (VefthjonustaID=yyy). |
| 4 | User name (xxx) does not have access to the Web Service from IP no. zzz. |
| 200 | Contract number is missing. |
| 201 | The contract number must be 6 digits. A 0 may be used as the first digit. |
| 202 | Contract number x does not exist. |
| 204 | Contract number x is not associated with Icelandic SS number y. |
| 205 | The contract owner's Icelandic SS no. is missing. |
| 206 | The contract owner's Icelandic SS no. must be 10 digits. |
| 207 | The SS no. does not exist. |
| 208 | User name x does not have access to the contract associated with Icelandic SS no. y. |
| 209 | POS terminal ID is missing. |
| 210 | POS terminal ID must be in digits only. |
| 211 | Card no. is missing. |
| 212 | Card no. must be 11 to 19 digits. |
| 213 | Card no. is void. |
| 214 | Expiration date is missing. |
| 215 | Expiration date must be 4 digits. |
| 216 | Verification code is missing. |
| 217 | Verification code is too long. |
| 218 | Authorization not received for card no. – not possible to create a virtual card no.. Different messages may appear. |
| 232 | Card expiration date is past. |
| 233 | POS termainal ID x is not associated with contract number y. |
| 235 | Received card numbers are virtual card numbers. Card numbers transmitted must be regular card numbers. |
| 304 | audkenningNidurstadaCavd, other name CAVD or CAVV (Cardholder Authentication Verification Data/Value), can not be empty. This field is returned back to the AudkenningTokstUrl (See FaAudkenningu web service) when the cardholder has completed his authentication. This is an encrypted string containing the authentication itself. |
| 305 | Invalid value for HverNotarKortid. Accepted values are 'M' (Merchant) or 'C' (Cardholder). |
| 306 | The posiId is not registered in the new Valitor authorization sysmte (VAS). Please contact support to get the posiId moved over. |
| 307 | AudkenningNidurstadaTxid, other name txid or xid can not be empty. This field is returned back to the AudkenningTokstUrl (See FaAudkenningu web service) when the cardholder has completed his authentication. This is an encrypted string containing the authentication itself. |
| 500 | System error. (Explanation text may vary.) |
| 999 | Unknown error. (Explanation text may vary.) |
Tip
It is suggested that integration on merchant's side allows for the possibility that Web Services may return other error numbers than those listed in this document.
6.3 - FaHeimild
This function is used to seek authorization, for when the card is to be charged that is behind the virtual card number.
6.3.1 - Definitions
6.3.1.1 - Request
| Field | Type | Len. min | Len. max | Usage | Description |
|---|---|---|---|---|---|
| Notandanafn | AN | 1 | 50 | M | Merchant's Web Service user name. |
| Lykilord | AN | 1 | 50 | M | Merchant's Web Service password. |
| Samningsnumer | N | 6 | 6 | M | Merchant's contract no. |
| SamningsKennitala | N | 10 | 10 | M | Contract's Icelandic SS no. |
| PosiID | B | 1 | - | M | POS terminal ID received from Valitor. |
| Syndarkortnumer | N | 16 | 16 | M | Virtual card no. received from the function FaSyndarkortnumer. |
| Upphaed | N | 1 | - | M | Amount to be charged. For ISK this needs to without minor units. For example 100kr must be sent in as 100. For other currencies this needs to be sent with minor units. For example 65,43$ needs to be sent in as 64,45 (with comma) If amount is 0 then no authorization request is performed, the service will just return an empty response with 0 error code. |
| Gjaldmidill | AN | 3 | 3 | M | Currency, e.g. ISK, USD, EUR, DKK. |
| Stillingar | AN | 1 | 250 | O |
Additional parameters. dsTransId : This field is required when the merchant is enrolled in 3DS2.x and if a virtual card was created with the user defined as Cardholder (HverNotarKortid = C). This field is captured from a post parameter called ‘dsTransId’ on the AudkenningTokstUrl. See FaAudkenningu. |
| AudkenningNidurstada_TXID | N | 1 | - | O | This field is required if a virtual card was created with the user defined as Cardholder (HverNotarKortid = C). This field needs to be captured from a post parameter called 'xid' on the AudkenningTokstUrl. See FaAudkenningu. |
| AudkenningNidurstada_CAVD | N | 1 | - | O | This field is required if a virtual card was created with the user defined as Cardholder (HverNotarKortid = C) This field needs to be captured from a post paramerer called 'cavv' on the AudkenningTokstUrl. See FaAudkenningu |
6.3.1.2 - Response
| Field | Type | Len. min | Len. max | Usage | Description |
|---|---|---|---|---|---|
| Villuskilabod | AN | 1 | 16 | M | Error description. Is empty if there is no error |
| Villunumer | N | 1 | 3 | M | Error number. Is 0 if there is no error. See table 4.2.3 |
| VilluLogID | N | 1 | - | M | Error ID in Valitor logs |
| Kvittun/Receipts | OB | - | - | - | Kvittun/Receipts object |
6.3.1.2.1 - Receipts Response Object
| Field | Type | Len. min | Len. max | Usage | Description |
|---|---|---|---|---|---|
| VerslunNafn | AN | 1 | - | M | Name of store. |
| VerslunHeimilisfang | AN | 1 | - | M | Store address. |
| VerslunStadur | AN | 1 | - | M | Place of store. |
| TegundKorts | AN | 1 | - | M | Card type, e.g. VISA. |
| TegundKortsKodi | N | 3 | 3 | M | No longer used. |
| Dagsetning | AN | 10 | 10 | M | Authorization date. |
| Timi | AN | 1 | - | M | Authorization time. |
| Kortnumer | AN | 19 | 19 | M | Starred card no. where last 4 digits appear. |
| Upphaed | AN | 19 | 19 | M | Amount. |
| Faerslunummer | N | 5 | 5 | M | Transaction no. |
| Faersluhirdir | AN | 19 | 19 | M | Acquirer name and phone no. |
| Heimildarnumer | AN | 6 | 6 | M | Authorization no. |
| StadsetningNumer | N | 4 | 4 | M | Location no., default 0001. |
| UtstodNumer | N | 4 | 4 | M | Terminal no., default 0001. |
| BuidAdOgilda | B | - | - | M | True if transaction is already cancelled. |
| Bunkanumer | AN | 8 | 8 | M | Batch numbers with prefix B. |
| Soluadilinumer | AN | 8 | 8 | M | Merchant contract no. with prefix S. |
| Hugbunadarnumer | N | 11 | 11 | M | Permanent no.: 11101020000. |
| PosiID | N | 1 | - | M | POS terminal ID allocated by Valitor. |
| PinSkilabod | - | - | - | - | Not used. |
| Vidskiptaskilabod | AN | 1 | - | M | Text, currency and amount. |
| F22_1til4 | N | 4 | 4 | M | Not in use. |
| LinaC1 | N | 3 | 3 | M | Not in use. |
| LinaC2 | N | 4 | 4 | M | Not in use. |
| LinaC3 | AN | 1 | - | M | Text and transaction no. |
| LinaC4 | AN | 1 | - | M | Text and authorization no. |
| LinaD1 | - | - | - | - | Not used. |
| LinaD2 | - | - | - | - | Not used. |
| TegundAdgerd | AN | 11 | 11 | M | Permanent text: SALA. |
| FaerslunumerUpphafleguFaerslu | AN | 1 | - | M | Text and transaction no. |
| TerminalID | N | 8 | 8 | M | Terminal ID. |
6.3.2 - Examples
6.3.2.1 - Request example
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <FaHeimild xmlns="http://api.valitor.is/Fyrirtaekjagreidslur/"> <Notandanafn>AbC123</Notandanafn> <Lykilord>84jkf</Lykilord> <Samningsnumer>60000</Samningsnumer> <SamningsKennitala>2112683579</SamningsKennitala> <PosiID>1</PosiID> <Syndarkortnumer>4999993986001010</Syndarkortnumer> <Upphaed>100</Upphaed> <Gjaldmidill>ISK</Gjaldmidill> <Stillingar></Stillingar> </FaHeimild> </soap:Body> </soap:Envelope>
6.3.2.2 - Response example
<?xml version="1.0" encoding="utf-8"?> <HeimildSkilabod xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns=" http://api.valitor.is/Fyrirtaekjagreidslur/"> <Villunumer>0</Villunumer> <Villuskilabod /> <VilluLogID>0</VilluLogID> <Kvittun> <VerslunNafn>123.is ehf</VerslunNafn> <VerslunHeimilisfang>Pósthólf 12063</VerslunHeimilisfang> <VerslunStadur>Reykjavik</VerslunStadur> <TegundKorts>VISA</TegundKorts> <TegundKortsKodi/> <Dagsetning>14.05.2009</Dagsetning> <Timi>09:38</Timi> <Kortnumer>****-****-****-6987</Kortnumer> <Upphaed>100</Upphaed> <Faerslunumer>26711</Faerslunumer> <Faersluhirdir>Valitor, sími: 525 2000</Faersluhirdir> <Heimildarnumer>114355</Heimildarnumer> <StadsetningNumer>0001</StadsetningNumer> <UtstodNumer>0001</UtstodNumer> <BuidAdOgilda>false</BuidAdOgilda> <Bunkanumer>B0000469</Bunkanumer> <Soluadilinumer>S0039189</Soluadilinumer> <Hugbunadarnumer>11101020000</Hugbunadarnumer> <PosiID>1</PosiID> <PinSkilabod /> <Vidskiptaskilabod>VIÐSKIPTI ISK: 100</Vidskiptaskilabod> <F22_1til4/>5101</F22_1til4> <LinaC1>060</LinaC1> <LinaC2>1509</LinaC2> <LinaC3>FÆRSLUNR: 0000001</LinaC3> <LinaC4>HEIMILD:114355</LinaC4> <LinaD1 /> <LinaD2 /> <TegundAdgerd>SALA</TegundAdgerd> <FaerslunumerUpphafleguFaerslu/> <TerminalID>11100004</TerminalID> </Kvittun> </HeimildSkilabod>
6.3.2.3 - Error response - POS terminal ID does not belong to the agreement number
<?xml version="1.0" encoding="utf-8"?> <HeimildSkilabod xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns=" http://api.valitor.is/Fyrirtaekjagreidslur/"> <Villunumer>233</Villunumer> <Villuskilabod>PosiID 89 tilheyrir ekki samningsnúmerinu 000122.</Villuskilabod> <VilluLogID>0</VilluLogID> <Kvittun> <VerslunNafn/> <VerslunHeimilisfang/> <VerslunStadur/> <TegundKorts/> <Dagsetning/> <Timi/> <Kortnumer/> <Upphaed/> <Faerslunumer/> <Faersluhirdir/> <Heimildarnumer/> <StadsetningNumer/> <UtstodNumer/> <BuidAdOgilda>false</BuidAdOgilda> <Bunkanumer/> <Soluadilinumer/> <Hugbunadarnumer/> <PosiID/> <PinSkilabod/> <Vidskiptaskilabod/> <F22_1til4/> <LinaC1/> <LinaC2/> <LinaC3/> <LinaC4/> <LinaD1/> <LinaD2/> <TegundAdgerd/> <FaerslunumerUpphafleguFaerslu/> <TerminalID/> </Kvittun> </HeimildSkilabod>
6.3.3 - Error Codes
| Error code | Description |
|---|---|
| 1 | Web Service ID does not exist. |
| 2 | Wrong user name or password. |
| 3 | User (xxx) does not have access to Web Service (yyy). |
| 4 | User (xxx) does not have access to Web Service (yyy) from IP (zzz). |
| 200 | Contract number is missing. |
| 201 | The contract number must be 6 digits. A 0 may be used as the first digit. |
| 202 | Contract number x does not exist. |
| 204 | Contract number x is not associated with Icelandic SS number y. |
| 205 | The contract owner's Icelandic SS no. is missing. |
| 206 | The contract owner's Icelandic SS no. must be 10 digits. |
| 207 | The SS no. does not exist. |
| 208 | User name x does not have access to the contract associated with Icelandic SS no. y. |
| 209 | POS terminal ID is missing. |
| 210 | POS terminal ID must be in digits only. |
| 306 | The posiId is not registered in the new Valitor authorization system (VAS). Please contact support to get the posiId moved over. |
| 219 | Virtual card number is missing. |
| 220 | Virtual card number is void. Virtual card number is 16 digits where digits 2 through 9 are 99999. |
| 221 | Virtual card number does not exist. |
| 222 | The amount is missing. |
| 224 | The currency is missing. |
| 225 | The currency must be three letters. |
| 226 | Contract number x is not listed for currency y. |
| 227 | Virtual number does not exist or merchant does not have access to virtual number. |
| 228 | Authorization not received, reason: xxxxxxxxxx. |
| 229 | Failed to reimburse. Different messages can appear. |
| 230 | POS terminal ID x is not associated with SS no. y. |
| 231 | The card associated with virtual card number x has expired. The card ends in y. |
| 235 | Error: location of card holder is too short. |
| 500 | System error. (Different messages may appear) |
| 999 | Unknow error. (Different messages may appear) |
Tip
It's highly recommended that integration on merchant's side allows for the possibility that Web Services may return other error numbers than those listed in this document.
6.4 - UppfaeraGildistima
"UppfaeraGildistima" is Icelandic for "update expiration date". The expiration date for the given virtual card is updated if valid.
6.4.1. Definitions
6.4.1.1 - Request
| Field | Type | Len. min | Len. max | Usage | Description |
|---|---|---|---|---|---|
| Notandanafn | AN | 1 | 50 | M | Merchant's Web Service user name. |
| Lykilord | AN | 1 | 50 | M | Merchant's Web Service password. |
| SamningsKennitala | N | 10 | 10 | M | Contract's Icelandic SS no. |
| Syndarkortnumer | N | 16 | 16 | M | Virtual card number received from the function FaSyndarkortnumer. |
| NyrGildistimi | N | 4 | 4 | M | Card expiration date written MMYY. |
| Stillingar | AN | 1 | 250 | O | Additional paramters. Not currently in use. |
6.4.1.2 - Response
| Field | Type | Len. min | Len. max | Usage | Description |
|---|---|---|---|---|---|
| Villuskilabod | AN | 1 | 16 | M | Error description. Is empty if there is no error. |
| Villunumer | N | 1 | 3 | M | Error number. Is 0 if no error. See table 4.4.3. |
| VilluLogID | N | 1 | - | M | Error ID in Valitor logs. |
6.4.2 - Examples
6.4.2.1 - Request example
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <UppfaeraGildistima xmlns="http://api.valitor.is/Fyrirtaekjagreidslur/"> <Notandanafn>AbC123</Notandanafn> <Lykilord>84jkf</Lykilord> <Samningsnumer>60000</Samningsnumer> <SamningsKennitala>2112683579</SamningsKennitala> <Syndarkortnumer>4999993986001010</Syndarkortnumer> <NyrGildistimi>0515</NyrGildistimi> <Stillingar></Stillingar> </UppfaeraGildistima> </soap:Body> </soap:Envelope>
6.4.2.2 - Response example
<?xml version="1.0" encoding="utf-8"?> <Skilabod xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns=" http://api.valitor.is/Fyrirtaekjagreidslur/"> <Villunumer>0</Villunumer> <Villuskilabod /> <VilluLogID>0</VilluLogID>
6.4.2.3 - Error response - Wrong user name or password
<?xml version="1.0" encoding="utf-8"?> <Skilabod xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns=" http://api.valitor.is/Fyrirtaekjagreidslur/"> <Villunumer>2</Villunumer> <Villuskilabod>Rangt notandanafn eða lykilorð.</Villuskilabod> <VilluLogID>0</VilluLogID> </Skilabod>
6.4.3 - Error Codes
| Error code | Description |
|---|---|
| 1 | Web Service ID no. does not exist. |
| 2 | Wrong user name or password. |
| 3 | User name (xxx) does not have accesss to the Web Service (VefthjonustaID=yyy). |
| 4 | User name (xxx) does not have accesss to the Web Service (VefthjonustaID yyy) from IP no. zzz. |
| 205 | The contract owner's Icelandic SS no. is missing. |
| 206 | The contract owner's Icelandic SS no. must be 10 digits. |
| 207 | The SS no. does not exist. |
| 208 | User name x does not have access to the contract associated with Icelandic SS no. y. |
| 214 | Expiration date is missing. |
| 215 | Expiration date must be 4 digits. |
| 219 | Virtual card number is missing. |
| 220 | Virtual card number is void. Virtual card number is 16 digits where digits 2 through 9 are 99999. |
| 221 | Virtual card number does not exist. |
| 304 | audkenningNidurstadaCavd, other name CAVD or CAVV (Cardholder Authentication Verification Data/Value), can not be empty. This field is returned back to the AudkenningTokstUrl (See FaAudkenningu web service) when the cardholder has completed his authentication. This is an encrypted string containing the authentication itself. |
| 306 | The posiId is not registered in the new Valitor authorization system (VAS). Please contact support to get the posiId moved over. |
| 307 | AudkenningNidurstadaTxid, other name txid or xid can not be empty. This field is returned back to the AudkenningTokstUrl (See FaAudkenningu web service) when the cardholder has completed his authentication. This is an encrypted string containing the authentication itself. |
| 216 | Verification code is missing. |
| 217 | Verification code is too long. |
| 227 | SS no. x does not have access to virtual card number y . |
| 999 | Unknown error. (Different messages may appear.) |
6.5 - FaOgildingu
This function is used to cancel or refund a transaction that has already been done using the FaHeimild function.
Transaction cancellation is done if the transaction has not been cleared.
Clearing is done at the end of each day.
If the transaction has already been cleared then this function performs a refund that will be cleared at end of day.
It's necessary to reference the original transaction by using the Faerslunumber from the response in FaHeimild and use in the request for FaOgildingu.
6.5.1 - Definitions
6.5.1.1 - Request
| Field | Type | Len. min | Len. max | Usage | Description |
|---|---|---|---|---|---|
| Notandanafn | AN | 1 | 50 | M | Merchant's Web Service user name. |
| Lykilord | AN | 1 | 50 | M | Merchant's Web Service password. |
| Samningsnumer | N | 6 | 6 | M | Merchant's contract no. |
| SamningsKennitala | N | 10 | 10 | M | Contract's Icelandic SS no. |
| PosiID | B | 1 | - | M | POS terminal ID received from Valitor. |
| Syndarkortnumer | N | 16 | 16 | M | Virtual card no. received from the function FaSyndarkortnumer. |
| Upphaed | N | 1 | - | M | Amount of the cancellation. If amount is 0, then no authorization lookup is performed and the service responds with an empty response with Error Code = 0 |
| Faerslunumer | AN | 6 | 6 | M | Transaction number of the transaction being cancelled. This is the value that is in Kvittun -> Faerslunumer when FaHeimild is used. |
| Stillingar | AN | 1 | 250 | O | Additional parameters. Not currently in use. |
6.5.1.2 - Response
| Field | Type | Len. min | Len. max | Usage | Description |
|---|---|---|---|---|---|
| Villuskilabod | AN | 1 | 16 | M | Error description. Is empty if there is no error. |
| Villunumer | N | 1 | 3 | M | Error no. Is 0 if no error. See table in 4.3.3. |
| VilluLogID | N | 1 | - | M | Error ID in Valitor logs |
| Kvittun/Receipts | OB | - | - | - | Kvittun/Receipts object |
6.5.1.2.1 - Receipts Response Object
| Field | Type | Len. min | Len. max | Usage | Description |
|---|---|---|---|---|---|
| VerslunNafn | AN | 1 | - | M | Name of store. |
| VerslunHeimilisfang | AN | 1 | - | M | Store address. |
| VerslunStadur | AN | 1 | - | M | Place of store. |
| TegundKorts | AN | 1 | - | M | Card type, e.g. VISA. |
| TegundKortsKodi | N | 3 | 3 | M | No longer used. |
| Dagsetning | AN | 10 | 10 | M | Authorization date. |
| Timi | AN | 1 | - | M | Authorization time. |
| Kortnumer | AN | 19 | 19 | M | Starred card no. where last 4 digits appear. |
| Upphaed | AN | 19 | 19 | M | Amount. |
| Faerslunumer | N | 5 | 5 | M | Transaction no. |
| Faersluhirdir | AN | 19 | 19 | M | Acquirer name and phone no. |
| Heimildarnumer | N | 6 | 6 | M | Authorization number. |
| StadsetningNumer | N | 4 | 4 | M | Location no., default 0001. |
| UtstodNumer | N | 4 | 4 | M | Terminal no., default 0001. |
| BuidAdOgilda | B | - | - | M | True if transaction canceled. |
| Bunkanumer | AN | 8 | 8 | M | Not in use. | Soluadilinumer | AN | 8 | 8 | M | Merchant contract no. with prefix S. |
| Hugbunadarnumer | N | 11 | 11 | M | Permanent no.: 11101020000. |
| PosiID | N | 1 | - | M | POS terminal ID allocated by Valitor. |
| PinSkilabod | - | - | - | - | Not used. |
| Vidskiptaskilabod | AN | 1 | - | M | Text, currency and amount. |
| F22_1til4 | N | 4 | 4 | M | Not used. |
| LinaC1 | N | 3 | 3 | M | Not used. |
| LinaC2 | N | 4 | 4 | M | Not used. |
| LinaC3 | AN | 1 | - | M | Text and transaction no. |
| LinaC4 | AN | 1 | - | M | Text and authorization no. |
| LinaD1 | - | - | - | - | Not used. |
| LinaD2 | - | - | - | - | Not used. |
| TegundAdgerd | AN | 11 | 11 | M | Standard text: ÓGILDING. |
| FaerslunumerUpphafleguFaerslu | - | - | - | M | Not in use. |
| TerminalID | N | 8 | 8 | M | Terminal ID. |
6.5.2 - Examples
6.5.2.1 - Request
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <FaOgildingu xmlns="http://api.Valitor.is/Fyrirtaekjagreidslur/"> <Notandanafn>AbC123</Notandanafn> <Lykilord>84jkf</Lykilord> <Samningsnumer>60000</Samningsnumer> <SamningsKennitala>2112683579</SamningsKennitala> <PosiID>1</PosiID> <Syndarkortnumer>4999993986001010</Syndarkortnumer> <Gjaldmidill>ISK</Gjaldmidill> <Upphaed>100</Upphaed> <Faerslunumer>213323</Faerslunumer> <Stillingar></Stillingar> </FaOgildingu> </soap:Body> </soap:Envelope>
6.5.2.2 - Response
<?xml version="1.0" encoding="utf-8"?> <HeimildSkilabod xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns=" http://api.Valitor.is/Fyrirtaekjagreidslur/"> <Villunumer>0</Villunumer> <Villuskilabod /> <VilluLogID>0</VilluLogID> <Kvittun> <VerslunNafn>123.is ehf</VerslunNafn> <VerslunHeimilisfang>Pósthólf 12063</VerslunHeimilisfang> <VerslunStadur>Reykjavik</VerslunStadur> <TegundKorts>VISA</TegundKorts> <TegundKortsKodi></TegundKortsKodi> <Dagsetning>14.05.2009</Dagsetning> <Timi>09:38</Timi> <Kortnumer>****-****-****-6987</Kortnumer> <Upphaed>50</Upphaed> <Faerslunumer>213327</Faerslunumer> <Faersluhirdir>Valitor, sími: 525 2000</Faersluhirdir> <Heimildarnumer>114355</Heimildarnumer> <StadsetningNumer>0001</StadsetningNumer> <UtstodNumer /> <BuidAdOgilda>false</BuidAdOgilda> <Bunkanumer /> <Soluadilinumer>0039189</Soluadilinumer> <Hugbunadarnumer>11101020000</Hugbunadarnumer> <PosiID>0001</PosiID> <PinSkilabod /> <Vidskiptaskilabod>VIÐSKIPTI ISK: 50</Vidskiptaskilabod> <F22_1til4/> <LinaC1/> <LinaC2/> <LinaC3>FÆRSLUNR: 0000001</LinaC3> <LinaC4>HEIMILD:114355</LinaC4> <LinaD1 /> <LinaD2 /> <TegundAdgerd>ÓGILDING</TegundAdgerd> <FaerslunumerUpphafleguFaerslu/> <TerminalID>11100004</TerminalID> </Kvittun> </HeimildSkilabod>
6.5.2.3 - Response error
<?xml version="1.0" encoding="utf-8"?> <?xml version="1.0" encoding="utf-8"?> <HeimildSkilabod xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns=" http://api.Valitor.is/Fyrirtaekjagreidslur/"> <Villunumer>233</Villunumer> <Villuskilabod>PosiID 89 tilheyrir ekki samningsnúmerinu 000122.</Villuskilabod> <VilluLogID>0</VilluLogID> <Kvittun> <VerslunNafn/> <VerslunHeimilisfang/> <VerslunStadur/> <TegundKorts/> <Dagsetning/> <Timi/> <Kortnumer/> <Upphaed/> <Faerslunumer/> <Faersluhirdir/> <Heimildarnumer/> <StadsetningNumer/> <UtstodNumer/> <BuidAdOgilda>false</BuidAdOgilda> <Bunkanumer/> <Soluadilinumer/> <Hugbunadarnumer/> <PosiID/> <PinSkilabod/> <Vidskiptaskilabod/> <F22_1til4/> <LinaC1/> <LinaC2/> <LinaC3/> <LinaC4/> <LinaD1/> <LinaD2/> <TegundAdgerd/> <FaerslunumerUpphafleguFaerslu/> <TerminalID/> </Kvittun> </HeimildSkilabod>
6.5.3 - Errors
| Error Code | Description |
|---|---|
| 1 | The web service id does not exist. |
| 2 | Wrong username or password. |
| 3 | The username (xxx) does not have access to the web service id (VefthjonustaID=yyy). |
| 4 | The username (xxx) does not have access to the web service (VefthjonustaID yyy) from the ip address zzz. |
| 200 | Missing agreement number. |
| 201 | The agreement number must be 6 digits. it is possible to fill out with 0 in front. |
| 202 | Contract number x does not exist. |
| 204 | Contract number x is not associated with Icelandic SS number y. |
| 205 | The contract owner's Icelandic SS no. is missing. |
| 206 | The contract owner's Icelandic SS no. Must be 10 digits. |
| 207 | The SS no. does not exist. |
| 208 | User name x does not have access to the contract associated with Icelandic SS no. y. |
| 209 | POS terminal ID is missing. |
| 210 | POS terminal ID must be in digits only. |
| 306 | The posiId is not registered in the new Valitor authorization system (VAS). Please contact support to get the posiId moved over. |
| 219 | Virtual card number is missing. |
| 220 | Virtual card number is void. |
| 221 | Virtual card number x does not exist. |
| 225 | Currency must be 3 characters. |
| 226 | Contract number x is not listed for currency y. |
| 227 | SS no. x does not have access to virtual card number y. |
| 229 | Failed to cancel. Different messages can appear. |
| 230 | POS terminal ID x is not associated with SS no. y. |
| 231 | The card associated with virtual card number x has expired. The card ends in y. |
| 233 | PosiID x does not belong to agreement number y. |
| 500 | System error. (Text can vary) |
| 999 | Unknown error. (Text can vary) |
Tip
It's highly recommended when integrating with Corporate Payments that integration allows for other error codes to be returned from the web services.