Klarna Merchant Urls.address Update API
The Merchant Urls.address Update API from Klarna — 1 operation(s) for merchant urls.address update.
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.address Update API
license:
name: Klarna Bank AB
servers:
- url: https://api.klarna.com
tags:
- name: Merchant Urls.address Update
paths:
/merchant_urls.address_update:
post:
summary: Address update
description: Will be called whenever the consumer changes billing or shipping address. The order will be updated according to the response received by Checkout.
operationId: updateAddress
requestBody:
$ref: '#/components/requestBodies/shipping_service_request'
responses:
'200':
description: Address looks good. The order will be updated according to response data.
content:
application/json:
schema:
$ref: '#/components/schemas/shipping_service_response'
'301':
description: Bad Address. Checkout will redirect the consumer to the page in Location header value.
headers: {}
'302':
description: Bad Address. Checkout will redirect the consumer to the page in Location header value.
headers: {}
'303':
description: Bad Address. Checkout will redirect the consumer to the page in Location header value.
headers: {}
'307':
description: Bad Address. Checkout will redirect the consumer to the page in Location header value.
headers: {}
'400':
description: 'Bad address. 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:
application/json:
schema:
$ref: '#/components/schemas/shipping_service_error_response'
tags:
- Merchant Urls.address Update
components:
schemas:
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
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
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.
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
ProductV1:
type: object
properties:
name:
type: string
description: Carrier product name
identifier:
type: string
description: Carrier product identifier
shipping_service_error_response:
type: object
required:
- error_text
- error_type
properties:
error_type:
type: string
example: address_error
description: 'Error type. Possible values: <em>unsupported_shipping_address</em>, <em>address_error</em> or <em>approval_failed</em>'
error_text:
type: string
example: Ooops, something went wrong...
description: Error text. Required if error_type is <em>address_error</em> or <em>approval_failed</em>
shipping_service_request:
type: object
required:
- order_amount
- order_lines
- order_tax_amount
- purchase_currency
properties:
order_amount:
type: integer
format: int64
description: Non-negative, minor units. Total total amount of the order, including tax and any discounts.
minimum: 0
order_tax_amount:
type: integer
format: int64
description: Non-negative, minor units. The total tax amount of the order.
minimum: 0
order_lines:
type: array
description: The applicable order lines (max 1000)
items:
$ref: '#/components/schemas/order_line'
maxItems: 1000
minItems: 0
billing_address:
$ref: '#/components/schemas/AddressV1'
shipping_address:
$ref: '#/components/schemas/AddressV1'
selected_shipping_option:
$ref: '#/components/schemas/shipping_option'
purchase_currency:
type: string
example: USD
description: ISO 4217 purchase currency.
pattern: ^[A-Za-z]{3,3}$
merchant_data:
type: string
description: Pass through field (max 6000 characters).
readOnly: true
merchant_reference1:
type: string
description: Used for storing merchant's internal order number or other reference. If set, will be shown on the confirmation page as "order number" (max 255 characters).
readOnly: true
merchant_reference2:
type: string
description: Used for storing merchant's internal order number or other reference (max 255 characters).
readOnly: true
customer:
$ref: '#/components/schemas/customer'
locale:
type: string
example: en-US
description: RFC 1766 customer's locale.
readOnly: true
tags:
type: array
description: The product's extra features, example ["dangerous_goods", "bulky"]
items:
type: string
order_line:
type: object
required:
- name
- quantity
- tax_rate
- total_amount
- total_tax_amount
- unit_price
properties:
type:
type: string
example: physical
description: Type of the order line item. The possible values are:<ul><li><em>physical (physical good)</em></li><li><em>discount</em></li><li><em>shipping_fee</em></li><li><em>sales_tax (depends on the country/city, usually called VAT)</em></li><li><em>digital (digital good)</em></li><li><em>gift_card</em></li><li><em>store_credit (credit from the merchant)</em></li><li><em>surcharge (extra charge)</em></li></ul>
reference:
type: string
example: 19-402-USA
description: Article number, SKU or similar. (max 255 characters)
minLength: 0
maxLength: 255
name:
type: string
example: Red T-Shirt
description: Descriptive name of the order line item (max 255 characters)
minLength: 1
maxLength: 255
quantity:
type: integer
format: int64
example: 5
description: Non-negative number. Quantity of the order line item.
minimum: 0
subscription:
$ref: '#/components/schemas/subscription'
quantity_unit:
type: string
example: pcs
description: Unit used to describe the quantity, e.g. kg, pcs... If defined has to be 1-8 characters
unit_price:
type: integer
format: int64
example: 10000
description: 'Minor units. Includes tax, excludes discount. (max value: 100000000).
Example: 100 Euros should be 10000.'
maximum: 100000000
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: 50000
description: "Minor units. Includes tax and discount. \n\nExample: 25 euros should be 2500\nValue = (quantity x unit_price) - total_discount_amount.\n(max value: 100000000)"
maximum: 100000000
total_discount_amount:
type: integer
format: int64
example: 0
description: 'Non-negative minor units. Includes tax.
Example: 25 euros should be 2500'
minimum: 0
total_tax_amount:
type: integer
format: int64
example: 4545
description: Must be within �1 of total_amount - total_amount \* 10000 / (10000 + tax_rate). Negative when type is discount.
merchant_data:
type: string
example: '{"marketplace_seller_info":[{"product_category":"Women''s Fashion","product_name":"Women Sweatshirt"}]}'
description: Property used to store additional metadata per item that will be returned whenever an order is read from Klarna. Pass through field. (max 1024 characters).
minLength: 0
maxLength: 1024
product_url:
type: string
example: https://www.example.com/products/f2a8d7e34
description: URL to the product page that can be later embedded in communications between Klarna and the customer. (max 1024 characters)
minLength: 0
maxLength: 1024
image_url:
type: string
example: https://www.exampleobjects.com/product-image-1200x1200.jpg
description: 'URL to an image that can be later embedded in communications between Klarna and the customer. (max 1024 characters)
Improves post-purchase customer experiences.'
minLength: 0
maxLength: 1024
product_identifiers:
$ref: '#/components/schemas/product_identifiers'
shipping_attributes:
$ref: '#/components/schemas/shipping_attributes'
payment_provider:
type: object
required:
- name
- redirect_url
properties:
name:
type: string
example: PayhereUs
description: The name of the payment provider. (max 255 characters)
minLength: 0
maxLength: 255
fee:
type: integer
format: int64
description: Minor units. Includes tax.
description:
type: string
example: an American company operating a worldwide online payments system
description: Short description of the payment method. This is displayed below the selected payment method. (max 500 characters)
minLength: 0
maxLength: 500
countries:
type: array
description: If specified, limits the method to the listed countries (alpha 2 codes).
items:
type: string
label:
type: string
example: continue
description: Controls label of buy button<ul><li>continue</li><li>complete</li></ul>
redirect_url:
type: string
example: https://www.example.com/us/start
description: URL to redirect to. (must be https, min 7, max 2000 characters)
minLength: 7
maxLength: 2000
image_url:
type: string
example: https://www.exampleobjects.com/product-image-1200x1200.jpg
description: URL to an image to display. (must be https, max 2000 characters)
minLength: 0
maxLength: 2000
AddressV1:
type: object
properties:
given_name:
type: string
example: John
description: Given name.
family_name:
type: string
example: Doe
description: Family name.
email:
type: string
example: john@doe.com
description: E-mail address.
title:
type: string
example: Mr
description: Title.<p>Valid values for UK:</p><ul><li><em>Mr</em></li><li><em>Ms</em></li><li><em>Mrs</em></li><li><em>Miss</em></li></ul><p>Valid values for DACH:</p><ul><li><em>Herr</em></li><li><em>Frau</em></li></ul><p>Valid values for NL:</p><ul><li><em>Dhr.</em></li><li><em>Mevr.</em></li></ul>
street_address:
type: string
example: Lombard St 10
description: Street address, first line. (Street name and number)
street_address2:
type: string
example: Apt 214
description: Street address, second line. (Apartment number, suite, etc.)
street_name:
type: string
example: Lombard St
description: Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See <b>streetNumber</b>.
street_number:
type: string
example: '10'
description: Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See <b>streetName</b>.
house_extension:
type: string
example: B
description: House extension. Only applicable in NL
postal_code:
type: string
example: '90210'
description: Postal/post code.
city:
type: string
example: Beverly Hills
description: City.
region:
type: string
example: CA
description: State or Region.
phone:
type: string
example: '333444555'
description: Phone number.
country:
type: string
example: US
description: ISO 3166 alpha-2. Country.
care_of:
type: string
example: C/O
description: Care of.
shipping_service_response:
type: object
required:
- order_amount
- order_lines
- order_tax_amount
- purchase_currency
properties:
order_amount:
type: integer
format: int64
description: Non-negative, minor units. Total total amount of the order, including tax and any discounts.
minimum: 0
order_tax_amount:
type: integer
format: int64
description: Non-negative, minor units. The total tax amount of the order.
minimum: 0
merchant_data:
type: string
example: '{"marketplace_seller_info":[{"product_category":"Women''s Fashion","product_name":"Women Sweatshirt"}]}'
description: Pass through field (max 1024 characters).
minLength: 0
maxLength: 1024
order_lines:
type: array
description: The applicable order lines (max 1000)
items:
$ref: '#/components/schemas/order_line'
maxItems: 1000
minItems: 0
shipping_options:
type: array
description: A list of shipping options available for this order.
items:
$ref: '#/components/schemas/shipping_option'
attachment:
$ref: '#/components/schemas/attachment'
purchase_currency:
type: string
example: USD
description: ISO 4217 purchase currency.
pattern: ^[A-Za-z]{3,3}$
locale:
type: string
example: en-US
description: RFC 1766 customer's locale.
pattern: ^[A-Za-z]{2,2}(?:-[A-Za-z]{2,2})*$
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'
tags:
type: array
description: 'Extra information added to the order.
Example: ["dangerous_goods", "bulky"]'
items:
type: string
address:
type: object
properties:
given_name:
type: string
example: John
description: Given name.
family_name:
type: string
example: Doe
description: Family name.
email:
type: string
example: john@doe.com
description: E-mail address.
title:
type: string
example: Mr
description: Title.<p>Valid values for UK:</p><ul><li><em>Mr</em></li><li><em>Ms</em></li><li><em>Mrs</em></li><li><em>Miss</em></li></ul><p>Valid values for DACH:</p><ul><li><em>Herr</em></li><li><em>Frau</em></li></ul><p>Valid values for NL:</p><ul><li><em>Dhr.</em></li><li><em>Mevr.</em></li></ul>
street_address:
type: string
example: Lombard St 10
description: Street address, first line. (Street name and number)
street_address2:
type: string
example: Apt 214
description: Street address, second line. (Apartment number, suite, etc.)
street_name:
type: string
example: Lombard St
description: Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See <b>streetNumber</b>.
street_number:
type: string
example: '10'
description: Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See <b>streetName</b>.
house_extension:
type: string
example: B
description: House extension. Only applicable in NL
postal_code:
type: string
example: '90210'
description: Postal/post code.
city:
type: string
example: Beverly Hills
description: City.
region:
type: string
example: CA
description: State or Region.
phone:
type: string
example: '333444555'
description: Phone number.
country:
type: string
example: US
description: ISO 3166 alpha-2. Country.
care_of:
type: string
example: C/O
description: Care of.
customer:
type: object
properties:
type:
type: string
example: person
description: The default supported value is 'person'. If B2B is enabled for the merchant, the value may be "organization".
gender:
type: string
example: male
description: Customers gender - male or female.
date_of_birth:
type: string
example: '1995-10-20'
description: Customers date of birth. The format is yyyy-mm-dd. ISO 8601 date.
organization_registration_id:
type: string
example: 556737-0431
description: '"The organization''s official registration id (organization number).
Note: Applicable only for B2B orders."'
vat_id:
type: string
description: Organization VAT ID. Only applies for b2b orders.
selected_addon:
type: object
properties:
type:
type: string
price:
type: integer
format: int64
external_id:
type: string
user_input:
type: string
DeliveryDetailsV1:
type: object
properties:
carrier:
type: string
description: Carrier product name
class:
type: string
description: Type of shipping class
product:
$ref: '#/components/schemas/ProductV1'
timeslot:
$ref: '#/components/schemas/TimeslotV1'
pickup_location:
$ref: '#/components/schemas/PickupLocationV1'
requestBodies:
shipping_service_request:
content:
application/json:
schema:
$ref: '#/components/schemas/shipping_service_request'