Skip to main content

Qliro One

This article will provide the details you need to implement Qliro One using Storefront API.

Plugin Configuration​

Required Data for Qliro Integration:

  • API key for your Qliro store
  • Secret for your Qliro store
  • Valid URLs for the Merchant Integrity Policy and Terms & Conditions
  • Merchant GUID (for links to the Qliro Merchant panel)

Setup Options​

Notifications:​

Notification endpoints for customer checkout status, order management, and order validation are dynamically defined by the plugin. No manual setup in plugin settings is required.

Payment Flow​

After a successful payment, the frontend calls paymentResult, placing the order in Centra with a Waiting for Payment flag and HOLD status. These remain until a CustomerCheckoutStatus notification with status="Completed" confirms the payment from Qliro.

  • Debit/Credit Card Payments: The flag and status usually clear within minutes.
  • Other Payment Types (e.g., INVOICE): The flag may persist longer as confirmation can take more time.

Require Success Validation​

An optional order validation step triggers when the customer submits the order in the payment widget. It checks:

  • Customer identity (if using "Verify identity with BankID" in Sweden).
  • Juridical type (ensures the selected type is allowed by configuration).
  • Item availability.

Handling Payment Declines​

The result can be managed on the frontend by implementing the onPaymentDeclined() callback, which accepts the decline reason as an argument. Refer to the Qliro documentation for details.

Allow Organizations to Place Orders​

Enable "Company", in the plugin, to allow businesses to place orders via Qliro One.

Ask for Newsletter Signup​

Enable the "newsletter signup" checkbox to display it in the Qliro One widget. You can choose whether it is pre-checked.

Age Restriction​

The age restriction setting enables the minimumCustomerAge parameter during payment session initialization. Setting it to "Yes" adds an "Age limit" attribute at the product level (visible in Catalog/Attributes setup). If a product with an age restriction is in the basket, the minimumCustomerAge value is sent to Qliro.

High Fraud Risk Flag: "HasRisk"​

The "HasRisk" flag limits available payment methods in Qliro checkout for products prone to fraudulent purchases. Configurable as a boolean value at the product level in Centra, it is sent to Qliro when a risky product is added to the cart. Removing the product restores all payment methods.

Enable the "HasRisk" feature in Qliro payment plugin settings to add a custom attribute on the product configuration page for marking products as risky.

Verify Identity with BankID - Sweden Only​

Set to "Yes" to require BankID for customers to complete their purchase.

Customer Information​

The payment widget can be prefilled with customer data from:

  • Basket shipping address
  • Basket billing address
  • Customer address

You can choose whether the address entered in the payment widget should be used for the order.

Set "Use customer addresses from Qliro One" to "No" to ignore the address from the payment widget, useful if customer info is collected in a separate form before payment.

Configuration allows locking customer information in the payment widget (partially or fully) to prevent changes during checkout initialization.

Geo-Restrictions​

You can restrict the plugin by pricelist, market, or country at the bottom of the setup.

Customization of Qliro One Widget​

Customize the Qliro One widget by setting colors for:

  • Background color
  • Primary color
  • Call To Action button
  • Call To Action hovered button

You can also configure corner radius for:

  • General corner radius
  • Button corner radius

Implementation​

When configured, Qliro One will show up in the data received from selection query:

// selection.checkout.paymentMethods
{
  "id": 3,
  "name": "Qliro One",
  "kind": "QLIRO",
  "initiateOnlySupported": false,
  "recurringSupported": false,
  "handlingCost": {
    "formattedValue": "0.00 SEK",
    "value": 0
  },
  "addressAfterPayment": true
}

Qliro Payment Method Selection​

When Qliro is selected as the payment method, a call to paymentInstructions initializes the payment session. If the request fails, details are available in Centra’s debug log.

mutation paymentInstructions($input: PaymentInstructionsInput) {
  paymentInstructions(input: $input) {
    userErrors {
      path
      message
    }
    action {
      action
      ... on FormPaymentAction {
        html
        formFields
        formType
      }
      ... on JavascriptPaymentAction {
        formFields
        formType
        script
      }
      ... on RedirectPaymentAction {
        url
      }
      ... on SuccessPaymentAction {
        order {
          number
        }
      }
    }
    selection {
      ...SelectionFields
      checkout {
        ...AdditionalCheckoutFields
      }
    }
  }
}

A successful initialization returns the following response:

{
  "data": {
    "paymentInstructions": {
      "action": {
        "action": "FORM",
        "html": "...",
        "formType": "qliro"
      },
      "selection": {
        "id": "...",
        "checkout": {
          // ...otherFields
        }
      },
      "userErrors": []
    }
  }
}

Rendering the Payment Widget​

  1. Insert and evaluate the action.html into the DOM (see payment flows)
  2. Once the shopper has completed the purchase within the widget they will be directed to the paymentReturnPage specified in the paymentInstructions input.
  3. Verify the payment using paymentResult (see payment flows)
  4. Centra verifies the payment towards Qliro and returns the order if the payment was successful or an error if it wasn’t.

CheckoutScript​

Qliro's API allows cart item updates during an active payment session. Use centraCheckoutScript to suspend and resume the payment widget while Centra's backend sends updates to Qliro's API.

To resume, pass the updated basket total price to Qliro:

  1. Define a globalwindow.totalPrice on the checkout page.
  2. Update it with the current selection.checkout.totals.find(total => total.type === 'GRAND_TOTAL').price.value when the Qliro widget is active.
    For example:
    • After addItem mutation or updating basket lines via updateLine mutation, Centra's response includes the updated grand total price.

Ensure var totalPrice is defined and accessible within the script's scope, so it updates automatically when resume() is called.

q1.onOrderUpdated(function (order) {
  if (order.totalPrice === totalPrice) {
    q1.unlock();
  }
  // else, don't do anything
});

More information about centraCheckoutScript can be found here

Frontend Event Listeners​

After payment processing is initiated, updates to the active session in Qliro are not allowed. To prevent modifying the order in Centra, the frontend should use onPaymentProcess() to lock interaction with the checkout cart.

This is necessary to avoid mismatches between Centra and Qliro by preventing updates to the checkout once payment has been initiated with a specific cart total.

Qliro Event Listeners Documentation

Last updated on