Qliro Checkout adapter
Overview
Qliro Checkout adapter integrates Qliro Checkout with Norce Checkout. Changes made in Norce Checkout are synced with Qliro Checkout and vise versa. In order to use this adapter effectively you need to know how to use Qliro Checkout, here you can find the Qliro Checkout docs.
Configuration
You start by adding a configuration for the Qliro Checkout adapter in Norce Checkout Admin.
Create payment
To get a Qliro Checkout HTML snippet, you start by creating a Qliro Checkout payment for an existing Norce order. A Qliro Checkout payment session will be created and the JSON response will include an HTML snippet containing a script tag that should be rendered on your checkout page. The script tag will load an iframe which will guide the customer through the Qliro Checkout UI.
POST /api/checkout/v1/{order_id}/payments{
"paymentId":"pyTWfWFQDxIwodoImZHAfSsZvON",
"htmlSnippet":"<script type=\"text/javascript\">(function(w, g) { w[g] = {\r\ncheckoutWebAppBaseUrl: \"https://pago.qit.nu/checkout/webapp/\",\r\ncheckoutWebAppVersion: \"1.99.2\",\r\ncheckoutWebApiBaseUrl: \"https://pago.qit.nu/checkout/webapi/\",\r\nqliroTermsUrl: \"https://assets.qliro.com/terms/se/sv/terms/1/user_terms.pdf\",\r\norderId: \"4009289\",\r\ncountry: \"SE\",\r\nlanguage: \"sv-se\",\r\nauth: \"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJNZXJjaGFudElkIjoiMjM2IiwiT3JkZXJJZCI6IjQwMDkyODkiLCJDb3VudHJ5Q29kZSI6IlNFIiwiQ3VycmVuY3lDb2RlIjoiU0VLIiwiTGFuZ3VhZ2VDb2RlIjoic3Ytc2UiLCJuYmYiOjE3MDE4ODE0MjgsImV4cCI6MTcwMTg4NjgyOCwiaWF0IjoxNzAxODgxNDI4LCJpc3MiOiJRTyJ9.YIvDkIUeFuHL3GJ2rKqP97mBSbIpiRn6L40jlEbtHT4\",\r\nmerchantConfirmationUrl: \"https://norce-checkout-test.jetshop.se/neworderconfirmation?orderId=onksAnol&channel=qliro\",\r\nmerchantTermsUrl: \"https://norce-checkout-test.jetshop.se/terms?orderId=onksAnol&channel=qliro\",\r\ncustomerCheckoutStatus: \"InProcess\",\r\nmerchantIntegrityPolicyUrl: \"\",\r\nqliroIntegrityPolicyUrl: \"https://assets.qliro.com/terms/se/sv/terms/1/integrity_policy.pdf\",\r\nqliroInvoiceTermsUrl: \"https://assets.qliro.com/terms/se/sv/terms/1/terms_invoice.pdf\",\r\npublicTrackingId: \"af65b373-6067-477e-9e28-5274c6d8f968\",\r\ngoogleApiKey: \"AIzaSyAkW8LC2HF0pKCph1DxCZpMtkLv5FDnI1Y\",\r\norderPollSetting: [],\r\npaymentStatusPollSetting: [{ waitInMs: 300, maxTries: 10 }, { waitInMs: 1000, maxTries: 25 }, { waitInMs: 5000 }],\r\nfrontendValidationTimeoutInMilliseconds: 7000,\r\nstyling: {\r\n},\r\n\r\npersonalNumberFormat: {\r\ncanBePresentedWithBirthdayAndLastXCharacters: true,\r\n},\r\n\r\npaymentMethodConfig: {\r\ntrustly: {\"visibleBanks\":[\"SWEDBANK\",\"HANDELSBANKEN\",\"NORDEA\",\"SEB\"]},\r\n},\r\n\r\ntrackingConfig: {\r\nenableGoogleAnalytics: true,\r\nenableGoogleOptimize: true,\r\nenableNewRelic: true,\r\nenableHotjar: false,\r\nenableSetOfTrackingOnInitialOrderFetch: false,\r\n},\r\n\r\naddressConfig: {\r\nshowArea: false,\r\nshowStreet2ForPhysical: false,\r\n},\r\n\r\nnewsLetterSignup: {\r\nchecked: false,\r\ntext: \"Jag vill ha nyheter och erbjudanden!\",\r\n},\r\n\r\nfeatureToggles: {\r\nenableNewIdentityVerification: \"true\",\r\nforceBankIdCountries: \"[]\",\r\ndisableShowBankIdDialogCountries: \"[\\\"SE\\\",\\\"NO\\\",\\\"FI\\\",\\\"DK\\\"]\",\r\ndisableGoogleMapsComponent: \"true\",\r\ndisableGoogleMapsScriptAndComponent: \"true\",\r\nenableGoogleMapsLink: \"true\",\r\nreportAccessCodeInOnShippingMethodChangedListener: \"{ \\\"*\\\": false, \\\"Lyko\\\": true, \\\"hats-staging\\\": true }\",\r\nfetchRetryConfig: \"{ \\\"totalRetries\\\": 6, \\\"waitIntervalMs\\\": 300 }\",\r\nendpointsWithFetchRetry: \"[\\\"identityverification/PollIdentityVerificationStatus\\\", \\\"paymenttransaction/getpaymenttransactionstatus\\\"]\",\r\nopenBankIdWithWebUrl: \"{ \\\"*\\\": false, \\\"hats-dev\\\": true }\",\r\nenableTwoAddressesForPhysicalCountries: \"[]\",\r\ntrustlyDirectSaveAccountEnabledCountries: \"[\\\"SE\\\", \\\"NO\\\", \\\"DK\\\", \\\"FI\\\", \\\"NL\\\", \\\"DE\\\", \\\"AT\\\", \\\"CZ\\\", \\\"UK\\\", \\\"SP\\\", \\\"FR\\\", \\\"EE\\\", \\\"LAT\\\", \\\"LT\\\"]\",\r\nuseBinListBrandDetection: \"{\\\"*\\\": true}\",\r\n},\r\n\r\n}\r\n})\r\n(window, 'qcoGlobal');</script><div id=\"qliro-root\"></div><script src=\"https://pago.qit.nu/checkout/webapp/bootstrap.js?v=1.99.2_5/TSB1/TWaHAeGz7uq8=XXXXXXXX\" async></script>"
}The Qliro Checkout adapter will also update your Norce order with the Qliro payment details. The payments[].id property represents the paymentId from the JSON response received when initializing the Qliro Checkout payment session and the payments[].orderId represents the Norce order identifier.
{
...
"payments": [
{
"id": "pyTWfWFQDxIwodoImZHAfSsZvON",
"adapterId": "qliro_checkout_adapter",
"name": "qliro_checkout_adapter",
"merchant": "norce-checkout-test",
"channel": "qliro",
"currency": "SEK",
"type": "default",
"orderId": "onksAnol",
"amount": 1295,
"upperLimitAmount": 2147483647,
"state": "intent",
"reference": "4009289",
"attributes": {},
"actions": []
}
...
}Update payment
When a Norce order changes a Cart Changed callback will be triggered in the Qliro Checkout adapter, during which the Qliro Checkout UI will be suspended to avoid any concurrent operations. The Qliro Checkout order will then be updated with the latest information from the Norce order, after which the Qliro Checkout UI will be resumed.
Update customer and shipping option
When the customer updates their customer and/or shipping information in the Qliro Checkout UI this will trigger separate 'Client-side events' callbacks in the Qliro Checkout Adapter to ensure that the Norce order is always up to date with the latest Qliro order information. Update Customer callback will update the Norce order with latest customer information from Qliro and Update Shipping Option callback will update the Norce order with the latest shipping information from Qliro.
Validate payment
When the user clicks on "Completed Purchase" in Qliro Checkout UI a validation callback is triggered in the Qliro Checkout adapter. If the validation is successful Qliro will continue with confirming the payment. At this point the Norce order will go to processing state and the order will be locked to any changes except status update.
If the validation failed a non 200 response will be return with a message that will be displayed in the Qliro Checkout UI.
Confirm payment
When the payment has been confirmed Qliro will call the configured MerchantOrderManagementStatusPushUrl to complete the order, update the payment and then redirects the user to the confirmationUrl of the Qliro checkout adapter.
It is required that you also include the Qliro Checkout iframe in your purchase confirmation page, since this Qliro Checkout iframe will show important purchase details to the customer. To display a "thank you" page on another page, for example when redirecting the user to a custom confirmation page, put an identical <script> tag on this page as well. When the Qliro Checkout order is in the state of PurchaseCompleted it will show a "thank you" page instead of the default purchase flow.
You do this by getting the Qliro Checkout order from Qliro Checkout adapter and render the snippet.
GET /api/checkout/v1/{order_id}/payments/{payment_id}{
"paymentId":"pyTWfWFQDxIwodoImZHAfSsZvON",
"htmlSnippet":"<script type=\"text/javascript\">(function(w, g) { w[g] = {\r\ncheckoutWebAppBaseUrl: \"https://pago.qit.nu/checkout/webapp/\",\r\ncheckoutWebAppVersion: \"1.99.2\",\r\ncheckoutWebApiBaseUrl: \"https://pago.qit.nu/checkout/webapi/\",\r\nqliroTermsUrl: \"https://assets.qliro.com/terms/se/sv/terms/1/user_terms.pdf\",\r\norderId: \"4009289\",\r\ncountry: \"SE\",\r\nlanguage: \"sv-se\",\r\nauth: \"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJNZXJjaGFudElkIjoiMjM2IiwiT3JkZXJJZCI6IjQwMDkyODkiLCJDb3VudHJ5Q29kZSI6IlNFIiwiQ3VycmVuY3lDb2RlIjoiU0VLIiwiTGFuZ3VhZ2VDb2RlIjoic3Ytc2UiLCJuYmYiOjE3MDE4ODE0MjgsImV4cCI6MTcwMTg4NjgyOCwiaWF0IjoxNzAxODgxNDI4LCJpc3MiOiJRTyJ9.YIvDkIUeFuHL3GJ2rKqP97mBSbIpiRn6L40jlEbtHT4\",\r\nmerchantConfirmationUrl: \"https://norce-checkout-test.jetshop.se/neworderconfirmation?orderId=onksAnol&channel=qliro\",\r\nmerchantTermsUrl: \"https://norce-checkout-test.jetshop.se/terms?orderId=onksAnol&channel=qliro\",\r\ncustomerCheckoutStatus: \"InProcess\",\r\nmerchantIntegrityPolicyUrl: \"\",\r\nqliroIntegrityPolicyUrl: \"https://assets.qliro.com/terms/se/sv/terms/1/integrity_policy.pdf\",\r\nqliroInvoiceTermsUrl: \"https://assets.qliro.com/terms/se/sv/terms/1/terms_invoice.pdf\",\r\npublicTrackingId: \"af65b373-6067-477e-9e28-5274c6d8f968\",\r\ngoogleApiKey: \"AIzaSyAkW8LC2HF0pKCph1DxCZpMtkLv5FDnI1Y\",\r\norderPollSetting: [],\r\npaymentStatusPollSetting: [{ waitInMs: 300, maxTries: 10 }, { waitInMs: 1000, maxTries: 25 }, { waitInMs: 5000 }],\r\nfrontendValidationTimeoutInMilliseconds: 7000,\r\nstyling: {\r\n},\r\n\r\npersonalNumberFormat: {\r\ncanBePresentedWithBirthdayAndLastXCharacters: true,\r\n},\r\n\r\npaymentMethodConfig: {\r\ntrustly: {\"visibleBanks\":[\"SWEDBANK\",\"HANDELSBANKEN\",\"NORDEA\",\"SEB\"]},\r\n},\r\n\r\ntrackingConfig: {\r\nenableGoogleAnalytics: true,\r\nenableGoogleOptimize: true,\r\nenableNewRelic: true,\r\nenableHotjar: false,\r\nenableSetOfTrackingOnInitialOrderFetch: false,\r\n},\r\n\r\naddressConfig: {\r\nshowArea: false,\r\nshowStreet2ForPhysical: false,\r\n},\r\n\r\nnewsLetterSignup: {\r\nchecked: false,\r\ntext: \"Jag vill ha nyheter och erbjudanden!\",\r\n},\r\n\r\nfeatureToggles: {\r\nenableNewIdentityVerification: \"true\",\r\nforceBankIdCountries: \"[]\",\r\ndisableShowBankIdDialogCountries: \"[\\\"SE\\\",\\\"NO\\\",\\\"FI\\\",\\\"DK\\\"]\",\r\ndisableGoogleMapsComponent: \"true\",\r\ndisableGoogleMapsScriptAndComponent: \"true\",\r\nenableGoogleMapsLink: \"true\",\r\nreportAccessCodeInOnShippingMethodChangedListener: \"{ \\\"*\\\": false, \\\"Lyko\\\": true, \\\"hats-staging\\\": true }\",\r\nfetchRetryConfig: \"{ \\\"totalRetries\\\": 6, \\\"waitIntervalMs\\\": 300 }\",\r\nendpointsWithFetchRetry: \"[\\\"identityverification/PollIdentityVerificationStatus\\\", \\\"paymenttransaction/getpaymenttransactionstatus\\\"]\",\r\nopenBankIdWithWebUrl: \"{ \\\"*\\\": false, \\\"hats-dev\\\": true }\",\r\nenableTwoAddressesForPhysicalCountries: \"[]\",\r\ntrustlyDirectSaveAccountEnabledCountries: \"[\\\"SE\\\", \\\"NO\\\", \\\"DK\\\", \\\"FI\\\", \\\"NL\\\", \\\"DE\\\", \\\"AT\\\", \\\"CZ\\\", \\\"UK\\\", \\\"SP\\\", \\\"FR\\\", \\\"EE\\\", \\\"LAT\\\", \\\"LT\\\"]\",\r\nuseBinListBrandDetection: \"{\\\"*\\\": true}\",\r\n},\r\n\r\n}\r\n})\r\n(window, 'qcoGlobal');</script><div id=\"qliro-root\"></div><script src=\"https://pago.qit.nu/checkout/webapp/bootstrap.js?v=1.99.2_5/TSB1/TWaHAeGz7uq8=XXXXXXXX\" async></script>"
}Recurring orders (Optional)
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. When this setting is enabled, all order items placed through this channel will be created in Qliro with the 'metadata.subscription.enabled: true' option selected. The token will be received upon payment finalization and saved with the order payment. This token represents the customer and their chosen payment method, which can be used to initiate future purchases.
How to Create a New Order and Add Qliro Payment Using a Previously Issued Token
To generate a new order and process payment through Qliro using a valid Qliro Checkout token, you can utilize the recurring payment feature. This process allows the creation of a new order without involving the customer, as their payment details are securely stored and reused using the Qliro token. The customer does not need to participate in or approve the transaction, simplifying the process for subscription services or repeat purchases.
POST /api/checkout/v1/orders/{order_id}/payments/recurringRequest Body
{
"token": "3d2092a6-7baf-49e3-bd34-d0d0d85744b5"
}token (string): The token representing the recurring payment method.
Responses
200 OK: Returns a detailed PaymentResponse indicating successful transaction completion.
400 Bad Request: Indicates invalid input or configuration errors.
404 Not Found: Occurs if the specified order ID does not exist.
409 Conflict: Occurs if a Qliro payment already exists for this order.
Example Response
{
"paymentId":"pyTWfWFQDxIwodoImZHAfSsZvON"
}Idempotency and retries
Please read the Qliro Checkout documentation on Idempotency and retries.