Klarna Customer Token API

openapi: 3.2.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 Customer Token API
  license:
    name: Klarna Bank AB
servers:
- url: https://api.klarna.com
tags:
- name: Customer Token
paths:
  /customer-token/v1/tokens/{customerToken}:
    get:
      summary: Get customer token
      description: Use this API request to retrieve the content of a Klarna customer token. The request will return the status of the token as well as payment method details. To learn more, refer to the **Read customer tokens details article**.
      operationId: readCustomerToken
      parameters:
      - name: customerToken
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Token was successfully read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer_token'
        '403':
          description: You were not authorized to execute this operation.
        '404':
          description: The token does not exist.
      tags:
      - Customer Token
  /customer-token/v1/tokens/{customerToken}/order:
    post:
      summary: Create an order with a customer token
      description: Use this API call to create an order using a Klarna Customer Token. Make sure you use the correct token ID when placing an order, to ensure that the right consumer gets billed. Read more on **Create a new order using the customer token**.
      operationId: createOrder
      parameters:
      - name: customerToken
        in: path
        required: true
        schema:
          type: string
      - name: Klarna-Idempotency-Key
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customer_token_order'
      responses:
        '200':
          description: Order was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order'
        '400':
          description: We were unable to create an order with the provided data. Some field constraint was violated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorV2'
        '403':
          description: You were not authorized to execute this operation.
        '404':
          description: The token does not exist.
        '409':
          description: The data in the request does not match the session.
      tags:
      - Customer Token
  /customer-token/v1/tokens/{customerToken}/status:
    patch:
      summary: Update customer token status
      description: Use this API call to update the status of a Klarna Customer Token. This should be used if you want to cancel a specific customer token. Read more on **Update the status of a customer token**.
      operationId: patchCustomerToken
      parameters:
      - name: customerToken
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customer_token_status_update_request'
      responses:
        '202':
          description: Token patch request has been accepted and is being processed.
        '400':
          description: Unable to patch the token with the provided data. Some field constraint was violated.
        '403':
          description: You were not authorized to execute this operation.
        '404':
          description: The token does not exist.
      tags:
      - Customer Token
components:
  schemas:
    direct_debit_information:
      type: object
      required:
      - masked_number
      properties:
        masked_number:
          type: string
          example: '**********124'
          description: Masked bank account number
    order:
      type: object
      required:
      - fraud_status
      - order_id
      - redirect_url
      properties:
        authorized_payment_method:
          $ref: '#/components/schemas/authorized_payment_method'
        fraud_status:
          type: string
          description: Fraud status for the order. Either ACCEPTED or PENDING. If ACCEPTED, the order could be captured. If PENDING, please wait till you receive the notification from Klarna in the notification URL that the order has been approved. You can find additional information here.
        order_id:
          type: string
          description: Unique order ID of the transaction. This ID will be used for all order management processes.
        redirect_url:
          type: string
          example: https://credit.klarna.com/v1/sessions/0b1d9815-165e-42e2-8867-35bc03789e00/redirect
          description: URL to redirect the customer to after placing the order. This is a Klarna URL to which the merchant should redirect the customer to. Klarna will place a cookie in the customers browser (if redirected) and redirect the customer back to the confirmation URL provided by the merchant. This is not a mandatory step but a recommended one to improve the returning customers experience. It is a spontaneous step and does not harm the customers experience.
    ErrorV2:
      type: object
      properties:
        authorized_payment_method:
          $ref: '#/components/schemas/authorized_payment_method'
        correlation_id:
          type: string
        error_code:
          type: string
        error_messages:
          type: array
          items:
            type: string
        fraud_status:
          type: string
        reason:
          type: string
    merchant_urls:
      type: object
      required:
      - confirmation
      properties:
        confirmation:
          type: string
          description: URL of merchant confirmation page. (max 2000 characters)
          minLength: 0
          maxLength: 2000
        push:
          type: string
          description: URL that will be requested when an order is completed. Should be different than checkout and confirmation URLs. (max 2000 characters)
          minLength: 0
          maxLength: 2000
    customer_token:
      type: object
      required:
      - payment_method_type
      - status
      properties:
        card:
          $ref: '#/components/schemas/card_information'
        direct_debit:
          $ref: '#/components/schemas/direct_debit_information'
        payment_method_type:
          type: string
          example: INVOICE
          description: Selected payment method
        status:
          type: string
          example: ACTIVE
          description: Status of token, can be active, cancelled, suspended
    card_information:
      type: object
      required:
      - brand
      - expiry_date
      - masked_number
      properties:
        brand:
          type: string
          example: VISA
          description: Card brand
        expiry_date:
          type: string
          example: 12/2020
          description: Card expiration date
        masked_number:
          type: string
          example: '************1234'
          description: Masked credit card number
    order_line:
      type: object
      required:
      - name
      - quantity
      - total_amount
      - unit_price
      properties:
        image_url:
          type: string
          example: https://www.exampleobjects.com/logo.png
          description: "URL to an image that can be later embedded in communications between Klarna and the customer. (max 1024 characters).\n A minimum of 250x250 px resolution is recommended for the image to look good in the Klarna app, and below 50x50 px won't even show. We recommend using a good sized image (650x650 px or more), however the file size must not exceed 12MB."
          minLength: 0
          maxLength: 1024
        merchant_data:
          type: string
          example: '{"customer_account_info":[{"unique_account_identifier":"test@gmail.com","account_registration_date":"2017-02-13T10:49:20Z","account_last_modified":"2019-03-13T11:45:27Z"}]}'
          description: Used for storing merchant's internal order number or other reference. Pass through field. (max 255 characters)
          minLength: 0
          maxLength: 255
        name:
          type: string
          example: Running shoe
          description: Descriptive name of the order line item.
          minLength: 1
          maxLength: 255
        product_identifiers:
          $ref: '#/components/schemas/product_identifiers'
        product_url:
          type: string
          example: https://.../AD6654412.html
          description: URL to the product in the merchants webshop that can be later used in communications between Klarna and the customer. (max 1024 characters)
          minLength: 0
          maxLength: 1024
        quantity:
          type: integer
          format: int64
          example: 1
          description: Quantity of the order line item. Must be a non-negative number.
          minimum: 0
        quantity_unit:
          type: string
          example: pcs
          description: Unit used to describe the quantity, e.g. kg, pcs, etc. If defined the value has to be 1-8 characters.
        reference:
          type: string
          example: AD6654412
          description: Client facing article number, SKU or similar. Max length is 256 characters.
          minLength: 0
          maxLength: 256
        tax_rate:
          type: integer
          format: int64
          example: 1900
          description: Tax rate of the order line. Non-negative value. The percentage value is represented with two implicit decimals. I.e 1900 = 19%.
        total_amount:
          type: integer
          format: int64
          example: 2500
          description: "Total amount of the order line. Must be defined as non-negative minor units. Includes tax and discount. Eg: 2500=25 euros\nValue = (quantity x unit_price) - total_discount_amount. \n(max value: 100000000)"
          maximum: 100000000
        total_discount_amount:
          type: integer
          format: int64
          example: 500
          description: 'Non-negative minor units. Includes tax. Eg: 500=5 euros'
          minimum: 0
        total_tax_amount:
          type: integer
          format: int64
          example: 475
          description: Total tax amount of the order line. Must be within �1 of total_amount - total_amount 10000 / (10000 + tax_rate). Negative when type is discount.
        type:
          type: string
          enum:
          - physical
          - discount
          - shipping_fee
          - sales_tax
          - digital
          - gift_card
          - store_credit
          - surcharge
          example: physical
          description: Type of the order line item.
        unit_price:
          type: integer
          format: int64
          example: 2500
          description: 'Price for a single unit of the order line. Non-negative minor units. Includes tax, excludes discount. (max value: 100000000)'
          maximum: 100000000
        subscription:
          $ref: '#/components/schemas/subscription'
    subscription:
      type: object
      required:
      - name
      - interval
      - interval_count
      properties:
        name:
          description: The name of the subscription product
          type: string
        interval:
          description: The cadence unit for this.
          type: string
          enum:
          - DAY
          - WEEK
          - MONTH
          - YEAR
        interval_count:
          description: The number of intervals
          type: integer
          minimum: 1
    attachment:
      type: object
      required:
      - body
      - content_type
      properties:
        body:
          type: string
          example: '{"customer_account_info":[{"unique_account_identifier":"test@gmail.com","account_registration_date":"2017-02-13T10:49:20Z","account_last_modified":"2019-03-13T11:45:27Z"}]}'
          description: The content of the extra merchant data 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 serialized 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"
    customer_token_status_update_request:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          example: CANCELLED
          description: The token status to update to.
          enum:
          - CANCELLED
    address:
      type: object
      properties:
        attention:
          type: string
          example: Attn
          description: Attn. - optional parameter.
          minLength: 0
          maxLength: 99
        city:
          type: string
          example: London
          description: Customers city.
          minLength: 0
          maxLength: 99
        country:
          type: string
          example: GB
          description: Customers country. This value overrides the purchase country if they are different. Should follow the standard of ISO 3166 alpha-2. E.g. GB, US, DE, SE.
          pattern: ^[A-Za-z]{2,2}$
        email:
          type: string
          example: test.sam@test.com
          description: Customers email address.
          minLength: 0
          maxLength: 99
        family_name:
          type: string
          example: Andersson
          description: Customers family name.
          minLength: 0
          maxLength: 99
        given_name:
          type: string
          example: Adam
          description: Customers first name.
          minLength: 0
          maxLength: 99
        organization_name:
          type: string
          description: Organization name (if applicable). Only applicable for B2B customers.
          minLength: 0
          maxLength: 99
        phone:
          type: string
          example: '+44795465131'
          description: Phone number. Preferably a mobile phone number.
          minLength: 5
          maxLength: 99
        postal_code:
          type: string
          example: W1G 0PW
          description: 'Customers postal code. Validation according to [Universal Postal Union addressing system](https://www.upu.int/en/activities/addressing/postal-addressing-systems-in-member-countries.html)

            E.g. 12345, W1G OPW.'
          minLength: 0
          maxLength: 10
        region:
          type: string
          example: OH
          description: Customers region or state - Mandatory for US and AU market. Validations according to ISO 3166-2 format, e.g. OH, NJ, etc.
          minLength: 0
          maxLength: 99
        street_address:
          type: string
          example: 33 Cavendish Square
          description: 'Customers street address.Validation according to [Universal Postal Union addressing system](https://www.upu.int/en/activities/addressing/postal-addressing-systems-in-member-countries.html). Regional formatting is required, as follows:

            UK/US/FR: 33 Cavendish Square

            Rest of EU: De Ruijterkade 7'
          minLength: 0
          maxLength: 99
        street_address2:
          type: string
          example: Floor 22 / Flat 2
          description: 'Customers street address. Second Line. '
          minLength: 0
          maxLength: 99
        title:
          type: string
          example: Mr.
          description: "Customers Title. Allowed values per country:\nUK - \"Mr\", \"Ms\"\nDE - \"Herr\", \"Frau\"\nAT: \"Herr, \"Frau\"\nCH: de-CH: \"Herr, \"Frau\" it-CH: \"Sig.\", \"Sig.ra\" fr-CH: \"M\", \"Mme\" \nBE: \"Dhr.\", \"Mevr.\"\nNL: \"Dhr.\", \"Mevr.\""
          minLength: 0
          maxLength: 20
    authorized_payment_method:
      type: object
      required:
      - type
      properties:
        number_of_days:
          type: integer
          format: int32
        number_of_installments:
          type: integer
          format: int32
        type:
          type: string
          enum:
          - invoice
          - fixed_amount
          - pix
          - base_account
          - deferred_interest
          - direct_debit
          - direct_bank_transfer
          - b2b_invoice
          - card
          - slice_it_by_card
          - pay_later_by_card
          - fixed_sum_credit
          - pay_by_card
    customer_token_order:
      type: object
      required:
      - order_amount
      - order_lines
      - order_tax_amount
      - purchase_currency
      properties:
        attachment:
          $ref: '#/components/schemas/attachment'
        auto_capture:
          type: boolean
          description: Allow merchant to trigger auto capturing.
          default: false
        merchant_data:
          type: string
          example: '{"order_specific":[{"substore":"Women''s Fashion","product_name":"Women Sweatshirt"}]}'
          description: Pass through field (max 6000 characters).
          minLength: 0
          maxLength: 6000
        merchant_reference1:
          type: string
          example: ON4711
          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).
          minLength: 0
          maxLength: 255
        merchant_reference2:
          type: string
          example: ON4711
          description: Used for storing merchant's internal order number or other reference (max 255 characters).
          minLength: 0
          maxLength: 255
        merchant_urls:
          $ref: '#/components/schemas/merchant_urls'
        order_amount:
          type: integer
          format: int64
          description: Non-negative, minor units. Total amount of the order, including tax and any discounts.
          minimum: 1
        order_lines:
          type: array
          description: The applicable order lines (max 1000)
          items:
            $ref: '#/components/schemas/order_line'
          maxItems: 1000
          minItems: 1
        order_tax_amount:
          type: integer
          format: int64
          description: Non-negative, minor units. The total tax amount of the order.
          minimum: 0
        purchase_currency:
          type: string
          example: GBP
          description: ISO 4217 purchase currency.
          pattern: ^[A-Za-z]{3,3}$
        shipping_address:
          $ref: '#/components/schemas/address'
        usage:
          type: string
          readOnly: true
    product_identifiers:
      type: object
      properties:
        brand:
          type: string
          example: shoe-brand
          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
        category_path:
          type: string
          example: Shoes > Running
          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 ' > '
          minLength: 0
          maxLength: 750
        global_trade_item_number:
          type: string
          example: '4912345678904'
          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: AD6654412-334.22
          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
        color:
          type: string
          example: white
          description: Color to be shown to the end customer (max 64 characters).
          minLength: 0
          maxLength: 64
        size:
          type: string
          example: small
          description: Size to be shown to the end customer (max 64 characters).
          minLength: 0
          maxLength: 64