Qliro Payment Widget API

openapi: 3.2.0
info:
  title: Qliro.Payments.MerchantApi Payment Widget API
  version: v1
servers:
- url: https://pago.qit.nu/checkout/merchantapi
tags:
- name: PaymentWidget
paths:
  /PaymentWidget/orders:
    post:
      tags:
      - PaymentWidget
      summary: Creates new widget order
      description: When the merchant wants to use a payment widget, the order is created on Qliro end through this request
      operationId: createPaymentWidgetOrder
      requestBody:
        x-name: createPaymentWidgetOrderRequest
        description: Order details to be created
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentWidgetOrderRequest'
        required: true
        x-position: 1
      responses:
        '201':
          description: Contains the order id for the newly created payment widget order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
        '400':
          description: See ErrorCode and DetailedErrorMessage more details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
  /PaymentWidget/orders/{id}:
    get:
      tags:
      - PaymentWidget
      summary: Gets an existing payment widget order
      description: Once an order is created, the merchant will receive the corresponding OrderId the response. The OrderId returned by createOrder operation can be used to get the order information
      operationId: getPaymentWidgetOrder
      parameters:
      - name: id
        in: path
        required: true
        description: Order id to get order by
        schema:
          type: integer
          format: int64
        x-position: 1
      responses:
        '200':
          description: Information about the order, together with more information to be able to intialize the widget front end api. If the CustomerCheckoutStatus is Completed or OnHold, there will be a non-empty list of OrderItems
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymentWidgetOrderResponse'
        '400':
          description: 'Possible reasons: arguments cannot be null, invalid input, invalid order id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
        '404':
          description: Order not found
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '500':
          description: System error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseModel'
components:
  schemas:
    MetadataContainer:
      type: object
      additionalProperties: false
      properties:
        HasRisk:
          type:
          - boolean
          - 'null'
          description: If true, order item considered as risk item. Default is false.
          example: true
        Subscription:
          description: It indicates that order item is a subscription if Enabled is true.
          oneOf:
          - $ref: '#/components/schemas/Subscription'
        TravelInformation:
          oneOf:
          - $ref: '#/components/schemas/TravelInformation'
        Ingrid:
          oneOf:
          - $ref: '#/components/schemas/Ingrid'
        MerchantData:
          type:
          - string
          - 'null'
          maxLength: 250
    InitDataContainer:
      type: object
      additionalProperties: false
      properties:
        AuthenticationHeader:
          type:
          - string
          - 'null'
        OrderId:
          type: integer
          format: int64
        WebApiUrl:
          type:
          - string
          - 'null'
        WebAppUrl:
          type:
          - string
          - 'null'
        Language:
          type:
          - string
          - 'null'
    CreateOrderResponse:
      type: object
      additionalProperties: false
      properties:
        OrderId:
          type: integer
          format: int64
          example: 12345
        PaymentLink:
          type:
          - string
          - 'null'
    Gender:
      type: integer
      description: ''
      x-enumNames:
      - Unknown
      - Female
      - Male
      enum:
      - 0
      - 1
      - 2
    GetPaymentWidgetOrderResponse:
      type: object
      additionalProperties: false
      properties:
        OrderId:
          type: integer
          description: Qliro Checkout order id.
          format: int64
          example: 12345
        MerchantReference:
          type:
          - string
          - 'null'
          description: A string generated by the merchant to identify the order uniquely in their system. Maximum length is 25 characters.
          example: MerchantUniqueReference
        TotalPrice:
          type: number
          format: decimal
          example: 1576.65
        Currency:
          type:
          - string
          - 'null'
          example: SEK
        Country:
          type:
          - string
          - 'null'
          example: SE
        Language:
          type:
          - string
          - 'null'
          example: sv-se
        CustomerCheckoutStatus:
          type:
          - string
          - 'null'
          example: Success
        Customer:
          oneOf:
          - $ref: '#/components/schemas/Customer'
        BillingAddress:
          oneOf:
          - $ref: '#/components/schemas/Address2'
        ShippingAddress:
          oneOf:
          - $ref: '#/components/schemas/Address2'
        OrderItems:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/OrderItem2'
        PaymentMethod:
          oneOf:
          - $ref: '#/components/schemas/PaymentMethod'
        BootstrapUrl:
          type:
          - string
          - 'null'
        Widgets:
          type:
          - array
          - 'null'
          items:
            type: object
            additionalProperties:
              type: string
        InitData:
          oneOf:
          - $ref: '#/components/schemas/InitDataContainer'
    PaymentMethodFee:
      type: object
      additionalProperties: false
      required:
      - Type
      - MerchantReference
      - AmountIncludingVat
      - AmountExcludingVat
      properties:
        Type:
          type: string
          description: The type of Fee
          minLength: 1
          example: InvoiceFee
        MerchantReference:
          type: string
          description: A string generated by the merchant to identify the Fee.
          minLength: 1
          pattern: ^[\p{L}\s(.)'\-_&,\/–+0-9:]{1,200}$
          example: MerchantReference
        AmountIncludingVat:
          type: number
          description: The price per item excluding Value Added Tax. This can be specified with 0, 1 or 2 decimals, e.g. 99, 99.9 or 99.99.
          format: decimal
          example: 100
        AmountExcludingVat:
          type: number
          description: The price per item including Value Added Tax. This can be specified with 0, 1 or 2 decimals, e.g. 99, 99.9 or 99.99.
          format: decimal
          example: 80
        Description:
          type:
          - string
          - 'null'
          description: User friendly description of the fee
          maxLength: 4000
          example: invoice fee
    JuridicalType:
      type: integer
      description: ''
      x-enumNames:
      - Physical
      - Company
      enum:
      - 0
      - 1
    Metadata:
      type: object
      additionalProperties: false
      properties:
        ShippingMethodMerchantReference:
          type:
          - string
          - 'null'
          example: UniqueMerchantReference
        ShippingMethodSecondaryOptionMerchantReference:
          type:
          - string
          - 'null'
          example: UniqueMerchantReference
        ShippingMethodAccessCode:
          type:
          - string
          - 'null'
          example: ACCESS_CODE
        AdditionalShippingProperties:
          oneOf:
          - $ref: '#/components/schemas/AdditionalShippingPropertiesData'
        MerchantData:
          type:
          - string
          - 'null'
    Traveler:
      type: object
      additionalProperties: false
      properties:
        FirstName:
          type:
          - string
          - 'null'
        LastName:
          type:
          - string
          - 'null'
        IsMainTraveller:
          type: boolean
        Gender:
          $ref: '#/components/schemas/Gender'
        DateOfBirth:
          type: string
          format: date-time
    Address2:
      type: object
      additionalProperties: false
      properties:
        FirstName:
          type:
          - string
          - 'null'
          example: First
        LastName:
          type:
          - string
          - 'null'
          example: Last
        CompanyName:
          type:
          - string
          - 'null'
          example: null
        CareOf:
          type:
          - string
          - 'null'
        Street:
          type:
          - string
          - 'null'
          example: Street
        Street2:
          type:
          - string
          - 'null'
          example: Street2
        PostalCode:
          type:
          - string
          - 'null'
          example: 12345
        City:
          type:
          - string
          - 'null'
          example: City
        CountryCode:
          type:
          - string
          - 'null'
          example: SE
        Area:
          type:
          - string
          - 'null'
          example: Area
        AreaCode:
          type:
          - string
          - 'null'
          description: Currently only used for US. Will contain the ISO-3166-2 code for the current state (Area)
          example: US-CA
    OrderItem:
      type: object
      additionalProperties: false
      required:
      - MerchantReference
      - Quantity
      - PricePerItemIncVat
      properties:
        MerchantReference:
          type: string
          description: A string generated by the merchant to identify the order item. The combination of MerchantReference and Price Per Item Including Vat is used to uniquely identify the order item. Maximum length is 200 characters.
          minLength: 1
          pattern: ^[\p{L}\s(.)'\-_&,\/–+0-9:]{1,200}$
          example: RedHat
        Description:
          type:
          - string
          - 'null'
          description: A name or description of the order item.
          maxLength: 4000
          example: Red hat original product
        Type:
          type:
          - string
          - 'null'
          description: Can be 'Product', 'Discount', 'Fee' or 'Shipping'
          example: Product
        Quantity:
          type: integer
          description: The number of these items in the cart.
          format: int32
          maximum: 2147483647
          minimum: 1
          example: 3
        PricePerItemIncVat:
          type: number
          description: The price per item including Value Added Tax. This can be specified with 0, 1 or 2 decimals, e.g. 99, 99.9 or 99.99.
          format: decimal
          example: 375.55
        PricePerItemExVat:
          type: number
          description: The price per item excluding Value Added Tax. This can be specified with 0, 1 or 2 decimals, e.g. 99, 99.9 or 99.99.
          format: decimal
          example: 300.35
        Metadata:
          description: Only available in create order and update order requests. Can be used to indicate if an item includes some kind of risk. If an item has been flagged with the property HasRisk, then depending on the merchant setup in Qliro Checkout, some payment methods will be disabled. This behavior is customizable in the merchant preferences. It can also be used to indicate that an order item is a subscription. If it is indicated as a subscription Qliro Checkout will show some additional terms for Qliro invoice if Qliro invoice is enabled for the merchant.
          oneOf:
          - $ref: '#/components/schemas/MetadataContainer'
    Ingrid:
      type: object
      additionalProperties: false
      properties:
        Weight:
          type:
          - integer
          - 'null'
          format: int32
        Sku:
          type:
          - string
          - 'null'
        ShippingDate:
          oneOf:
          - $ref: '#/components/schemas/ShippingDateRange'
        Attributes:
          type:
          - array
          - 'null'
          items:
            type: string
        Dimensions:
          oneOf:
          - $ref: '#/components/schemas/ItemDimensions'
        OutOfStock:
          type:
          - boolean
          - 'null'
        Discount:
          type:
          - number
          - 'null'
          format: decimal
    CreatePaymentWidgetOrderRequest:
      allOf:
      - $ref: '#/components/schemas/RequestBase'
      - type: object
        additionalProperties: false
        required:
        - MerchantReference
        - Currency
        - Country
        - Language
        - OrderItems
        properties:
          MerchantReference:
            type: string
            description: A string generated by the merchant to identify the order uniquely in their system. Maximum length is 25 characters.
            minLength: 1
            pattern: ^[A-Za-z0-9_-]{1,25}$
            example: MerchantUniqueReference
          Currency:
            type: string
            description: Three uppercase characters, in accordance with ISO 4217.
            minLength: 1
            example: SEK
          Country:
            type: string
            description: Two upper case characters. In accordance with ISO 3166-1.
            minLength: 1
            example: SE
          Language:
            type: string
            description: Locale indicative for language & other location-specific details.
            minLength: 1
            example: sv-se
          MerchantOrderValidationUrl:
            type:
            - string
            - 'null'
            description: If specified, Qliro will use this URL to try to validate the order before completing the purchase. Info about authentication for this request can be found below. Should use https.
            example: https://merchant.com/orderValidation/
          MerchantOrderManagementStatusPushUrl:
            type:
            - string
            - 'null'
            description: Qliro will use this URL to send notifications on payment status changes during the order management process, for example when the payment created by MarkItemsAsShipped call becomes successful. Info about authentication for this request can be found below. Should use https.
            example: https://ordermanagement.merchant.com/checkoutstatus
          MerchantCheckoutStatusPushUrl:
            type:
            - string
            - 'null'
            description: Qliro will use this URL to send customer checkout status updates. For example when the checkout status switches from OnHold to Completed. Info about authentication for this request can be found below. Should use https.
            example: https://ordermanagement.merchant.com/checkoutstatus
          OrderItems:
            type: array
            description: 'List of items customer added to the cart. '
            items:
              $ref: '#/components/schemas/OrderItem'
          RequireIdentityVerification:
            type:
            - boolean
            - 'null'
          ApplicableFees:
            oneOf:
            - $ref: '#/components/schemas/ApplicableFeeContainer'
    ApplicableFeeContainer:
      type: object
      additionalProperties: false
      properties:
        Fees:
          type:
          - object
          - 'null'
          description: A Dictionary of string and Array of Fees, the key should be the name of a PaymentMethod for which the Array of Fees is applicable
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/PaymentMethodFee'
    ErrorResponseModel:
      type: object
      additionalProperties: false
      properties:
        ErrorCode:
          type:
          - string
          - 'null'
          description: Unique error code
          example: ORDER_NOT_FOUND
        DetailedErrorMessage:
          type:
          - string
          - 'null'
          description: Detailed error message
          example: Order not found
        ErrorReference:
          type: string
          description: A tracking ID from Qliro Checkout
          format: guid
          example: d7da92f4-1ad9-48c3-9cd3-26559c98e64c
    Customer:
      type: object
      additionalProperties: false
      properties:
        FirstName:
          type:
          - string
          - 'null'
          example: FirstName
        LastName:
          type:
          - string
          - 'null'
          example: LastName
        PersonalNumber:
          type:
          - string
          - 'null'
          example: 111111-1111
        VatNumber:
          type:
          - string
          - 'null'
          example: SE111111111101
        Email:
          type:
          - string
          - 'null'
          example: email@domain.com
        MobileNumber:
          type:
          - string
          - 'null'
          example: '+46101010101'
        JuridicalType:
          example: Physical
          oneOf:
          - $ref: '#/components/schemas/JuridicalType'
        DateOfBirth:
          type:
          - string
          - 'null'
          format: date-time
          example: '1990-01-01'
        Gender:
          example: Male
          oneOf:
          - $ref: '#/components/schemas/Gender'
    ItemDimensions:
      type: object
      additionalProperties: false
      properties:
        Height:
          type:
          - integer
          - 'null'
          format: int32
        Length:
          type:
          - integer
          - 'null'
          format: int32
        Width:
          type:
          - integer
          - 'null'
          format: int32
    TravelInformation:
      type: object
      additionalProperties: false
      properties:
        DepartureCountry:
          type:
          - string
          - 'null'
        DepartureCity:
          type:
          - string
          - 'null'
        DepartureIATACode:
          type:
          - string
          - 'null'
        ArrivalCountry:
          type:
          - string
          - 'null'
        ArrivalCity:
          type:
          - string
          - 'null'
        ArrivalIATACode:
          type:
          - string
          - 'null'
        StopOverCountry:
          type:
          - string
          - 'null'
        StopOverCity:
          type:
          - string
          - 'null'
        StopOverIATACode:
          type:
          - string
          - 'null'
        TravelType:
          type:
          - string
          - 'null'
        BookingDate:
          type: string
          format: date-time
        DepartureDate:
          type: string
          format: date-time
        ReturnDate:
          type: string
          format: date-time
        DaysToDeparture:
          type: integer
          format: int32
        NoOfPassengers:
          type: integer
          format: int32
        Travelers:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Traveler'
        Class:
          type:
          - string
          - 'null'
        Airline:
          type:
          - string
          - 'null'
        NoOfLuggage:
          type: integer
          format: int32
    OrderItem2:
      type: object
      additionalProperties: false
      properties:
        MerchantReference:
          type:
          - string
          - 'null'
          example: MerchantUniqueReference
        Description:
          type:
          - string
          - 'null'
          example: Original product
        Quantity:
          type: integer
          format: int32
          example: 5
        PricePerItemIncVat:
          type: number
          format: decimal
          example: 10
        PricePerItemExVat:
          type: number
          format: decimal
          example: 8
        Type:
          example: Product
          oneOf:
          - $ref: '#/components/schemas/OrderItemType'
        Metadata:
          oneOf:
          - $ref: '#/components/schemas/Metadata'
        PaymentTransactionId:
          type: integer
          format: int64
          example: 123456
    ShippingDateRange:
      type: object
      additionalProperties: false
      properties:
        Start:
          type:
          - string
          - 'null'
          format: date-time
        End:
          type:
          - string
          - 'null'
          format: date-time
    AgentData:
      type: object
      additionalProperties: false
      properties:
        Id:
          type:
          - string
          - 'null'
        Name:
          type:
          - string
          - 'null'
        MapLongitude:
          type:
          - number
          - 'null'
          format: double
        MapLatitude:
          type:
          - number
          - 'null'
          format: double
        Address1:
          type:
          - string
          - 'null'
        Address2:
          type:
          - string
          - 'null'
        ZipCode:
          type:
          - string
          - 'null'
        City:
          type:
          - string
          - 'null'
    OrderItemType:
      type: integer
      description: ''
      x-enumNames:
      - Product
      - Discount
      - Fee
      - Shipping
      enum:
      - 0
      - 1
      - 2
      - 3
    PaymentMethod:
      type: object
      additionalProperties: false
      properties:
        PaymentMethodName:
          type:
          - string
          - 'null'
          example: PaymentMethodName
        PaymentTypeCode:
          type:
          - string
          - 'null'
          example: PaymentTypeCode
    RequestBase:
      type: object
      x-abstract: true
      additionalProperties: false
      required:
      - MerchantApiKey
      properties:
        MerchantApiKey:
          type: string
          description: Will be provided by Qliro Checkout when setting up merchant account
          maxLength: 50
          minLength: 0
          example: MerchantApiKey
    Subscription:
      type: object
      additionalProperties: false
      properties:
        Enabled:
          type: boolean
    AdditionalShippingPropertiesData:
      type: object
      additionalProperties: false
      properties:
        ShippingProvider:
          type:
          - string
          - 'null'
        ServiceId:
          type:
          - string
          - 'null'
        Agent:
          oneOf:
          - $ref: '#/components/schemas/AgentData'
x-generator: NSwag v14.0.3.0 (NJsonSchema v11.0.0.0 (Newtonsoft.Json v13.0.0.0))