Qliro Checkout Adapter

Overview Document: Payment Adapters Overview

Overview and Unique Capabilities

The Qliro Checkout Adapter integrates Qliro Checkout with Norce Checkout. Changes made in Norce Checkout are synced with Qliro Checkout and vice versa. This page focuses on the unique technical details and configuration for Qliro.

Supported payment methods and other features: Features Overview

Configuration in Norce Admin

The adapter is configured using the following unique details obtained from Qliro:

Optional Configuration

Reference Source Configuration

Redirect URLs Configuration

Consent Options

Shipping Configuration

Qliro API Environments

In addition to the generic Norce Adapter URLs (see Payment Adapters Overview), Qliro uses the following external API environments:

Create Payment

To get a Qliro Checkout HTML snippet, create a Qliro Checkout payment for an existing Norce order:

POST /api/checkout/v1/orders/{order_id}/payments
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

The response includes an HTML snippet containing a script tag that should be rendered on your checkout page. The script tag will load an iframe which guides the customer through the Qliro Checkout UI.

Example response:

{
  "paymentId": "pyTWfWFQDxIwodoImZHAfSsZvON",
  "htmlSnippet": "<script type=\"text/javascript\">...</script><div id=\"qliro-root\"></div>"
}

The adapter also updates your Norce order with the Qliro payment details. The payments[].id property represents the paymentId from the response, and payments[].reference contains the Qliro order ID.

Confirmation Page

When the payment has been confirmed, Qliro redirects the user to the confirmationUrl. You must also include the Qliro Checkout iframe on your confirmation page, as it shows important purchase details to the customer.

To display the confirmation page, retrieve the Qliro Checkout order and render the snippet:

GET /api/checkout/v1/orders/{order_id}/payments/{payment_id}
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

When the Qliro Checkout order is in the state of PurchaseCompleted, it will show a "thank you" page instead of the default purchase flow.

Creating a Recurring Payment

To create an order using a previously stored recurring token:

POST /api/checkout/v1/orders/{order_id}/payments/recurring
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}
Content-Type: application/json

{
  "token": "3d2092a6-7baf-49e3-bd34-d0d0d85744b5"
}

The token is retrieved from a previous order where the customer completed a purchase with recurring payments enabled. To use recurring payments, merchants must activate this feature on both their Qliro merchant account (by contacting Qliro support) and in the Norce Qliro configuration by setting recurring: true.

Upsell

The upsell feature allows merchants to offer additional products to customers after they have completed their initial purchase. This is useful for subscription services, accessories, or related products.

To enable upsell:

1. Enable useUpsell in the adapter configuration
2. Ensure upsell is also enabled in your Qliro merchant account (contact Qliro support)
3. Configure upsellTimeoutSeconds to set the maximum time window for upsell offers (default: 300 seconds)

When an order is in the Accepted state and upsell is enabled, you can add items to the order. The adapter will call Qliro's upsell API to add the items to the existing payment. Once the upsell period expires or you explicitly complete the upsell, call the complete endpoint:

POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/upsell/complete
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

This endpoint requires no request body. A successful response returns 200 OK with no content.

Qliro Loyalty Sign-up

The Qliro Checkout Adapter supports Qliro's Loyalty Sign-up feature, which allows customers to enroll in a merchant's loyalty program directly inside the Qliro Checkout iframe. The adapter forwards a loyaltyConfiguration block to Qliro when the order is created, and Qliro renders the sign-up UI for the supported provider:

• Voyado Engage — creates a contact (or updates an existing member) in Voyado.
• Klaviyo — creates or updates a profile in Klaviyo and adds it to one or more lists.

For a full description of the customer-facing flow, see Qliro's Loyalty Sign-up documentation.

Prerequisites for Qliro Loyalty Sign-up

Before configuring loyaltyConfiguration in the Qliro Checkout Adapter, ensure all of the following are in place:

1. Qliro has activated the loyalty integration on your merchant account. Contact Qliro merchant solutions and provide:
   • An SVG logo for the loyalty provider, displayed in the sign-up component.
   • A provider API key (Voyado API key or Klaviyo private API key with Profile, List, and Subscription full-access permissions).
2. The loyalty provider is fully configured.
   • Voyado: the contact type and any consent IDs referenced in the configuration must already exist in your Voyado tenant.
   • Klaviyo: every list referenced by name in klaviyo.lists must already exist in your Klaviyo account, and the email or SMS subscription channels you enable must be configured (sending domain verified, default sender set).
3. The customer's email address is available in the Qliro Checkout iframe. Qliro looks up the customer in the loyalty provider by email. If the email is not pre-filled by the merchant in customerInformation.email, the customer must enter it in the iframe before Qliro can render the loyalty sign-up modal.

Qliro Loyalty Configuration

The loyaltyConfiguration object is part of the qliro_checkout_adapter configuration. The adapter includes it in the Qliro order-creation request. Provide either a voyado block or a klaviyo block — not both.

Top-level fields

Voyado loyalty configuration

The voyado block configures Qliro's interaction with Voyado Engage.

Example Voyado configuration:

"loyaltyConfiguration": {
  "askForSignupChecked": true,
  "merchantLoyaltyTermsUrl": "https://example.com/loyalty/terms",
  "merchantLoyaltyIntegrityPolicyUrl": "https://example.com/loyalty/privacy",
  "mainText": {
    "title": "Become a member",
    "description": "Join our loyalty program to collect bonus points on every purchase."
  },
  "updateText": {
    "title": "Update your preferences",
    "description": "We'd like to keep you up to date on offers and news."
  },
  "voyado": {
    "contactType": "Member",
    "consents": ["member"],
    "memberConsents": ["member"],
    "update": {
      "checkBoxes": [
        {
          "isChecked": false,
          "consentId": "newsletter",
          "label": "I want to receive the newsletter"
        }
      ]
    },
    "storeExternalId": "store-001"
  }
}

Klaviyo loyalty configuration

The klaviyo block configures Qliro's interaction with Klaviyo.

Example Klaviyo configuration:

"loyaltyConfiguration": {
  "askForSignupChecked": true,
  "merchantLoyaltyTermsUrl": "https://example.com/loyalty/terms",
  "merchantLoyaltyIntegrityPolicyUrl": "https://example.com/loyalty/privacy",
  "mainText": {
    "title": "Join our newsletter",
    "description": "Sign up to receive exclusive offers."
  },
  "klaviyo": {
    "lists": ["Newsletter"],
    "useEmailSubscriptionChannel": true,
    "useSmsSubscriptionChannel": false,
    "useSmsTransactionalChannel": false
  }
}

Qliro Loyalty Sign-up Notifications

When a customer opts in or updates consents in the loyalty sign-up component, Qliro calls the adapter with one of the following push notifications:

The adapter receives the full provider payload (Voyado contact or Klaviyo profile), maps it to a Norce loyalty record, and persists it on the Norce order at customer.loyalty. The persisted record contains:

• id — the provider's identifier for the member or profile.
• provider — Voyado or Klaviyo.
• attributes — an object containing:
  • isMember — true when the Voyado contact has contactType set to Member and approved set to true; false otherwise (including all Klaviyo profiles).
  • attributes — the provider's contact or profile fields (name, email, member number, bonus points, etc.).
  • meta — provider metadata such as contact type, approval status, and timestamps.
  • preferences — communication preferences returned by the provider.
  • consents — consent records returned by the provider.

The notification is processed asynchronously; the loyalty data may not be present on the order immediately after the customer opts in.

Qliro Loyalty Sign-up Troubleshooting

The Qliro Loyalty Sign-up modal does not appear in the Qliro Checkout iframe.

Verify, in order:

1. The order create request to Qliro includes a loyaltyConfiguration object with a non-null voyado or klaviyo block. If it is missing, check that loyaltyConfiguration is set in the qliro_checkout_adapter configuration for the channel.
2. The customer has entered an email address in the Qliro Checkout iframe (or the merchant has pre-filled customerInformation.email). Qliro cannot look up the customer in the loyalty provider without an email.
3. Qliro merchant solutions has activated the loyalty integration for your merchant API key, including the SVG logo and the provider API key.

The customer signs up but the profile or contact is not created in the loyalty provider.

• Klaviyo: confirm every list name in klaviyo.lists exactly matches an existing list in Klaviyo (names are case-sensitive). Confirm the Klaviyo private API key supplied to Qliro has Profile, List, and Subscription full-access permissions. If useEmailSubscriptionChannel is true and the list uses double opt-in, the profile is created but stays unsubscribed until the customer confirms via email.
• Voyado: confirm the contactType and every consent ID in consents and memberConsents exist in the Voyado tenant connected to Qliro.

The returning-member update flow is not shown to existing members.

The update flow requires both updateText (top level) and voyado.update.checkBoxes to be configured. Without both, Qliro shows the standard sign-up flow even for known members.

Synchronization Callbacks

The Qliro Checkout Adapter automatically handles synchronization between Qliro and Norce:

• Cart Changed: Qliro UI is suspended, order updated, then resumed
• Customer Update: Norce order updated with customer info from Qliro
• Shipping Option Update: Norce order updated with shipping selection

Idempotency and Retries

Qliro's checkout system uses idempotency to ensure that repeated identical requests have the same effect. This is important for retry scenarios and webhook handling. Please read the Qliro Checkout documentation on Idempotency and retries for detailed information.

Troubleshooting (Qliro Specific)

In addition to the generic troubleshooting steps:

• Review the order status in Qliro's merchant portal.
• If Capture fails, verify the Norce order is in the reserved state.
• Use the refresh endpoint to update available payment actions:

POST /api/order/v1/orders/{order_id}/payments/{payment_id}/refresh
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

Common Errors

• 409 Conflict: A payment already exists for this order.
• Validation Fails: Check stock availability and discount validity.
• Capture Fails: Order must be in reserved state.

Links and References

• Qliro Checkout Adapter (Business Overview)
• Qliro Checkout Adapter OpenAPI Specification
• Qliro Checkout Documentation (External)