Klarna Merchant Urls.country Change API

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.country Change API
  license:
    name: Klarna Bank AB
servers:
- url: https://api.klarna.com
tags:
- name: Merchant Urls.country Change
paths:
  /merchant_urls.country_change:
    post:
      summary: Country change
      description: Will be called whenever the consumer changes  billing address country. The order will be updated according to the response received by Checkout.
      operationId: countryChange
      requestBody:
        $ref: '#/components/requestBodies/shipping_service_request'
      responses:
        '200':
          description: New country is accepted. The order will be updated according to response data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipping_service_response'
        '301':
          description: New country is not accepted. Checkout will redirect the consumer to the page in Location header value.
          headers: {}
        '302':
          description: New country is not accepted. Checkout will redirect the consumer to the page in Location header value.
          headers: {}
        '303':
          description: New country is not accepted. Checkout will redirect the consumer to the page in Location header value.
          headers: {}
        '307':
          description: New country is not accepted. 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.country Change
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'