Introduction
In order to integrate Klarna to your checkout you will need to use our API methods. To create an order you will need to use the function reserve_amount .
Sandbox and live environment access information
To test Klarna’s services, you need to apply for API credentials for the test environment. The test environment is exactly the same as Klarna’s live system, except no real invoices will be created and no credit checks are made.
To connect to the test environment, you need to change the host and port in the Klarna client libraries.
Host: payment.testdrive.klarna.com Port: 443
Digest
A digest is a cryptographic hash function that takes a block of data and returns a fixed-size bit string. The digest is used to verify the integrity of the call as well as to identify the caller, and sent in as a base64 encoded string.
Note: the string is formatted to hexadecimal before encoding.
Supported hashing algorithms are, in descending order of recommendation:
- SHA-512
- SHA-384
- SHA-256
- SHA-128
- MD5 (deprecated)
The use of MD5 is strongly discouraged, and has been deprecated.
Error handling
When an error occurs, Klarna will respond with an error code and a message . The error message language is determined by the language code in the API call. If no language code can be used, Klarna will answer with the language of the consumer.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
<?xml version="1.0" encoding="ISO-8859-1"?> <methodResponse> <fault> <value> <struct> <member> <name>faultCode</name> <value> <int>8114</int> </value> </member> <member> <name>faultString</name> <value> <string>A problem ...</string> </value> </member> </struct> </value> </fault> </methodResponse>
Methods
get_addresses
Get_addresses can be used by Swedish private persons or organizations with one or more registered addresses. Klarna will return all registered addresses based on social security or organization number.
The get_addresses function may only be used as long as the following requirements are met:
- The function can only be used by consumers with a Swedish social security number or organization
- Customer data is only retrieved for Klarna’s payment methods in the checkout
- The function may not be used for registering customers
- The function may only be used after providing the consumer with Klarna’s User Terms and Privacy Notice .
- The get_addresses function and received data must disappear if the consumer chooses another payment method (non Klarna payment methods)
- The consumer needs to actively press a button to collect the data, it may not be triggered by completion of a form field
- The button is not allowed to be called get address (hämta address). Approved names: Fetch (Hämta), Continue (Fortsätt), Search (Sök), Proceed (Vidare)
- You may not state the source of the address received
- The received data must be obfuscated/masked in such a way that it is not possible for anyone else but the consumer to understand if the data is correct or not. I.e. the obfuscation/masking should be done in such a way that the function cannot be used as a address look up service.
Digest
Consist of the values from eid, pno and secret (in this order) separated with a colon without the square brackets.
Example: base64encode(hex(sha512("[eid]:[pno]:[shared_secret]")))
Return value
An array of arrays containing the addresses (one array per address). The array contains strings.
Example when using Type 5 or 1 0 = First name (not returned if company) 1 = Last name or company name 2 = Address 3 = Postno 4 = City 5 = Country
Call structure
* Required
Variable | Type | Description |
---|---|---|
Variable proto_vsn * | Type string | Description Use 4.1. Automatically set in the library. |
Variable client_vsn * | Type string | Description xmlrpc:my-store-name:version-number. Automatically set in the library. |
Variable eid * | Type string | Description A merchant ID which refers to your store in Klarna’s database |
Variable pno * | Type string | Description Consumer’s social security number. Use the following format: (SE) yymmdd-nnnn, it can be sent with or without dash “-” or with or without the two first numbers in the year. |
Variable digest * | Type string | Description Digest for authentication. Klarna’s libraries do this for you together with the shared secret. |
Variable pno_encoding * | Type int | Description 2: Sweden |
Variable type * | Type int | Description How the name will be returned. We recommend type 5.1: Gives all first names that the person has. 2: Gives only the last name and the consumer fills out the first name. 5: Gives the persons given name if available, otherwise it returns all names. Recommended |
Variable client_ip * | Type string | Description The IP address of the consumer who initiates the call |
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
<?xml version="1.0" encoding="ISO-8859-1"?> <methodCall> <methodName>get_addresses</methodName> <params> <param> <value> <!-- proto_vsn --> <string>4.1</string> </value> </param> <param> <value> <!-- client_vsn --> <string>xmlrpc:my-store-name:1.2.3</string> </value> </param> <param> <value> <!-- pno --> <int>4103219202</int> </value> </param> <param> <value> <!-- merchant id (eid) --> <string>0</string> </value> </param> <param> <value> <!-- shared_secret --> <string>replace_with_digest</string> </value> </param> <param> <value> <!-- pno_encoding --> <int>2</int> </value> </param> <param> <value> <!-- type --> <int>5</int> </value> </param> <param> <value> <!-- client_ip --> <string>customer_ip_address</string> </value> </param> </params> </methodCall>
has_account
To verify whether the consumer has an active part payment plan. The has_account function works only in the Nordic countries. If the function answers true, then you should put part payment as the default payment option.
Digest
Consist of the values from eid, pno and secret (in this order) separated with a colon without the square brackets.
Example: base64encode(hex(sha512("[eid]:[pno]:[shared_secret]")))
Return value
String - true or false
Call structure
* Required
Variable | Type | Description |
---|---|---|
Variable proto_vsn * | Type string | Description Use 4.1. Automatically set in the library. |
Variable client_vsn * | Type string | Description xmlrpc:my-store-name:version-number. Automatically set in the library. |
Variable eid * | Type int | Description A merchant ID which refers to your store in Klarna’s database |
Variable pno * | Type string | Description Consumer’s social security number. Use the following format:SE: YYMMDD-NNNN, it can be sent with or without dash “-” or with or without the two first numbers in the year. FI: DDMMYY-NNNN, it can be sent with or without dash “-”. NO: DDMMYYNNNNN DK: DDMMYYNNNN |
Variable digest * | Type string | Description Digest for authentication. Klarna’s libraries do this for you together with the shared secret. |
Variable pno_encoding * | Type int | Description Indicates the person’s country of origin2: Sweden 3: Norway 4: Finland 5: Denmark |
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42
<?xml version="1.0" encoding="ISO-8859-1"?> <methodCall> <methodName>has_account</methodName> <params> <param> <value> <!-- proto_vsn --> <string>4.1</string> </value> </param> <param> <value> <!-- client_vsn --> <string>xmlrpc:my-store-name:1.2.3</string> </value> </param> <param> <value> <!-- merchant id (eid) --> <int>0</int> </value> </param> <param> <value> <!-- pno --> <string>4103219202</string> </value> </param> <param> <value> <!-- shared_secret --> <string>replace_with_digest</string> </value> </param> <param> <value> <!-- pno_encoding --> <int>2</int> </value> </param> </params> </methodCall>
get_pclasses
To obtain pclass values from Klarna’s system.
Pclasses represent the various payment methods offered by Klarna. When calling reserve_amount, the pclass variable is used to specify the payment method that has been selected by the consumer. Pclasses are also necessary to calculate monthly costs on the product and checkout pages.
Please note: get_pclasses function is to be used to obtain pclass values for stores one time only, unless you get a new type of part payment assigned to your store. You are not permitted to use get_pclasses function for continuous calculation of monthly costs or with every purchase in the checkout.
Depending on the configuration, the libraries will store the pclasses locally in your system. Make sure your webserver user can access the file or database for both reading and writing when making a get_pclasses call.
The get_pclasses should not be confused with the library method “getPClasses” which gets locally stored pclasses. The libraries refer to the get_pclasses call as “fetch_pclasses”.
Digest
Consist of the values from eid, currency and secret (in this order) separated with a colon without the square brackets.
Example: base64encode(hex(sha512("[eid]:[currency]:[shared_secret]")))
Return value
An array of arrays containing the pclass values
0 = Pclass id number 1 = Description 2 = Amount of months for part payment 3 = Start fee 4 = Invoice fee 5 = Interest rate 6 = Minimum purchase amount for pclass 7 = Country 8 = Type (This is used to determine what type the pclass id is and which calculation method is to be used, see below for the different options.) 9 = Pclass expiry date in the format YYYY-MM-DD. This is used for Buy now, pay in X months.
Type no | Description |
---|---|
Type no 0 | Description Part payment - fixed |
Type no 1 | Description Part payment - flexible |
Type no 2 | Description Buy now, pay in X month e.g. christmas campaign) |
Type no 3 | Description Fixed price |
Type no 4 | Description Pay in X months |
Type no 5 | Description Klarna mobile |
Call structure
* Required
Variable | Type | Description |
---|---|---|
Variable proto_vsn * | Type string | Description Use 4.1. Automatically set in the library. |
Variable client_vsn * | Type string | Description xmlrpc:my-store-name:version-number. Automatically set in the library. |
Variable eid * | Type int | Description A merchant ID which refers to your store in Klarna’s database |
Variable currency * | Type int | Description Currency code for which you want to retrieve pclasses0: Swedish krona 1: Norwegian krona 2: Euro 3: Danish krona Please note! Currency must match the country variable e.g. SEK and Sweden. |
Variable digest * | Type string | Description Digest for authentication. Klarna’s libraries do this for you together with the shared secret. |
Variable country* | Type int | Description Country code for which you want to retrieve pclasses15: Austria 59: Denmark 73: Finland 81: Germany 154: Netherlands 164: Norway 209: Sweden Please note! Currency must match the country variable e.g. SEK and Sweden. |
Variable language * | Type int | Description Language code in which language you want to retrieve pclasses27: Danish 28: German 28: Austria 37: Finnish 97: Norwegian 101: Dutch 138: Swedish |
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
<?xml version="1.0" encoding="ISO-8859-1"?> <methodCall> <methodName>get_pclasses</methodName> <params> <param> <value> <!-- proto_vsn --> <string>4.1</string> </value> </param> <param> <value> <!-- client_vsn --> <string>xmlrpc:my-store-name:1.2.3</string> </value> </param> <param> <value> <!-- merchant id (eid) --> <int>0</int> </value> </param> <param> <value> <!-- currency --> <int>0</int> </value> </param> <param> <value> <!-- shared_secret --> <string>replace_with_digest</string> </value> </param> <param> <value><!-- country --> <int>209</int> </value> </param> <param> <value> <!-- language --> <int>138</int> </value> </param> </params> </methodCall>
reserve_amount
To create a reservation (order) in Klarna’s system. The reservation is valid, by default, for 7 days.
Digest
Consist of the values from eid, pno, amount and secret (in this order) separated with a colon without the square brackets.
Example: base64encode(hex(sha512("[eid]:[pno]:[amount]:[shared_secret]")))
Return value
Array - [rno, invoiceStatus]
The value of “rno” is the reservation number for the purchase, at most 255 char string. The value of “invoiceStatus” shows if the reservation can be delivered immediately or requires manual approval by Klarna. If you receive “Pending”, you can use check_order_status to query Klarna for a new status.
1 = OK 2 = Pending
Call structure
* Required
† Required in Austria, Germany and the Netherlands
Variable | Type | Description |
---|---|---|
Variable proto_vsn * | Type string | Description Use 4.1. Automatically set in the library. |
Variable client_vsn * | Type string | Description xmlrpc:my-store-name:version-number. Automatically set in the library. |
Variable pno * | Type string | Description Consumer’s social security number or birth date. Use the following format:SE: YYMMDD-NNNN, it can be sent with or without dash “-” or with or without the two first numbers in the year. FI: DDMMYY-NNNN, it can be sent with or without dash “-”. NO: DDMMYYNNNNN DK: DDMMYYNNNN DE: DDMMYYYY AT: DDMMYYYY NL: DDMMYYYY |
Variable gender † | Type int | Description Gender of consumer0: Female 1: Male |
Variable amount * | Type int | Description Amount to be reserved, including VAT, given in cents, e.g. 10000 = 100 EUR. |
Variable reference | Type string | Description The reference person for the purchase if it is a company purchase. You can also use reference variable to write a message or other important information to the consumer on the invoice. Requires a setting which can be made by Klarna integration sales. |
Variable reference_code | Type string | Description The reference code for the sale. You can also use reference_code variable to write a message or other important information to the consumer on the invoice. Requires a setting which can be made by Klarna integration sales. |
Variable orderid1 | Type string | Description Order ID #1 |
Variable orderid2 | Type string | Description Order ID #2 |
Variable delivery_address * | Type array | Description Delivery address. See address structure below for more information. Please observe that for Sweden the address must be exactly as you receive with get_addresses function. |
Variable billing_address * | Type array | Description Billing address. See address structure below for more information. |
Variable client_ip * | Type string | Description IP number of the consumer when the purchase is made online |
Variable flags * | Type int | Description Flag which affects the invoiced purchase. Input 0 to set no flag.2: If you set this flag, a test reservation is created despite your store working in live mode. It comes in handy if you wish to test something while avoiding any disturbance to your regular invoicing. “Klarna Mobil” flags 512: To tell Klarna that it’s a phone transaction 1024: To send the consumer a PIN code. |
Variable currency * | Type int | Description Currency code to be used for the invoices0: Swedish krona 1: Norwegian krona 2: Euro 3: Danish krona Please note: Currency, country and language must be the same as where the consumer is registered. E.g. Swedish consumer, SEK, Sweden and Swedish. |
Variable country * | Type int | Description Code for the country where your sales will be:15: Austria 59: Denmark 73: Finland 81: Germany 154: Netherlands 164: Norway 209: Sweden Please note: Currency, country and language must be the same as where the consumer is registered. E.g. Swedish consumer, SEK, Sweden and Swedish. |
Variable language * | Type int | Description Language code for the language used on the invoice.27: Danish 28: German 28: Austria 37: Finnish 97: Norwegian 101: Dutch 138: Swedish Please note: Currency, country and language must be the same as where the consumer is registered. E.g. Swedish consumer, SEK, Sweden and Swedish. |
Variable eid * | Type int | Description A merchant ID which refers to your store in Klarna’s database |
Variable digest * | Type string | Description Digest for authentication. Klarna’s libraries do this for you together with the shared secret. |
Variable pno_encoding * | Type int | Description Indicates the country where the consumer is registered:2: Sweden 3: Norway 4: Finland 5: Denmark 6: Germany 7: Netherlands 8: Austria Please note: Currency, country and language must be the same as where the consumer is registered. E.g. Swedish consumer, SEK, Sweden and Swedish. |
Variable pclass * | Type int | Description Pclass variable designates code to be used at the purchase and is utilized when the sale is a part payment or invoice purchase. If the sale is an invoice (14 days) purchase, pclass variable shall be set to -1.-1 = invoice (14 days) xxx = Part payment or invoice * Part payments are not available for organizations. *There are two ways to retrieve pclasses. 1. Go to Klarna Online and press “view store” button in the menu on the left. In the store view, click “Click here to view campaigns”. 2. Use the function get_pclasses to save all pclass values to your database. |
Variable goods_list * | Type array | Description See goods list structure below for more information |
Variable comment | Type string | Description Not available currently |
Variable shipment_info * | Type array | Description See shipment info structure below for more information |
Variable travel_info | Type array | Description Extra data from merchants selling travel tickets, talk to your Integration Sales representative for more information about travel info structure for your integration. |
Variable income_expense | Type array | Description Not used at this moment |
Variable bank_info | Type array | Description Not used at this moment |
Variable session_id | Type array | Description Not used at this moment |
Variable extra_info | Type array | Description Talk to your integration sales representative if you are asked to send in extra information to Klarna. |
address structure
* Required † Required in Germany and Netherlands ‡ Required in Netherlands ❧ Required if cellno is not used ☙ Required if telno is not used
Variable | Type | Description |
---|---|---|
Variable fname * | Type string | Description Consumer’s first name |
Variable lname * | Type string | Description Consumer’s last name |
Variable careof | Type string | Description C/O address (this field must be submitted in case it is collected in the e-store checkout) |
Variable company | Type string | Description Company name (this field must be submitted in case it is collected in the e-store checkout) |
Variable street * | Type string | Description Street address |
Variable house_number † | Type string | Description House number. Used in Germany and Netherlands. For all other countries you can send in an empty string. |
Variable house_extension ‡ | Type string | Description House extension. Only used in Netherlands, if the customer has one. For all other countries you can send in an empty string. |
Variable zip * | Type string | Description Zip Code |
Variable city * | Type string | Description City |
Variable country * | Type integer | Description Code for the country where the consumer lives:15: Austria 59: Denmark 73: Finland 81: Germany 154: Netherlands 164: Norway 209: Sweden |
Variable telno ❧ | Type string | Description Telephone number |
Variable cellno ☙ | Type string | Description Cellphone number |
Variable email * | Type string | Description E-mail address |
Goods list structure
* Required
Variable | Type | Description |
---|---|---|
Variable qty * | Type integer | Description Quantity of the articles |
Variable artno * | Type string | Description Article number |
Variable title * | Type string | Description Article title |
Variable price * | Type integer | Description Article price, excluding VAT, given in cents, e.g. 10000 = 100 EUR. We always recommend to send in the price incl VAT by using the flag 32. |
Variable vat * | Type double | Description VAT in percent |
Variable discount | Type double | Description Discount in percent |
Variable flags | Type integer | Description 8: Indicates that the item is a shipment fee 16: Indicates that the item is a handling fee 32: Send the prices including VAT |
shipment_info structure
* Required
Variable | Type | Description |
---|---|---|
Variable delay_adjust * | Type int | Description The two values determine how long after invoice activation Klarna starts countdown to the expiration date. Both countdowns are by default zero days. The time of the countdowns can be negotiated with Klarna. 1: Normal shipment 2: Express shipment |
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396
<?xml version="1.0" encoding="ISO-8859-1"?> <methodCall> <methodName>reserve_amount</methodName> <params> <param> <value> <!-- proto_vsn --> <string>4.1</string> </value> </param> <param> <value> <!-- client_vsn --> <string>xmlrpc:my-store-name:1.2.3</string> </value> </param> <param> <value> <!-- pno --> <string>4103219202</string> </value> </param> <param> <value> <!-- gender --> <!-- If left empty, send as string --> <int>0</int> </value> </param> <param> <value> <!-- amount --> <int>10000</int> </value> </param> <param> <value> <!-- reference --> <string>Testperson-se Approved</string> </value> </param> <param> <value> <!-- reference_code --> <string>Department 160</string> </value> </param> <param> <value> <!-- orderid1 --> <string>12345</string> </value> </param> <param> <value> <!-- orderid2 --> <string>6789</string> </value> </param> <param> <value> <!-- delivery_address --> <struct> <member> <name>fname</name> <value> <string>Testperson-se</string> </value> </member> <member> <name>lname</name> <value> <string>Approved</string> </value> </member> <member> <name>careof</name> <value> <string>C/O last name</string> </value> </member> <member> <name>company</name> <value> <string>Test company</string> </value> </member> <member> <name>street</name> <value> <string>Stårgatan 1</string> </value> </member> <member> <name>house_number</name> <value> <string></string> </value> </member> <member> <name>house_extension</name> <value> <string></string> </value> </member> <member> <name>zip</name> <value> <string>12345</string> </value> </member> <member> <name>city</name> <value> <string>Ankeborg</string> </value> </member> <member> <name>country</name> <value> <int>209</int> </value> </member> <member> <name>telno</name> <value> <string></string> </value> </member> <member> <name>cellno</name> <value> <string>0765260000</string> </value> </member> <member> <name>email</name> <value> <string>testperson-se@example.com</string> </value> </member> </struct> </value> </param> <param> <value> <!-- billing_address --> <struct> <member> <name>fname</name> <value> <string>Testperson-se</string> </value> </member> <member> <name>lname</name> <value> <string>Approved</string> </value> </member> <member> <name>careof</name> <value> <string>C/O last name</string> </value> </member> <member> <name>company</name> <value> <string>Test company</string> </value> </member> <member> <name>street</name> <value> <string>Stårgatan 1</string> </value> </member> <member> <name>house_number</name> <value> <string></string> </value> </member> <member> <name>house_extension</name> <value> <string></string> </value> </member> <member> <name>zip</name> <value> <string>12345</string> </value> </member> <member> <name>city</name> <value> <string>Ankeborg</string> </value> </member> <member> <name>country</name> <value> <int>209</int> </value> </member> <member> <name>telno</name> <value> <string></string> </value> </member> <member> <name>cellno</name> <value> <string>0765260000</string> </value> </member> <member> <name>email</name> <value> <string>testperson-se@example.com</string> </value> </member> </struct> </value> </param> <param> <value> <!-- client_ip --> <string>customer_ip_address</string> </value> </param> <param> <value> <!-- flags --> <int>0</int> </value> </param> <param> <value> <!-- currency --> <int>0</int> </value> </param> <param> <value> <!-- country --> <int>209</int> </value> </param> <param> <value> <!-- language --> <int>138</int> </value> </param> <param> <value> <!-- eid --> <int>0</int> </value> </param> <param> <value> <!-- shared_secret --> <string>replace_with_digest</string> </value> </param> <param> <value> <!-- pno_encoding --> <int>2</int> </value> </param> <param> <value> <!-- pclass --> <int>-1</int> </value> </param> <param> <value> <array> <data> <value> <!-- goods_list --> <struct> <member> <name>goods</name> <value> <struct> <member> <name>title</name> <value> <string>Matrox G200 MMS</string> </value> </member> <member> <name>price</name> <value> <int>29999</int> </value> </member> <member> <name>discount</name> <value> <int>0</int> </value> </member> <member> <name>flags</name> <value> <int>32</int> </value> </member> <member> <name>artno</name> <value> <string>MG200MMS</string> </value> </member> <member> <name>vat</name> <value> <int>25</int> </value> </member> </struct> </value> </member> <member> <name>qty</name> <value> <int>1</int> </value> </member> </struct> </value> </data> </array> </value> </param> <param> <value> <!-- comment --> <string></string> </value> </param> <param> <value> <!-- shipment_info --> <struct> <member> <name>delay_adjust</name> <value> <int>1</int> </value> </member> </struct> </value> </param> <param> <value> <!-- traveL_info --> <struct></struct> </value> </param> <param> <value> <!-- income_expense --> <struct></struct> </value> </param> <param> <value> <!-- bank_info --> <struct></struct> </value> </param> <param> <value> <!-- session_id --> <struct></struct> </value> </param> <param> <value> <!-- extra_info --> <struct></struct> </value> </param> </params> </methodCall>