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: 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: unsupported_shipping_address, address_error or approval_failed' error_text: type: string example: Ooops, something went wrong... description: Error text. Required if error_type is address_error or approval_failed 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: 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 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.

Valid values for UK:

Valid values for DACH:

Valid values for NL:

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 streetNumber. street_number: type: string example: '10' description: Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName. 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.

Valid values for UK:

Valid values for DACH:

Valid values for NL:

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 streetNumber. street_number: type: string example: '10' description: Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName. 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'