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.

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)