Qliro payment

  • Litium 8

Qliro payment app can be used to integration with Qliro to handle payments in your e-commerce solution.

When using Qliro payment app in local development the app need to use a public accessible domain that are secured with https, otherwise requests to Qliro may fail.

Version dependencies

  • Qliro Payment app 1.0.0
    • Supports cancellation and refund of orders
    • Supports order validation
    • Requires Litium 8.10.0 or later
  • Qliro payment app 1.3.0
    • Supports recurring paymets
    • Supports Ingrid integration
    • Requires Litium 8.18 or later

Installation

Litium serverless cloud - Use the Cloud CLI to install the app.

Litium legacy cloud - Contact support to install the app in your test and/or production environment.

Local environment - See details below. 

Docker template for local installation

Values to replace in the template:

  • ports
  • environment
    • ASPNETCORE_HTTPS_PORT
    • AppMetadata__AppUrl
    • LitiumApi__ApiUrl
version: '3'
services:
  qliro-payment:
    image: registry.litium.cloud/apps/qliro-payment:1.3.1
    dns: 
    - 192.168.65.254
    restart: unless-stopped
    ports:
    - "10070:80"
    - "10071:443"
    environment:
    # Enable HTTPS binding
    - ASPNETCORE_URLS=https://+;http://+
    - ASPNETCORE_HTTPS_PORT=10071
    # Configuration for HTTPS inside the container, exported dotnet dev-certs with corresponding password
    - ASPNETCORE_Kestrel__Certificates__Default__Password=${CERT_PWD}
    - ASPNETCORE_Kestrel__Certificates__Default__Path=/https/localhost.pfx
    # Folder for the configuraiton, this is volume-mapped
    - CONFIG_PATH=/app_config
    # Folder where logfiles should be placed, this is volume-mapped
    - APP_LOG_PATH=/logs
    # Don't validate certificates
    - AppConfiguration__ValidateCertificate=false
    # Url to this app
    - AppMetadata__AppUrl=https://customer-app-qliro-payment.localtest.me:10071
    # Url to the litium installation
    - LitiumApi__ApiUrl=https://customer.localtest.me:5001
    volumes:
    - ./data/qliro-payment/config:/app_config
    - ./data/qliro-payment/data:/app_data
    - ./data/qliro-payment/logs:/logs
    - ./data/qliro-payment/DataProtection-Keys:/root/.aspnet/DataProtection-Keys
    - ./data/https:/https:ro

App configuration file

The configuration file must have json format and UTF-8 encoding

{
  "Qliro": {
    "PaymentAccounts": [
      {
        "PaymentAccountId": "SE",
        "MerchantApiKey": "",
        "MerchantApiSecret": "",
        "Environment": "Test",
        "PaymentOptions": [ "One" ],
        "UISettings": {
          "CallToActionHoverColor": "#FF0000",
          "CallToActionColor": "#FFFF00",
          "BackgroundColor": "#FF0000",
          "PrimaryColor": "#FFFF00",
          "CornerRadius": 30,
          "ButtonCornerRadius": 25
        },
        "EnableShippingMethods": true,
        "AvailableShippingMethodsBackendUrl": "https://example.com/ShippingMethods",
        "AvailableShippingAdressesBackendUrl": "https://example.com/ShippingAddresses"
      },
      {
        "PaymentAccountId": "DK",
        "MerchantApiKey": "",
        "MerchantApiSecret": "",
        "Environment": "Test",
        "PaymentOptions": [ "One" ]
      }
    ]
  }
}
  • PaymentAccountId: Identifier to select the account. It must be a unique string.
  • MerchantApiKey: Qliro api key for the merchant account. This value is assigned by Qliro.
  • MerchantApiSecret: Qliro api password. This value is assigned by Qliro.
  • Environment: Qliro environment. It should be "Test" or "Live".
  • PaymentOptions: It must be "One".
  • UISettings (optional): These fields are used to customize the UI of the Qliro checkout iframe.
  • EnableShippingAddress (optional): Enable the callbacks for getting shipping addresses from Litium
  • EnableShippingMethods (optional): Enable the callbacks for getting shipping methods from Litium
  • AvailableShippingMethodsBackendUrl (optional): Defines the endpoint for the MerchantOrderAvailableShippingMetthods callback from Qliro. More information below.
  • AvailableShippingAdressesBackendUrl (optional): Defines the endpoint for the MerchantOrderAvailableShippingAddresses callback. More information below.

Integrated shipping

The Qliro checkout iframe can load available shipping methods and/or shipping addresses from Litium. The URLs to the respective endpoints is defined in the app configuration. You would then need to build the actual endpoints to return the correct data in your Litium solution.

More information about what data Qliro will send in the callback, as well as which data it expects in the response can be found in the Qliro documentation about the Update Shipping Methods and Update Shipping Addresses notifications. Request to the provided endpoints contains the cartContextSystemId query string parameter with the identifier for the cart context for the current request, use the extension method HttpContext.SwitchCartContextAsync to use the cart context based on the identifier.

Ingrid integration

Qliro supports displaying shipping options from ingrid inside Qliro checkout iframe.

You need to contact Qliro merchant support to enable Ingrid for your account.

Additional configuration in Litium:

  1. Configure the Direct Shipment app to provide a shipping option with integration type set to PaymentCheckout.

  2. Add this shipping option to channels where you want to use Ingrid. Additional shipping options configured on the channel will be sent to Qliro to be used as fallback options if the connection between Qliro and Ingrid fails.

Note: The fee for the integrated shipping option should be set to 0 in Litium.

Note: The AvailableShippingMethodsBackendUrl and AvailableShippingAdressesBackendUrl endpoints can not be used together with Ingrid integration. These configuration parameters should be set to null.

The field mappings for shipping data (height, width, length, weight and tags) in Litium backoffice will be used by the Qliro app to provide information to Ingrid.

Note: Qliro will add the fee for shipping option from Ingrid to the order when the payment is confirmed. This means that Litium will not be able to calculate any free shipping discounts for these shipping options.

When an order is placed, Litium will save the Ingrid Checkout Session ID received from Qliro as additional info on the shipping info of the order. This Session ID can be used to retrieve information about the selected shipping option from Ingrid's API. The Merchant Notification callback from Qliro is not supported by the app.

Upsell

Qliro's Upsell feature enables the merchant to offer the customer the ability to add additional items to an already confirmed order. This is commonly implemented on the order confirmation page. More information are available in Qliro documentation. To use this feature you need to implement additional logic in the Litium solution.

To enable Upsell, you need to manually create a additional authorization transaction that contains the products that the customer want to add. This transaction needs to have a key in the additionalData dictionary with the key "Upsell" set to "true"

When Qliro payment app receives the notification back for the request the app will forward the result into the payments authorization update endpoint in Litium with the status of how the upsell was applied or not.

Please note that Litium does not currently support more than one authorization transaction when doing payment operations like capture and refund. For orders with Upsell you would need to implement this yourself.

Recurring Payments / Payment token

Qliro supports saving a payment token and using that token to make payments for subsequent orders.

You need to contact Qliro cutomer service to enable the Qliro recurring payments / subscriptions feature for your account.

To use a saved Payment token, use the payment method "Payment Token" when creating the order. You need to set the actual payment token, for more information see documentation on Payment Tokens.