Klarna Merchant Urls.validation API
The Merchant Urls.validation API from Klarna — 1 operation(s) for merchant urls.validation.
OpenAPI Specification
openapi: 3.0.0
info:
description: Hosted Payment Page (HPP) API is a service that lets you integrate Klarna Payments without the need of hosting the web page that manages the client side of Klarna Payments.
version: '1.1'
title: Klarna HPP Captures Merchant Urls.validation API
license:
name: Klarna Bank AB
servers:
- url: https://api.klarna.com
tags:
- name: Merchant Urls.validation
paths:
/merchant_urls.validation:
post:
summary: Order validation
description: Will be called before completing the purchase to validate the information provided by the consumer in Klarna's Checkout iframe.
operationId: validate
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/order'
responses:
'200':
description: Purchase approved. The consumer will then be redirected as usual to the checkout confirmation page.
'301':
description: Purchase denied. Checkout will redirect the consumer to the page in Location header value.
headers: {}
'302':
description: Purchase denied. Checkout will redirect the consumer to the page in Location header value.
headers: {}
'303':
description: Purchase denied. Checkout will redirect the consumer to the page in Location header value.
headers: {}
'307':
description: Purchase denied. Checkout will redirect the consumer to the page in Location header value.
headers: {}
'400':
description: 'This type of response can be used to show an error text message to the consumer. The response body should include one of the following values in the error_type field: ''address_error'', ''unsupported_shipping_address'' or ''approval_failed''. An ''error_text'' field can also be included in the response (mandatory if error_type is ''address_error'' or ''approval_failed''). The error message will be shown to the consumer and he or she will be kept in the Checkout page.'
content:
'*/*':
schema:
$ref: '#/components/schemas/shipping_service_error_response'
tags:
- Merchant Urls.validation
components:
schemas:
checkbox-v2:
type: object
required:
- checked
- id
- required
- text
properties:
text:
type: string
example: Please add me to the newsletter list, read more here \[link\](http://www.google.com)
description: Text that will be displayed to the consumer aside the checkbox. Links and formatting can be added using Markdown. (max 1000 characters)
checked:
type: boolean
description: Default state of the additional checkbox. It will use this value when loaded for the first time.
required:
type: boolean
description: Whether it is required for the consumer to check the additional checkbox box or not in order to complete the purchase.
id:
type: string
example: newsletter_opt_in
description: Identifier used when presenting data back to merchant
attachment:
type: object
required:
- body
- content_type
properties:
body:
type: string
example: '{"hotel_reservation_details": [{"pnr": "VH67899","hotel_intinerary": [{"hotel_name": "Hotel ltd.","address": {"street_address": "Storgatan 3","postal_code": "113 35","city": "Stockholm","country": "Sweden"},"start_time": "2019-01-31T15:00:00Z","end_time": "2019-01-31T15:30:00Z","number_of_rooms": 2,"ticket_delivery_method": "email","ticket_delivery_recipient": "jonas.larlsson@klarna.com","hotel_price": 23050,"class": "Business","passenger_id": [1]}],"passengers": [{"id": 1,"title": "mr","first_name": "Adam","last_name": "Adamson"}],"insurance": [{"insurance_company": "Insurance Company X","insurance_type": "travel","insurance_price": 0}],"affiliate_name": "TradeMaxi AB"}],"air_reservation_details": [{"pnr": "VH67899","intinerary": [{"departure": "ARN","departure_city": "Stockholm","arrival": "NCE","arrival_city": "Nice","carrier": "SK","segment_price": 34000,"departure_date": "2019-01-30T15:00:00Z","ticket_delivery_method": "email","ticket_delivery_recipient": "jonas.larlsson@klarna.com","passenger_id": [1]}],"passengers": [{"id": 1,"title": "mr","first_name": "Adam","last_name": "Adamson"}],"insurance": [{"insurance_company": "Insurance Company X","insurance_type": "travel","insurance_price": 0}],"affiliate_name": "TradeMaxi AB"}],"customer_account_info": [{"unique_account_identifier": "12345","account_registration_date": "2016-01-24T15:00:00Z","account_last_modified": "2017-01-24T15:00:00Z"}],"payment_history_full": [{"payment_option": "card","number_paid_purchases": 2,"total_amount_paid_purchases": 1234,"date_of_last_paid_purchase": "2018-01-24T15:00:00Z","date_of_first_paid_purchase": "2018-01-24T15:00:00Z"}]}'
description: The content of the extra merchant data which should be presented as a string inside this property. The body should be an object containing any of the keys and sub objects described below serialised to JSON. More information on that object can be found [here](https://docs.klarna.com/api/extra-merchant-data/).
content_type:
type: string
example: application/vnd.klarna.internal.emd-v2+json
description: The content type of the body. It is usually represented as "application/vnd.klarna.internal.emd-v2+json"
shipping_option:
type: object
required:
- id
- name
- price
- tax_amount
- tax_rate
properties:
id:
type: string
example: express_priority
description: id
name:
type: string
example: EXPRESS 1-2 Days
description: Name.
minLength: 1
maxLength: 255
description:
type: string
example: Delivery by 4:30 pm
description: Description.
promo:
type: string
example: Christmas Promotion
description: Promotion name. To be used if this shipping option is promotional.
price:
type: integer
format: int64
description: Price including tax.
preselected:
type: boolean
description: 'If true, this option will be preselected when checkout loads. Default: false'
tax_amount:
type: integer
format: int64
description: Tax amount.
tax_rate:
type: integer
format: int64
description: Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.
shipping_method:
type: string
example: PickUpStore
description: Shipping method. Possible values:<ul><li>PickUpStore</li><li>Home</li><li>BoxReg</li><li>BoxUnreg</li><li>PickUpPoint</li><li>Own</li><li>Postal</li><li>DHLPackstation</li><li>Digital</li></ul> If DHLPackstation is selected the correct form will be displayed.
delivery_details:
$ref: '#/components/schemas/DeliveryDetailsV1'
tms_reference:
type: string
example: a1b2c3d4-e4f6-g7h8-i9j0-k1l2m3n4o5p6
description: TMS reference. Required to map completed orders to shipments reserved in TMS.
selected_addons:
type: array
items:
$ref: '#/components/schemas/selected_addon'
product_identifiers:
type: object
properties:
brand:
type: string
example: Intel
description: The product's brand name as generally recognized by consumers. If no brand is available for a product, do not supply any value.
minLength: 0
maxLength: 70
color:
type: string
example: Blue
description: Color to be shown to the end customer (max 64 characters).
minLength: 0
maxLength: 64
category_path:
type: string
example: Electronics Store > Computers & Tablets > Desktops
description: 'The product''s category path as used in the merchant''s webshop. Include the full and most detailed category and separate the segments with '' > ''. (max 750 characters)
Example: "Electronics Store > Computers & Tablets > Desktops"'
minLength: 0
maxLength: 750
global_trade_item_number:
type: string
example: '735858293167'
description: The product's Global Trade Item Number (GTIN). Common types of GTIN are EAN, ISBN or UPC. Exclude dashes and spaces, where possible
minLength: 0
maxLength: 50
manufacturer_part_number:
type: string
example: BOXNUC5CPYH
description: The product's Manufacturer Part Number (MPN), which - together with the brand - uniquely identifies a product. Only submit MPNs assigned by a manufacturer and use the most specific MPN possible
minLength: 0
maxLength: 70
size:
type: string
example: Medium
description: Size to be shown to the end customer (max 64 characters).
minLength: 0
maxLength: 64
TimeslotV1:
type: object
properties:
id:
type: string
description: Id
start:
type: string
description: Start time
end:
type: string
description: End time
checkbox:
type: object
required:
- checked
- required
- text
properties:
text:
type: string
example: Please add me to the newsletter list, read more here \[link\](http://www.google.com)
description: Text that will be displayed to the consumer aside the checkbox. Links and formatting can be added using Markdown. (max 1000 characters)
checked:
type: boolean
description: Default state of the additional checkbox. It will use this value when loaded for the first time.
required:
type: boolean
description: Whether it is required for the consumer to check the additional checkbox box or not in order to complete the purchase.
merchant_urls:
type: object
required:
- checkout
- confirmation
- push
- terms
properties:
terms:
type: string
example: https://www.example.com/terms.html
description: 'URL for the terms and conditions page of the merchant. The URL will be displayed inside the Klarna Checkout iFrame.(max 2000 characters)
Example: "https://merchant.com/terms"'
minLength: 0
maxLength: 2000
checkout:
type: string
example: https://www.example.com/checkout.html
description: 'URL for the checkout page of the merchant. (max 2000 characters)
Example: "https://merchant.com/checkout"'
minLength: 0
maxLength: 2000
confirmation:
type: string
example: https://www.example.com/confirmation.html
description: 'URL of the merchant confirmation page. The consumer will be redirected back to the confirmation page if the authorization is successful after the customer clicks on the Place Order button inside checkout. The special characters of the confirmation URL should be encoded, e.g. the "space" character should be written as "%20". Then, on top of that, the whole confirmation URL should be encoded. E.g. the "space" character should become "%2520". (max 2000 characters)
Example: "https://merchant.com/confirmation"'
minLength: 0
maxLength: 2000
push:
type: string
example: https://www.example.com/api/push
description: 'URL that will be used for push notification when an order is completed. Should be different than checkout and confirmation URLs. (max 2000 characters)
Example: "https://merchant.com/push"'
minLength: 0
maxLength: 2000
validation:
type: string
example: https://www.example.com/api/validation
description: 'URL that will be requested for final merchant validation. (must be https, max 2000 characters)
Example: "https://merchant.com/validation"'
minLength: 0
maxLength: 2000
notification:
type: string
example: https://www.example.com/api/pending
description: 'URL for notifications on pending orders. (max 2000 characters)
Example: "https://merchant.com/notification/{checkout.order.id}"'
minLength: 0
maxLength: 2000
cancellation_terms:
type: string
example: https://www.example.com/terms/cancellation.html
description: 'URL for the cancellation terms page of the merchant. The URL will be displayed in the email that is sent to the customer after the order is captured.(max 2000 characters)
Example: "https://merchant.com/terms/cancelation"'
minLength: 0
maxLength: 2000
shipping_option_update:
type: string
example: https://www.example.com/api/shipment
description: 'URL for shipping option update. (must be https, max 2000 characters)
Example: "https://merchant.com/shippingoptionupdate"'
minLength: 0
maxLength: 2000
address_update:
type: string
example: https://www.example.com/api/address
description: 'URL for shipping, tax and purchase currency updates. Will be called on address changes. (must be https, max 2000 characters)
Example: "https://merchant.com/addressupdate"'
minLength: 0
maxLength: 2000
country_change:
type: string
example: https://www.example.com/api/country
description: 'URL for shipping, tax and purchase currency updates. Will be called on billing or shipping country changes. (must be https, max 2000 characters)
Example: "https://merchant.com/countrychange"'
minLength: 0
maxLength: 2000
subscription:
type: object
required:
- interval
- interval_count
properties:
name:
type: string
description: 'The name of the subscription product.
Example: "Premium Account"'
interval:
type: string
description: 'The cadence unit for this.
Example: "DAY"'
enum:
- DAY
- WEEK
- MONTH
- YEAR
interval_count:
type: integer
format: int32
description: 'The number of intervals.
Example: 30'
minimum: 1
discount_line:
type: object
required:
- name
- quantity
- tax_rate
- total_amount
- total_tax_amount
- unit_price
properties:
name:
type: string
example: Super deal
description: Descriptive name of discount
minLength: 1
maxLength: 255
quantity:
type: integer
format: int64
example: 5
description: Non-negative number. Quantity of the discount line item.
minimum: 0
unit_price:
type: integer
format: int64
example: -10000
description: 'Minor units. Includes tax, excludes discount. (Must be non-positive).
Example: -100 Euros should be -10000.'
maximum: 0
tax_rate:
type: integer
format: int64
example: 1000
description: 'Non-negative value. The percentage value is represented with two implicit decimals. (max 10000)
Example: 25% should be 2500.'
maximum: 10000
total_amount:
type: integer
format: int64
example: -2500
description: "Minor units. Includes tax and discount. \n\nExample: -25 euros should be -2500\nValue = (quantity x unit_price).\n(Must be non-positive)"
maximum: 0
total_tax_amount:
type: integer
format: int64
example: -123
description: Must be within �1 of total_amount - total_amount \* 10000 / (10000 + tax_rate). Should be non-positive
reference:
type: string
example: 645f54bb-dbb7-6e1f-83bd-bc81a2c3a258
description: The CRM reference to the gift-card that was entered by the user
minLength: 0
maxLength: 255
merchant_data:
type: string
example: '{"card_number":"5551234567890"}'
description: The gift-card number that was entered by the user
minLength: 0
maxLength: 1024
merchant_requested_checkbox:
type: object
properties:
id:
type: string
checked:
type: boolean
PickupLocationV1:
type: object
properties:
id:
type: string
description: Id
name:
type: string
description: Name of the location
address:
$ref: '#/components/schemas/address'
dimensions:
type: object
properties:
height:
type: integer
format: int64
example: 100
description: The product's height as used in the merchant's webshop. Non-negative. Measured in millimeters.
width:
type: integer
format: int64
example: 100
description: The product's width as used in the merchant's webshop. Non-negative. Measured in millimeters.
length:
type: integer
format: int64
example: 100
description: The product's length as used in the merchant's webshop. Non-negative. Measured in millimeters.
options:
type: object
properties:
require_validate_callback_success:
type: boolean
description: 'If true, validate callback must get a positive response to not stop purchase. Default: false.'
acquiring_channel:
type: string
description: 'Acquiring channel for the order. The possible values are:
<ul><li><em>ECOMMERCE for "E-commerce"</em></li><li><em>IN_STORE for "Purchase in boutique"</em></li><li><em>Default : ECOMMERCE</em></li></ul>'
pattern: ECOMMERCE|MOTO|IN_STORE|TELESALES
vat_removed:
type: boolean
description: If true, VAT is not displayed in Checkout's Order Summary page.
allow_separate_shipping_address:
type: boolean
description: 'If true, the consumer can enter different billing and shipping addresses. Default: false, except for purchase_country DE where default is: true'
color_button:
type: string
example: '#FF9900'
description: Color for the buttons within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
pattern: ^#[A-Fa-f0-9]{6}$
color_button_text:
type: string
example: '#FF9900'
description: Color for the text inside the buttons within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
pattern: ^#[A-Fa-f0-9]{6}$
color_checkbox:
type: string
example: '#FF9900'
description: Color for the checkboxes within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
pattern: ^#[A-Fa-f0-9]{6}$
color_checkbox_checkmark:
type: string
example: '#FF9900'
description: Color for the checkboxes checkmark within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
pattern: ^#[A-Fa-f0-9]{6}$
color_header:
type: string
example: '#FF9900'
description: Color for the headers within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
pattern: ^#[A-Fa-f0-9]{6}$
color_link:
type: string
example: '#FF9900'
description: Color for the hyperlinks within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
pattern: ^#[A-Fa-f0-9]{6}$
date_of_birth_mandatory:
type: boolean
description: 'If true, the consumer cannot skip date of birth. Default: false'
shipping_details:
type: string
example: Delivered within 1-3 working days
description: A message that will be presented on the confirmation page under the headline "Delivery" (max 255 characters).
title_mandatory:
type: boolean
description: If specified to false, title becomes optional. Only available for orders for country GB.
additional_checkbox:
$ref: '#/components/schemas/checkbox'
national_identification_number_mandatory:
type: boolean
description: 'If true, the user cannot skip national identification number in SE, NO, FI and DK. Default: false. In order to read the national identification number in the validation callback, please contact Klarnas merchant support.'
additional_merchant_terms:
type: string
description: 'Additional merchant defined field. e.g. Extra terms and conditions to show.
Example: "ADDITIONAL MERCHANT TERMS! \[terms link\](https://merchant.com/extra_terms)"'
phone_mandatory:
type: boolean
description: If false, the consumer can skip the phone. Only available for orders in DACH countries.
radius_border:
type: string
example: '5'
description: Radius for the border of elements within the iFrame.
allowed_customer_types:
type: array
description: 'A list of allowed customer types. Supported types: <b>person</b> & <b>organization</b>.
Example: ["person","organization"]'
items:
type: string
maxItems: 2
minItems: 1
show_subtotal_detail:
type: boolean
description: 'If true, the Order Detail subtotals view is expanded when the Klarna Checkout iFrame is loaded. Default: false'
additional_checkboxes:
type: array
items:
$ref: '#/components/schemas/checkbox-v2'
verify_national_identification_number:
type: boolean
description: Enable verification of National Identification Numbers only in Sweden and Norway. This option also make the national identification number mandatory. (Not applicable for countries outside of Sweden and Norway)
auto_capture:
type: boolean
description: Allow merchant to trigger auto capturing.
require_client_validation:
type: boolean
description: If true, a client side validation is needed to complete the purchase
enable_discount_module:
type: boolean
description: Enables the inline discount module
show_vat_registration_number_field:
type: boolean
description: If true, a optional VAT registration number field will be shown in the address form. Only applies for b2b orders.
shipping_attributes:
type: object
properties:
weight:
type: integer
format: int64
example: 1000
description: The product's weight as used in the merchant's webshop. Non-negative. Measured in grams.
dimensions:
$ref: '#/components/schemas/dimensions'
tags:
type: array
description: The product's extra features, example ["dangerous_goods", "bulky"]
items:
type: string
merchant_requested:
type: object
properties:
additional_checkbox:
type: boolean
description: Informs whether the additional_checkbox is checked or not, when applicable.
readOnly: true
additional_checkboxes:
type: array
description: Informs whether the additional_checkboxes is checked or not, when applicable.
readOnly: true
items:
$ref: '#/components/schemas/merchant_requested_checkbox'
order:
type: object
required:
- locale
- order_amount
- order_lines
- order_tax_amount
- purchase_country
- purchase_currency
properties:
order_id:
type: string
example: f3392f8b-6116-4073-ab96-e330819e2c07
description: Unique order ID that will be used for the entire lifecycle of the order. (max 255 characters)
readOnly: true
name:
type: string
example: Women's Fashion
description: The merchant name (max 255 characters).
readOnly: true
purchase_country:
type: string
example: US
description: "The purchase country of the merchant's store. The format to be used is ISO 3166 alpha-2. Eg: GB, SE, DE, US, etc. \n\nNote: purchase country and currency need to match the defined merchant configuration. For global configuration see more details [here](https://docs.klarna.com/kco/use-cases/selling-to-multiple-countries/)"
pattern: ^[A-Za-z]{2,2}$
purchase_currency:
type: string
example: USD
description: 'The purchase currency of the merchant''s store. The format to be used is ISO 4217. Eg: USD, EUR, SEK, GBP, etc.
Note: purchase country and currency need to match the defined merchant configuration. For global configuration see more details [here](https://docs.klarna.com/kco/use-cases/selling-to-multiple-countries/)'
pattern: ^[A-Za-z]{3,3}$
locale:
type: string
example: en-US
description: Used to define the language and region of the customer. RFC 1766 customer's locale.
pattern: ^[A-Za-z]{2,2}(?:-[A-Za-z]{2,2})*$
status:
type: string
example: CHECKOUT_INCOMPLETE
description: The current status of the order. The status will be incomplete until the customer has been successfully authorized.
billing_address:
$ref: '#/components/schemas/address'
shipping_address:
$ref: '#/components/schemas/address'
order_amount:
type: integer
format: int64
example: 50000
description: 'Total amount of the order including tax and any available discounts. The value should be in non-negative minor units.
Example: 25 Euros should be 2500.'
minimum: 0
order_tax_amount:
type: integer
format: int64
example: 4545
description: 'Total tax amount of the order. The value should be in non-negative minor units.
Example: 25 Euros should be 2500.'
minimum: 0
order_lines:
type: array
description: An array containing list of line items that are part of this order. Maximum of 1000 line items could be processed in a single order.
items:
$ref: '#/components/schemas/order_line'
maxItems: 1000
minItems: 0
customer:
$ref: '#/components/schemas/customer'
merchant_urls:
$ref: '#/components/schemas/merchant_urls'
html_snippet:
type: string
example: <div id='klarna-checkout-container'><script>alert('Initializing Klarna Checkout');</script></div>
description: The HTML snippet that is used to render the checkout in an iframe.
readOnly: true
merchant_reference1:
type: string
example: 45aa52f387871e3a210645d4
description: 'Used for storing merchant''s internal order number or other reference. If set, will be shown on the confirmation page as "order number" . The value is also available in the settlement files. (max 255 characters).
Example: "45aa52f387871e3a210645d4"'
minLength: 0
maxLength: 255
merchant_reference2:
type: string
example: 45aa52f387871e3a210645d4
description: 'Used for storing merchant''s internal order number or other reference. The value is available in the settlement files. (max 255 characters).
Example: "45aa52f387871e3a210645d4"'
minLength: 0
maxLength: 255
started_at:
type: string
format: date-time
description: 'ISO 8601 datetime. The date and time when the order has been created. The format will be as follows:
"yyyy-mm-ddThh:mm:ssZ"'
readOnly: true
completed_at:
type: string
format: date-time
description: 'ISO 8601 datetime. The date and time when the order has been completed. The format will be as follows:
"yyyy-mm-ddThh:mm:ssZ"'
readOnly: true
last_modified_at:
type: string
format: date-time
description: 'ISO 8601 datetime. The date and time when the order was last modified. The format will be as follows:
"yyyy-mm-ddThh:mm:ssZ"'
readOnly: true
options:
$ref: '#/components/schemas/options'
attachment:
$ref: '#/components/schemas/attachment'
external_payment_methods:
type: array
description: List of external payment methods that will be displayed as part of payment methods in the checkout.
items:
$ref: '#/components/schemas/payment_provider'
external_checkouts:
type: array
description: 'List of external checkouts that will be displayed as part of payment methods in the checkout.
The image_url is required, and the image size has to be 276x48px'
items:
$ref: '#/components/schemas/payment_provider'
shipping_countries:
type: array
description: "List of allowed shipping countries for this order in ISO-3166 alpha-2 format.\n\nIf specified, the customer will be able to change the shipping country in the checkout and you will be notified through address_update callback or the shipping_address_change javascript event. \n\nIf not specified then the default value will be the purchase country.\n\nExample: look at billing_countries example."
items:
type: string
shipping_options:
type: array
description: A list of shipping options available for this order.
items:
$ref: '#/components/schemas/shipping_option'
merchant_data:
type: string
example: '{"marketplace_seller_info":[{"product_category":"Women''s Fashion","product_name":"Women Sweatshirt"}]}'
description: Pass through field to send any information about the order to be used later for reference while retrieving the order details (max 6000 characters).
minLength: 0
maxLength: 6000
gui:
$ref: '#/components/schemas/gui'
merchant_requested:
$ref: '#/components/schemas/merchant_requested'
selected_shipping_option:
$ref: '#/components/schemas/shipping_option'
recurring:
type: boolean
description: 'Indicates whether this purchase will create a token that can be used by the merchant to create recurring purchases. This must be enabled for the merchant to use. Default: false
Depending on specified country, recurring could be used for the following payment methods: Pay Later, Direct Debit, Card.'
recurring_token:
type: string
description: Token to be used when creating recurring orders.
readOnly: true
recurring_description:
type: string
description: Description to be added to the recurring order.
readOnly: true
minLength: 0
maxLength: 255
billing_countries:
type: array
description: 'List of allowed billing countries for this order.
If specified, the customer will be able to change the billing country in the checkout and you will be notified through country_change callback or the billing_address_change javascript event.
If not specified but shipping_countries is specified, will use same values as shipping_countries.
If not specified and shipping_countries is not specified, then the default value will be the purchase country.
Example: ["AD", "AE", "AG", "AI", "AL", "AM", "AQ", "AR", "AS", "AT",
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/klarna/refs/heads/main/openapi/klarna-merchant-urls-validation-api-openapi.yml