openapi: 3.0.0
info:
  description: >-
    The Customer Token API is used to charge customers with a tokenized payment
    method and can be used for recurring purchases, subscriptions and for
    storing a customer's payment method. Tokens are created using the [`generate
    a customer token`](https://docs.klarna.com/api/payments/) call in the
    payments API.


    Read more on [Klarna payments](https://docs.klarna.com/klarna-payments/).
  version: 1.0.0
  title: Payments API V1
paths:
  /customer-token/v1/tokens/{customerToken}:
    get:
      summary: Get customer token
      description: >-
        Use this API request to retrieve the content of a Kustom 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](https://docs.klarna.com/klarna-payments/other-actions/check-the-details-of-a-customer-token/)**.
      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.
  /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 Kustom 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](https://docs.klarna.com/klarna-payments/integrate-with-klarna-payments/step-3-create-an-order/set-up-a-recurring-payment-order/#create-an-order-with-a-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.
  /customer-token/v1/tokens/{customerToken}/status:
    patch:
      summary: Update customer token status
      description: >-
        Use this API call to update the status of a Kustom 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](https://docs.klarna.com/klarna-payments/other-actions/cancel-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.
servers:
  - url: https://api.kustom.co
components:
  schemas:
    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
    address:
      type: object
      properties:
        attention:
          type: string
          example: Attn
          description: ‘Attn.’ - optional parameter.
          minLength: 0
          maxLength: 99
        city:
          type: string
          example: London
          description: Customer’s city.
          minLength: 0
          maxLength: 99
        country:
          type: string
          example: GB
          description: >-
            Customer’s 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: Customer’s email address.
          minLength: 0
          maxLength: 99
        family_name:
          type: string
          example: Andersson
          description: Customer’s family name.
          minLength: 0
          maxLength: 99
        given_name:
          type: string
          example: Adam
          description: Customer’s 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: >-
            Customer’s 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: >-
            Customer’s 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: >-
            Customer’s 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: 'Customer’s street address. Second Line. '
          minLength: 0
          maxLength: 99
        title:
          type: string
          example: Mr.
          description: |-
            Customer’s Title. Allowed values per country:
            UK - "Mr", "Ms"
            DE - "Herr", "Frau"
            AT: "Herr, "Frau"
            CH: de-CH: "Herr, "Frau" it-CH: "Sig.", "Sig.ra" fr-CH: "M", "Mme" 
            BE: "Dhr.", "Mevr."
            NL: "Dhr.", "Mevr."
          minLength: 0
          maxLength: 20
    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"
    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
    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
    customer_token_order:
      type: object
      required:
        - order_amount
        - order_lines
        - 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
    customer_token_status_update_request:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          example: CANCELLED
          description: The token status to update to.
          enum:
            - CANCELLED
    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
    direct_debit_information:
      type: object
      required:
        - masked_number
      properties:
        masked_number:
          type: string
          example: '**********124'
          description: Masked bank account number
    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
    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 Kustom in the notification URL that
            the order has been approved. You can find additional information
            [here](https://docs.klarna.com/payments/after-payments/order-management/more-actions/pending-orders/).
        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
            Kustom URL to which the merchant should redirect the customer to.
            Kustom will place a cookie in the customer’s 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 customer’s experience. It is a spontaneous
            step and does not harm the customer’s experience.
    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
            Kustom and the customer. (max 1024 characters).
             A minimum of 250x250 px resolution is recommended for the image to look good in the Kustom 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 merchant’s webshop that can be later used
            in communications between Kustom 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

            Value = (quantity x unit_price) - total_discount_amount. 

            (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'
    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
    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
