4 - Web Services

4.1 - HefjaSendingu (Start Transmission)

Before sending recurring transactions one should first use web service HefjaSendingu (Start Transmission) which returns BunkiID (Batch ID) that should be used in transmission of all transactions.

Attention

It is very important never to reuse the same Batch ID for the same merchant agreement - not even after one year.

This function refunds a sale which was made with the Web Payments Page. Sales that have already been refunded or voided can not be refunded.

4.1.1 - Definitions

4.1.1.1 - Request

Field Type Len. min Len. max Usage Description
Notandanafn S 1 50 M Username
Lykilord S 1 50 M Password
Samningsnumer S 6 6 M Merchant's recurring contract number
Bunkanumer S 7 7 M Batch Number assigned by the merchant, Valitor recommends starting with 0000001 and increasing by one. The Batch Number shall never be reused for the same merchant contract.
SamningsKennitala S 10 10 M Merchant's National ID.
BunkaUpphaed S - - - !!! attention This field is obsolete and is no longer used.
FjoldiFaerslna S - - - !!! attention This field is obsolete and is no longer used.
Syndarnumerasending B - - M True if the transmissions contains only tokens.

4.1.1.2 - Response

Field Type Len. min Len. max Usage Description
Villunumer N 1 3 M Error number. Cf. table 4.1.3.
Villuskilabod S 1 - M Error description. Empty if no error.
VilluLogID N 1 - M Error ID - as registered in Valitor system error logs.
KeyrsluTimiMillisek N 1 - M Response time in milliseconds.
BunkiID S 26 26 M Batch ID. 0 if error. This ID is used for sendind transactions.

4.1.2. Examples

4.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>
<HefjaSendingu xmlns="http://api.valitor.is/">
<Notandanafn>AbC123</Notandanafn>
<Lykilord>84jkf</Lykilord>
<Samningsnumer>60000</Samningsnumer>
<Bunkanumer>0000001</Bunkanumer>
<SamningsKennitala>6012966135</SamningsKennitala>
<BunkaUpphaed></BunkaUpphaed >
<FjoldiFaerslna></FjoldiFaerslna >
<Syndarnumerasending>vaxtalaust</Syndarnumerasending>
</HefjaSendingu>
</soap:Body> </soap:Envelope>

4.1.2.2 - Response

<?xml version="1.0" encoding="utf-8"?>
<HefjaSendingu xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.valitor.is/">
<Villunumer>0</Villunumer>
<Villuskilabod />
<VilluLogID>0</VilluLogID>
<BunkiID>15.10.2012 11:21:14:731000</BunkiID>
</HefjaSendingu>

4.1.2.3 - Error Response

<?xml version="1.0" encoding="utf-8"?>
<HefjaSendingu xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.valitor.is/">
<Villunumer>260</Villunumer>
<Villuskilabod>Samningsnúmer og bunkanúmer hefur komið inn áður.</Villuskilabod>
<VilluLogID>0</VilluLogID>
<BunkiID>0</BunkiID>
</HefjaSendingu>

4.1.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).
220 Merchant contract number is missing.
221 Contract number must be 6 digits (left filled with 0 if necessary).
222 Batch number is missing.
223 Batch number must be 7 digits.
224 National ID (kennitala) of the merchant is missing.
225 National ID (kennitala) of the merchant must be 10 digits.
226 Batch total amount is missing.
227 Batch total amount is not correct.
228 Transaction count is missing.
229 Transaction count is not correct.
242 User (xxx) does not have access to contract (yyy).
249 Sýndarnúmerasending (Token Transmission) needs to be True or False.
260 Contract number and batch number have been registered before.
300 Merchant contract number does not exist.
301 National ID (kennitala) does not exist.
302 Contract xxx is not connected to National ID yyy.
304 This contract is not open for recurring transactions.
500 System error. (Explanation text may vary.)
900 Unknown error. (Explanation text may vary.)

4.2 - SendaInn (Send In)

This function accepts transactions.

Attention

It is important to send one transaction at a time and wait for the response. All transactions in a batch need to be sent in within 96 hours.

4.2.1 - Definitions

4.2.1.1 - Request

Field Type Len. min Len. max Usage Description
Notandanafn S 1 50 M Username
Lykilord S 1 50 M Password
BunkiID S 26 26 M Batch ID in the Valitor system.
Samningsnumer S 6 6 M Merchant recurring agreement contract
Bunkanumer S 7 7 M Batch Number assigned by the merchant, Valitor recommends starting with 0000001 and increasing by one. The Batch Number shall never be reused for the same merchant agreement.
SamningsKennitala S 10 10 M Merchant National ID.
Tilvisunarnumer S 7 7 M Reference number. The same reference number and PAN shall not repeat in the same batch.
Kortnumer S 11 19 M Card number.
Gildistimi S 4 4 O Valid to MMYY. Not present for tokens.
Kortategund S 1 1 M V=VISA. M=MasterCard.
Upphaed S 1 7 M Amount to be charged. For refunds/payments to the cardholder the sign should be ”-” .
KennitalaHandhafa S 10 10 O Cardholder's National ID .
KennitalaRetthafa S 10 10 O Cardowner's National ID.
Skyring S 10 10 O Merchant National ID.

4.2.1.2 - Response

Field Type Len. min Len. max Usage Description
Villunumer N 1 3 M ErrorNumber. See table 4.1.3. If 0 - transmission succeeded.
Villuskilabod S 1 - M Error description. Empty if no error.
VilluLogID N 1 - M Error ID - as registered in Valitor system error logs.
KeyrsluTimiMillisek N 1 - M Response time in milliseconds.

4.2.2 - Examples

4.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>
<SendaInn xmlns="http://api.valitor.is/">
<Notandanafn>AbC123</Notandanafn>
<Lykilord>84jkf</Lykilord>
<BunkiID>15.10.2012 11:21:14:731000</BunkiID>
<Samningsnumer>60000</Samningsnumer>
<Bunkanumer>0000001</Bunkanumer>
<SamningsKennitala>6012966135</SamningsKennitala>
<Tilvisunarnumer>9348333</Tilvisunarnumer> <Kortnumer>4166453986001010</Kortnumer> <Gildistimi>0409</Gildistimi> <Kortategund>V</Kortategund> <Upphaed>1000</Upphaed> <KennitalaHandhafa>2112683579</KennitalaHandhafa> <KennitalaRetthafa>1010801234</KennitalaRetthafa> <Skyring>ADSL</Skyring>
</SendaInn>
</soap:Body> </soap:Envelope>

4.2.2.2 - Response

<?xml version="1.0" encoding="utf-8"?>
<SendaInn xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.valitor.is/">
<Villunumer>0</Villunumer>
<Villuskilabod />
<VilluLogID>0</VilluLogID>
</SendaInn>

4.2.2.3 - Error Response

<?xml version="1.0" encoding="utf-8"?>
<SendaInn xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.valitor.is/">
<Villunumer>259</Villunumer>
<Villuskilabod>Þetta kortnúmer og tilvísunarnúmer hefur komið fyrir áður í þessum bunka.</Villuskilabod>
<VilluLogID>0</VilluLogID>
</SendaInn>

4.2.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).
220 Merchant contract number is missing.
221 Contract number must be 6 digits (left filled with 0 if necessary).
222 Batch number is missing.
223 Batch number must be 7 digits.
224 National ID (kennitala) of the merchant is missing.
225 National ID (kennitala) of the merchant must be 10 digits.
230 Reference number must be 7 digits.
231 Missing card number.
232 Card number must consist of 11 to 19 digits.
233 Card expiry date must be 4 digits.
234 Missing Card Type.
235 Card Type must be one letter, e.g. V for Visa.
236 Amount is missing.
237 Amount must be numeric.
238 National ID (kennitala) of the cardholder must be 10 digits.
239 National ID (kennitala) of the card owner must be 10 digits.
240 Comments must not exceed 30 letters.
241 BunkiID (Batch ID) is missing.
243 No open batch with this Batch ID, merchant contract ID or batch number. A batch created more than 96 hours before no longer treated as open.
247 Incorrect token. Tokens (virtual PANs) are 16 digits where digits 2 till 6 are 99999.
256 Reference number is missing.
259 Duplicate card number and reference number in the same batch.
261 Invalid card number.
262 Expiry date should not be sent along with a token (virtual card number).
263 The merchant social security number yyyyyyyyyy does not have access to the supplied virtual number.
266 Merchant agreement xxxxxx is not allowed to accept MasterCard.
267 This is a token. This batch is not meant for transmission of tokens.
268 Amount must be less than 10.000.000 krónur.
305 Unsupported Card Type.
306 Unsupported Card Type.
500 System error. (Explanation text may vary.)
900 Unknown error. (Explanation text may vary.)

4.3 - SendinguLokid (Transmission Completed)

When all transactions have been sent call SendinguLokid.

Attention

A batch older than 96 hours is no longer considered open. An attempt to close such a batch will result in error message 243.

4.3.1 - Definitions

4.3.1.1 - Request

Field Type Len. min Len. max Usage Description
Notandanafn S 1 50 M Username
Lykilord S 1 50 M Password
BunkiID S 26 26 M Batch ID assigned by Valitor.
Samningsnumer S 6 6 M Merchant's recurring contract number
Bunkanumer S 7 7 M Batch Number assigned by the merchant, Valitor recommends starting with 0000001 and increasing by one. The Batch Number shall never be reused for the same merchant contract.
SamningsKennitala S 10 10 M Merchant's National ID.

4.3.2 - Examples

4.3.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>
<SendinguLokid xmlns="http://api.valitor.is/">
<Notandanafn>AbC123</Notandanafn>
<Lykilord>84jkf</Lykilord>
<BunkiID>15.10.2012 11:21:14:731000</BunkiID>
<Samningsnumer>60000</Samningsnumer>
<Bunkanumer>0000001</Bunkanumer>
<SamningsKennitala>6012966135</SamningsKennitala>
</SendinguLokid>
</soap:Body> </soap:Envelope>

4.3.2.2 - Response

<?xml version="1.0" encoding="utf-8"?>
<SendinguLokid xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.valitor.is/">
<Villunumer>0</Villunumer>
<Villuskilabod />
<VilluLogID>0</VilluLogID>
</SendinguLokid>

4.3.2.3 - Error response

<?xml version="1.0" encoding="utf-8"?>
<SendinguLokid xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.valitor.is/">
<Villunumer>257</Villunumer>
<Villuskilabod> Fjöldi innsenndra færslna er 45, en gefið var upp að 47 færslur yrðu sendar inn.</Villuskilabod>
<VilluLogID>0</VilluLogID></SendinguLokid>

4.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).
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).
220 Merchant contract number is missing.
221 Contract number must be 6 digits (left filled with 0 if necessary).
222 Batch number is missing.
223 Batch number must be 7 digits.
224 National ID (kennitala) of the merchant is missing.
225 National ID (kennitala) of the merchant must be 10 digits.
241 BunkiID (Batch ID) is missing.
242 User x does not have access to contracts with National ID (kennitala) yyyyyyyyyy.
243 No open batch with this Batch ID, merchant contract ID or batch number. A batch created more than 96 hours before no longer treated as open.
257 The number of received transaction is x, while y transactions were supposed to be transmitted.
258 The batch total amount of received transaction is x krónur, while the amount was supposed to be y krónur.
300 Merchant contract number does not exist.
301 National ID (kennitala) does not exist.
302 Contract xxx is not connected to National ID yyy.
304 This contract is not open for recurring transactions.
500 System error. (Explanation text may vary.)
900 Unknown error. (Explanation text may vary.)

4.4 - LaekkaBunka (Batch Adjustment - Retired)

Warning

LaekkaBunka is now retired from Recurring Payments

The operation LaekkaBunka is not active anymore in the Recurring Payments system. Those merchants who have already integrated with Recurring Payments can still call LaekkaBunka but it has no effect. The operation will only return a empty success response.

4.4.1 - Example response - Empty

<?xml version="1.0" encoding="utf-8"?>
<LaekkaBunka xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.valitor.is/">
<Villunumer>0</Villunumer>
<Villuskilabod />
<VilluLogID>0</VilluLogID>
</LaekkaBunka>

4.5 - NidurstodurSendingar (Processing Results)

It is possible to call this service often than once, for example, in case of a timeout for any reason.

4.5.1 - Definitions

4.5.1.1 - Request

Field Type Len. min Len. max Usage Description
Notandanafn S 1 50 M Username
Lykilord S 1 50 M Password
BunkiID S 26 26 M Batch ID assigned by Valitor.
Samningsnumer S 6 6 M Merchant's recurring contract number
Bunkanumer S 7 7 M Batch Number assigned by the merchant, Valitor recommends starting with 0000001 and increasing by one. The Batch Number shall never be reused for the same contract.
SamningsKennitala S 10 10 M Merchant's National ID.
SkilaFaerslurTokst S - - M Should return both transactions that were authorized and not authorized (True) or only them that where not authorized (False)

4.5.2 - Examples

4.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>
<NidurstodurSendingar xmlns="http://api.valitor.is/">
<Notandanafn>AbC123</Notandanafn>
<Lykilord>84jkf</Lykilord>
<BunkiID>15.10.2012 11:21:14:731000</BunkiID>
<Samningsnumer>60000</Samningsnumer>
<Bunkanumer>0000001</Bunkanumer>
<SamningsKennitala>6012966135</SamningsKennitala>
<SkilaFaerslurTokst>false</SkilaFaerslurTokst> </NidurstodurSendingar>
</soap:Body> </soap:Envelope>

4.5.2.2 - Response

<?xml version="1.0" encoding="utf-8"?>
<NidurstodurSendingar xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.valitor.is/">
<Villunumer>0</Villunumer>
<Villuskilabod />
<VilluLogID>0</VilluLogID>
<Bunki>
<BunkaFaersla>
<BunkiID>15.10.2012 11:21:14:731000</BunkiID> <Samningsnumer>60000</Samningsnumer> <Bunkanumer>0000001</Bunkanumer> <Keyrsludagur>15.10.2012 13:01:15:984000</Keyrsludagur>
<FjoldiFaerslna>9</FjoldiFaerslna> <FjoldiFaerslnaTokstAdSkuldfaera>8</FjoldiFaerslnaTokstAdSkuldfaera> <BunkaUpphaedVar>9000</BunkaUpphaedVar> <BunkaUpphaedVerdur>8000</BunkaUpphaedVerdur>
</BunkaFaersla> <NyKortnumer> <ListiKortnumer>
<Kortnumer> <Innsent>4177453986001011-0209</Innsent>
<Nytt>4112678298001010-0810</Nytt>
<KennitalaHandhafa>2312683579</KennitalaHandhafa>
<NafnHandhafa/></NafnHandhafa>
<Tilvisunarnumer>9348432</Tilvisunarnumer>
</Kortnumer> </ListiKortnumer>
<NyKortnumer>
<FaerslurHafnad> <ListiFaerslaHafnad>
<FaerslaHafnad> <Tilvisunarnumer>9348333</Tilvisunarnumer>
<Kortnumer>4166453986001010</Kortnumer>
<Upphaed>1000</Upphaed>
<KennitalaHandhafa>2112683579</KennitalaHandhafa>
<NafnHandhafa></NafnHandhafa> <KennitalaRetthafa>1010801234</KennitalaRetthafa> <Skyring>ADSL</Skyring>
<Astaeda>17</Astaeda>
</FaerslaHafnad> </ListiFaerslaHafnad>
</FaerslurHafnad>
</Bunki>
</NidurstodurSendingar>

4.5.2.3 - Error response

<?xml version="1.0" encoding="utf-8"?>
<LaekkaBunka xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.valitor.is/">
<Villunumer>243</Villunumer>
<Villuskilabod>Ekki til opinn bunki fyrir innsent BunkiID, samningsnúmer og bunkanúmer. Bunki stofnaður fyrir meira en 96 tímum telst ekki opinn.</Villuskilabod>
<VilluLogID>0</VilluLogID> </LaekkaBunka>

If expiration date is not given for a card it is shown as follows:

4166453986001010-

If it is given it will follow as shown after the hyphen:

4166453986001010-0810

"Astaeda" can have the following values:

00 = Approval
01 = Refer to Card Issuer
02 = Refer to Card Issuer, special condition (Visa)
04 = Pick-up Card
05 = Do not honour
07 = Pick-up Card, special condition (other than lost/stolen Card)
11 = VEAS approval (Visa EU advice)
12 = Invalid transaction
13 = Invalid amount
14 = Invalid Account Number (no such number)
15 = No such Issuer
19 = Re-enter transaction
41 = Pick-up Card (lost Card)
43 = Pick-up Card (stolen Card)
51 = Insufficient funds
52 = No current account
53 = No savings account
54 = Expired Card
57 = Transaction not permitted to Cardholder
58 = Transaction not allowed at terminal
61 = Activity amount limit exceeded
62 = Restricted Card (for example, in Country Exclusion table)
91 = Issuer unavailable
93 = Transaction cannot be completed; violation of law
96 = System malfunction or certain field error conditions

There can be other reasons than above mentioned and it should be taken into consideration when integrating with Recurring Payments.

In NyKortnumer(new cardnumbers) is a list of the cardnumbers that we try to charge when the cardnumber that was sent to us didn't get authorization. We look after a new card issued to the same cardholder.

Important

It is important to update the card number in the merchant's system according to the list that is returned.

In FaerslurTokst (transactions authorized) and FaerslurHafnad (transactions rejected) the former card is shown although another card is charged.

If the card number that is sent to us is closed and a new card is issued to the same cardholder we try to charge that card. If that new card number is declined for authorization it is still shown int the list of new cardnumbers.

Please note

Only cardnumbers that are sent to Valitor appear in the lists FaerslurTokst and FaerslurHafnad. „Ný kortnúmer“ are never shown in these lists.

If error 259 „Ekki til lokaður bunki fyrir innsent BunkiID, samningsnúmer og bunkanúmer.“ is shown in spite of successfull web service SendinguLokid (það skilaði villunúmeri 0) then the information are yet not imported into Valitors sysems.

4.5.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).
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).
220 Merchant contract number is missing.
221 Contract number must be 6 digits (left filled with 0 if necessary).
222 Batch number is missing.
223 Batch number must be 7 digits.
224 National ID (kennitala) of the merchant is missing.
225 National ID (kennitala) of the merchant must be 10 digits.
241 BunkiID (Batch ID) is missing.
242 User x does not have access to contracts with National ID (kennitala) yyyyyyyyyy.
243 No open batch with this Batch ID, merchant contract ID or batch number. A batch created more than 96 hours before no longer treated as open.
251 SkilaFaerslurTokst must be true or false.
252 Amount is missing.
253 Amount must be numeric.
254 Amount of transactions is missing.
255 Amount of transactions must be numeric.
259 There is not a closed Batch for insent BunkiID, samningsnúmer og bunkanúmer.
300 Merchant contract number does not exist.
301 National ID (kennitala) does not exist.
302 Contract xxx is not connected to National ID yyy.
304 This contract is not open for recurring transactions.
352 Batch processing has not been completed.
500 System error. (Explanation text may vary.)
900 Unknown error. (Explanation text may vary.)

4.6 - SkilaSyndarnumeriUtFraKortnumeri (Return Token for PAN)

Tokens (Virtual Card Numbers) are 16 digits long with digits 2 to 6 being 99999, e.g. 4999997698764321. The first digit is the same as in the real Card Number (alias PAN i.e. Primary Account Number).

Warning

Please note that as of 31.October 2020, cards registered with this web service are not in full compliance with the new SCA Regulatory Update. Older cards, registered before 31.October 2020, are still in full compliance. But new registrations are at a greater risk of being rejected by the card issuers. Please contact Valtior for information about alternative soulutions that fully comply with the SCA Regulatory update.

4.6.1 - Definitions

4.6.1.1 - Request

Field Type Len. min Len. max Usage Description
Notandanafn S 1 50 M Username
Lykilord S 1 50 M Password
SamningsKennitala S 10 10 M Merchant's National ID.
Samningsnumer S 6 6 M Merchant's recurring contract number
Kortnumer S 11 19 M Card number for which a token is requested.
Gildistimi S 4 4 M Expiry date as MMYY.

Please Note

For those who have already integrated with Recurring Payments Web Service, the parameter Gildistimi will remain optional until April 30th 2020.

4.6.2 - Examples

4.6.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>
<SkilaSyndarnumeriUtfraKortnumeri xmlns="http://api.valitor.is/">
<Notandanafn>AbC123</Notandanafn>
<Lykilord>84jkf</Lykilord>
<SamningsKennitala>6012966135</SamningsKennitala>
<Kortnumer>4166453986001010</Kortnumer> <Gildistimi>0409</Gildistimi> </SkilaSyndarnumeriUtfraKortnumeri>
</soap:Body> </soap:Envelope>

4.6.2.2 - Response

<?xml version="1.0" encoding="utf-8"?>
<SkilaSyndarnumeriUtFraKortnumeri xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.valitor.is/">
<Villunumer>0</Villunumer>
<Villuskilabod />
<VilluLogID>0</VilluLogID> <Syndarnumer>4999998765438764</Syndarnumer>
</SkilaSyndarnumeriUtFraKortnumeri>

4.6.2.3 - Error response

<?xml version="1.0" encoding="utf-8"?>
<SkilaSyndarnumeriUtfraKortnumeri xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.valitor.is/">
<Villunumer>305</Villunumer>
<Villuskilabod>Þjónustan styður ekki kortategund kortnúmers.</Villuskilabod>
<VilluLogID>0</VilluLogID> </SkilaSyndarnumeriUtfraKortnumeri>

4.6.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).
224 National ID (kennitala) of the merchant is missing.
225 National ID (kennitala) of the merchant must be 10 digits.
231 Missing card number.
232 Card number must consist of 11 to 19 digits.
233 Card expiry date must be 4 digits.
242 User x does not have access to contracts with National ID (kennitala) yyyyyyyyyy.
261 Invalid card number.
270 Expiry date missing
271 Card expired
305 Unsupported Card Type.
500 System error. (Explanation text may vary.)
900 Unknown error. (Explanation text may vary.)

4.7 - SkilaKortnumeriUtFraSyndarnumeri (Return PAN for Token)

This function returns only the last four digits of the original card number, even though the name suggests the full PAN.

4.7.1 - Definitions

4.7.1.1 - Request

Field Type Len. min Len. max Usage Description
Notandanafn S 1 50 M Username
Lykilord S 1 50 M Password
SamningsKennitala S 10 10 M Merchant's National ID.
Syndarnumer S 16 16 M Token (Virtual Card Number).

4.7.2 - Examples

4.7.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>
<SkilaKortnumeriUtFraSyndarnumeri xmlns="http://api.valitor.is/">
<Notandanafn>AbC123</Notandanafn>
<Lykilord>84jkf</Lykilord>
<SamningsKennitala>6012966135</SamningsKennitala>
<Syndarnumer>4999998765438764</Syndarnumer> </SkilaKortnumeriUtFraSyndarnumeri>
</soap:Body> </soap:Envelope>

4.7.2.2 - Response

<?xml version="1.0" encoding="utf-8"?>
<SkilaKortnumeriUtFraSyndarnumeri xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.valitor.is/">
<Villunumer>0</Villunumer>
<Villuskilabod />
<VilluLogID>0</VilluLogID> <Syndarnumer>****-****-****-1897</Syndarnumer>
</SkilaKortnumeriUtFraSyndarnumeri>

4.7.2.3 - Error response

<?xml version="1.0" encoding="utf-8"?>
<SkilaKortnumeriUtFraSyndarnumeri xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.valitor.is/">
<Villunumer>250</Villunumer>
<Villuskilabod> Ógilt sýndarnúmer. Sýndarnúmer er 16 tölustafir þar sem tölustafir 2 til 6 eru 99999.</Villuskilabod>
<VilluLogID>0</VilluLogID> </SkilaKortnumeriUtFraSyndarnumeri>

4.7.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).
246 Token does not exist.
250 Invalid token. Tokens are 16 digits long with digits 2 to 6 being 99999.
263 Merchant with National ID yyyyyyyyyy has no access at this token.
500 System error. (Explanation text may vary.)
900 Unknown error. (Explanation text may vary.)

4.8 - EydaBunka (Delete Batch)

Completed batches cannot be deleted. If a batch is deleted it is allowed to send a batch with the same batch number again.

4.8.1 - Definitions

4.8.1.1 - Request

Field Type Len. min Len. max Usage Description
Notandanafn S 1 50 M Username
Lykilord S 1 50 M Password
Samningsnumer S 6 6 M Merchant's recurring contract number
Bunkanumer S 7 7 M Batch Number assigned by the merchant, Valitor recommends starting with 0000001 and increasing by one. The Batch Number shall never be reused for the same merchant contract.
SamningsKennitala S 10 10 M Merchant's National ID.

4.8.2 - Examples

4.8.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>
<EydaBunka xmlns="http://api.valitor.is/">
<Notandanafn>AbC123</Notandanafn>
<Lykilord>84jkf</Lykilord>
<Samningsnumer>60000</Samningsnumer>
<Bunkanumer>0000001</Bunkanumer>
<SamningsKennitala>6012966135</SamningsKennitala> </EydaBunka>
</soap:Body> </soap:Envelope>

4.8.2.2 - Response

<?xml version="1.0" encoding="utf-8"?>
<EydaBunka xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.valitor.is/">
<Villunumer>0</Villunumer>
<Villuskilabod />
<VilluLogID>0</VilluLogID>
</EydaBunka>

4.8.2.3 - Error response

<?xml version="1.0" encoding="utf-8"?>
<EydaBunka xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.valitor.is/">
<Villunumer>264</Villunumer>
<Villuskilabod>Ekki hægt að eyða bunka þar sem innsendingu er lokið.</Villuskilabod>
<VilluLogID>0</VilluLogID> </EydaBunka>

4.8.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).
220 Token does not exist.
221 Contract number must be 6 digits (left filled with 0 if necessary).
222 Batch number is missing.
223 Batch number must be 7 digits.
224 National ID (kennitala) of the merchant is missing.
225 National ID (kennitala) of the merchant must be 10 digits.
242 User x does not have access to contracts with National ID (kennitala) yyyyyyyyyy.
264 Completed batches cannot be deleted.
265 Batch number xxxxxx cannot be found for merchant contract yyyyyy.
300 Merchant contract number does not exist.
301 National ID (kennitala) does not exist.
302 Contract xxx is not connected to National ID yyy.
304 This contract is not open for recurring transactions.
500 System error. (Explanation text may vary.)
900 Unknown error. (Explanation text may vary.)

4.9 - BunkaSkrar (Batch Files)

Creates a batch with transactions that need to be submitted through XML or JSON.
More than one batch may be submitted at once.

Please note

When a merchant sends either virtual or actual cards that have not been previously sent through the system, they need to be looked up and the first submissions using this operation may be a little slow if it includes many new cards. The following submissions will be quicker as the mapping for the card numbers has been performed and lookup isn't necessary.

In cases where virtual numbers are not used, the card expiry date is required.

Important information

Error codes in response can either be found under <SkilabodBunkaSkrar><Villunumer> and then the whole submission has failed. Otherwise they can be found under <SkilabodBunkaSkrar><BunkaInnsending><BunkiInnsending><Villunumer> and then a single batch in the submission has failed.

4.9.1 - Definitions

4.9.1.1 - Request

Field Type Len. min Len. max Usage Description
Notandanafn S 1 50 M Merchant's user name for the webservice
Lykilord S 1 50 M Merchant's password for the webservice
Bunkar S - - M The batch itself with transactions either on JSON or XML form
Tegund S 1 50 M Definition whether JSON or XML is being used for transactions
TegundTilkynningar S 1 50 O Notification type that should be used to notify merchant on the batch progress
Available options are email and/or webhook
Allowed values: Email, Webhook and EmailAndWebhook
Email S 1 50 O Email to send notifications to
Webhook S 1 100 O Merchant's URL to send notifications to
4.9.1.1.1 - Notifications

Notifications on batch progress are available after the batch has been submitted.

The notifications can be sent to merchant's email and/or to að certain URL provided by the merchant where notifications via Webhooks should be possible.

Merchant's Webhook website need to include a function/method that can receive a POST message with one parameter. - Message : Message to merchant on batch progress.

Along with this message a value called Bodgreidsla-Signature is included in the message header with a signature that the merchant can use to verify that the message is originated in Valitor's Recurring Payments.

The signature is a SHA512 hash value of the inner batch ID that the merchant receives back from SkilabodBunkaSkrar web service response.

Merchant can therefore perform this hash on the inner batch ID and compare it to the one in the Bodgreidsla-Signature in the Webhook message.

Example:
Batch with InnraBunkiId 001d2e61-4f01-4453-ae64-07f4ca204663 (inner batch ID) returns a notification message with 799C363CC2BF16E84DE2C3AFAAA2125B37578A0E9ABAEFA51485496A51D2649B8A771E120B6514BEAB3A9F509BE911EF357FEBA335A9D76E6FAD063D9323A3E7 in the header Bodgreidsla-Signature.

4.9.1.2 - Response

Field Tegund Len. min Len. max Usage Description
Villunumer N 1 3 M Error code
See table 4.9.3
Villuskilabod S 1 - M Error description
Empty if no error
VilluLogID N 1 - M Error ID - as registered in Valitor system error log systems
KeyrsluTimiMillisek N 1 - M Response time in milliseconds
BunkaInnsending O - - M List of BunkiInnsending, if multiple batches were submitted then this list should have equal number of objects
4.9.1.2.1 - BunkiInnsending Response Object
Field Type Len. min Len. max Usage Description
BunkaNumer S 7 7 M Batch number submitted by merchant
BunkiID S 26 26 M Batch ID
This is used to retrieve processing results in the NidurstodurSendingar web service
VilluLogID N 1 - M Error ID - as registered in Valitor system error log systems
InnraBunkiId S 36 36 M GUID (Globally Unique Identifier) representing the batch identity in Valitor's Inner Recurring Payments Webservice
May be used to confirm a notification message when Webhook is used to receive notifications
Villunumer N 1 3 M Error code for specific batch in submission
See table 4.9.3

4.9.2 - Examples

4.9.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>
<BunkaSkrar>
<Notandanafn>AbC123</Notandanafn>
<Lykilord>84jkf</Lykilord>
<Bunkar><BodgreidsluSkraningar>
  <Bunkar>
    <Bunki>
      <BunkaFaersla>
        <Samningsnumer>231517</Samningsnumer>
        <SamningsKennitala>1110793319</SamningsKennitala>
        <Bunkanumer>8892889</Bunkanumer>
        <SyndarnumerSending>true</SyndarnumerSending>
      </BunkaFaersla>
      <Faerslur>
        <Faersla>
          <Tilvisunarnumer>0000000</Tilvisunarnumer>
          <Upphaed>2400</Upphaed>
          <Kortnumer>2999990237099289</Kortnumer>
          <Gildistimi />
        </Faersla>
        <Faersla>
          <Tilvisunarnumer>0000001</Tilvisunarnumer>
          <Upphaed>2400</Upphaed>
          <Kortnumer>2999990237099289</Kortnumer>
          <Gildistimi />
        </Faersla>
        <Faersla>
          <Tilvisunarnumer>0000002</Tilvisunarnumer>
          <Upphaed>2400</Upphaed>
          <Kortnumer>2999990237099289</Kortnumer>
          <Gildistimi />
        </Faersla>
        <Faersla>
          <Tilvisunarnumer>0000003</Tilvisunarnumer>
          <Upphaed>2400</Upphaed>
          <Kortnumer>2999990237099289</Kortnumer>
          <Gildistimi />
        </Faersla>
        <Faersla>
          <Tilvisunarnumer>0000004</Tilvisunarnumer>
          <Upphaed>2400</Upphaed>
          <Kortnumer>2999990237099289</Kortnumer>
          <Gildistimi />
        </Faersla>
        <Faersla>
          <Tilvisunarnumer>0000005</Tilvisunarnumer>
          <Upphaed>2400</Upphaed>
          <Kortnumer>2999990237099289</Kortnumer>
          <Gildistimi />
        </Faersla>
      </Faerslur>
    </Bunki>
  </Bunkar>
</BodgreidsluSkraningar></Bunkar>
<Tegund>XML</Tegund>
<TegundTilkynningar>EmailAndWebhook</TegundTilkynningar>
<Email>merchant@test.is</Email>
<Webhook>https://merchant.is/webhook</Webhook>
</BunkaSkrar>
</soap:Body> </soap:Envelope>

<?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>
<BunkaSkrar>
<Notandanafn>AbC123</Notandanafn>
<Lykilord>84jkf</Lykilord>
<Bunkar>{"Bunkar":[{"BunkaFaersla":{"Samningsnumer":"231517","SamningsKennitala":"1110793319","Bunkanumer":"4142018","BunkaUpphaed":null,"FjoldiFaerslna":null,"SyndarnumerSending":"true"},"Faerslur":[{"Tilvisunarnumer":"0000000","Upphaed":"2400","Kortnumer":"2999990237099289","Gildistimi":""},{"Tilvisunarnumer":"0000001","Upphaed":"2400","Kortnumer":"2999990237099289","Gildistimi":""},{"Tilvisunarnumer":"0000002","Upphaed":"2400","Kortnumer":"2999990237099289","Gildistimi":""},{"Tilvisunarnumer":"0000003","Upphaed":"2400","Kortnumer":"2999990237099289","Gildistimi":""},{"Tilvisunarnumer":"0000004","Upphaed":"2400","Kortnumer":"2999990237099289","Gildistimi":""},{"Tilvisunarnumer":"0000005","Upphaed":"2400","Kortnumer":"2999990237099289","Gildistimi":""}]}]}</Bunkar>
<Tegund>JSON</Tegund>
<TegundTilkynningar>EmailAndWebhook</TegundTilkynningar>
<Email>merchant@test.is</Email>
<Webhook>https://merchant.is/webhook</Webhook>
</BunkaSkrar>
</soap:Body> </soap:Envelope>

4.9.2.2 - Response

<SkilabodBunkaSkrar xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.valitor.is/">
<Villunumer>0</Villunumer>
<Villuskilabod/>
<VilluLogID>0</VilluLogID>
<KeyrsluTimiMillisek>0</KeyrsluTimiMillisek>
<BunkaInnsending>
<BunkiInnsending>
<Bunkanumer>4142018</Bunkanumer>
<BunkiId>2020-04-29-23.27.25.830000</BunkiId>
<InnraBunkiId>17e7681b-5f78-44ba-b3d6-652768cff42c</InnraBunkiId>
<Villunumer>0</Villunumer>
</BunkiInnsending>
</BunkaInnsending>
</SkilabodBunkaSkrar>

4.9.2.3 - Error Response

<SkilabodBunkaSkrar xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.valitor.is/">
<Villunumer>0</Villunumer>
<Villuskilabod/>
<VilluLogID>0</VilluLogID>
<KeyrsluTimiMillisek>0</KeyrsluTimiMillisek>
<BunkaInnsending>
<BunkiInnsending>
<Bunkanumer>4142018</Bunkanumer>
<BunkiId>2020-05-13-11.16.19.353000</BunkiId>
<InnraBunkiId>ed72f30e-29fb-418b-81b5-5ceca46bd35f</InnraBunkiId>
<Villunumer>0</Villunumer>
</BunkiInnsending>
<BunkiInnsending>
<Bunkanumer>4142018</Bunkanumer>
<Villunumer>230</Villunumer>
<Villuskilabod>Tilvísunarnúmer verður að vera 7 tölustafir.</Villuskilabod>
</BunkiInnsending>
</BunkaInnsending>
</SkilabodBunkaSkrar>

4.9.3 - Error Codes

Error Code Description
220 Merchant contract number is missing.
221 Contract number must be 6 digits (left filled with 0 if necessary).
222 Batch number is missing.
223 Batch number must be 7 digits.
224 National ID (kennitala) of the merchant is missing.
225 National ID (kennitala) of the merchant must be 10 digits.
230 Reference number must be 7 digits.
231 Missing card number.
232 Card number must consist of 11 to 19 digits.
233 Card expiry date must be 4 digits.
236 Amount is missing.
237 Amount must be numeric.
247 Incorrect token. Tokens (virtual PANs) are 16 digits where digits 2 till 6 are 99999.
249 Sýndarnúmerasending (Token Transmission) needs to be True or False.
256 Reference number is missing.
261 Invalid card number.
267 This is a token. This batch is not meant for transmission of tokens.
268 Amount must be less than 10.000.000 kr.
270 Expiry date missing
271 Card expired
272 Batch file missing
273 Batch file type missing.
274 Batch file type does not contain supported value. Supported values are 'XML' and 'JSON'.
275 Batch XML format is not valid. Error : '{exception.Message}'
276 XML formatted batch can't be converted to JSON format. Error : '{exception.Message}'.
277 Email not valid.
278 TegundTilkynningar not supported. Supported values are 'Email', 'Webhook' or 'EmailAndWebhook'. Webhook is a website hosted by the merchant that is capable of receiving messages from Valitor's Recurring Payments.
279 Email missing
280 Webhook missing
281 Webhook must be a valid URL.
282 Missing batch transaction.
305 Unsupported Card Type.
500 System error. (Explanation text may vary.)
900 Unknown error. (Explanation text may vary.)