Svea Checkout Adapter

Overview

Svea Checkout Adapter is a payment adapter for Svea Checkout. Read more on Svea Checkout docs

Environments

There are two environments that you can use.

Environment	Address
Test	https://checkout-svea-adapter.test.jetshopcloud.io
Production	https://checkout-svea-adapter.norce.tech

Configuration

You start by adding a configuration for the Svea Checkout Adapter in Norce Checkout Admin.

Create payment

To get a Svea Checkout HTML snippet, you start by initializing a checkout session for the order.

Copy

Copied

POST /api/v1/checkout/{order_id}/payments

A Svea Checkout session will be created and a JSON response will be returned which includes a paymentId and an HTML snippet. By embedding the HTML snippet in your checkout page, an iframe with the Svea Checkout will be loaded.

Copy

Copied

{
    "paymentId":"pujEsNeNLlTDuMWRPANoguleauN",
    "htmlSnippet":"
<div id=\"svea-checkout-container\" data-sco-sveacheckout=\"\" data-sco-sveacheckout-locale=\"sv-SE\" style=\"overflow-x: hidden; overflow-y: hidden;\">
    <noscript> Please <a href=\"http://enable-javascript.com\">enable JavaScript</a>. </noscript>
    <iframe id=\"svea-checkout-iframe\" name=\"svea-checkout-iframe\" data-sco-sveacheckout-iframeSrc=\"https://checkoutapistage.svea.com/b/index.html?orderId=9017996&merchantId=124842&authToken=someAuthToken&locale=sv-SE&enableEvents=true&_638370395429587445\" scrolling=\"no\" frameborder=\"0\" style=\"display: none; width: 1px; min-width: 100%; max-width: 100%;\"></iframe>
</div>

<script type=\"text/javascript\" src=\"https://checkoutapistage.svea.com/merchantscript/index.js?v=6a6b0af1db9429d6278062d73c274b29\"></script>
<script type=\"text/javascript\">!function(e){var t=e.document,n=t.querySelectorAll(\"[\".concat(\"data-sco-sveacheckout\",\"]\"));if(!n.length)throw new Error(\"No Svea checkout container exists on page\");function c(){return!!e.scoInitializeInjectedInstances&&(e.scoInitializeInjectedInstances(),!0)}var o,i;c()||(o=0,e.setTimeout(i=function(){o+=1,c()||(o<150?e.setTimeout(i,20):[].slice.call(n).forEach(function(e){var n=t.createElement(\"div\");n.innerHTML=\"Something went wrong, please refresh the page\",e.appendChild(n)}))},20))}(window);</script>

"
}

The Svea Checkout Adapter will also update your order with the payment details needed to get your frontend working.

Copy

Copied

{
    // ...
	"payments": [
        {
            "id": "pujEsNeNLlTDuMWRPANoguleauN",
            "adapterId": "svea_checkout_adapter",
            "name": "svea_checkout_adapter",
            "merchant": "norce-checkout-demo",
            "channel": "svea-b2c",
            "type": "default",
            "orderId": "oAPpsaMj",
            "amount": 321.0,
            "upperLimitAmount": 2147483647.0,
            "state": "intent",
            "reference": "9017996",
            "attributes": {},
            "actions": []
        }
	]
    // ...
}

Recurring payment (Optional)

To use Recurring Payments, merchants must activate this feature on both their Svea merchant account and in the Norce Svea configuration. When this setting is enabled, all orders placed through this channel will be created in Svea with the "recurring": "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.

Copy

Copied

{
    // ...
	"payments": [
        {
          "id": "pxrnztANjUvStDramXmjRCYmJtl",
          "adapterId": "svea_checkout_adapter",
          "name": "svea_checkout_adapter",
          "merchant": "norcecheckouttest",
          "channel": "norce-checkout-se-svea-recurring",
          "type": "default",
          "orderId": "oUATilze",
          "amount": 100,
          "upperLimitAmount": 2147483647,
          "state": "reserved",
          "reference": "9360407",
          "attributes": {
            "clientId": "206444",
            "paymentName": "Card"
          }
          "actions": [],
          "recurring": {
             "token": "cd45444b-e125-4660-b5c0-08dce7ff05be",
             "attributes": {}
          }
        }
	]
    // ...
}

How to Create a New Order and Add Svea Payment Using a Previously Issued Token

To generate a new order and process payment through Svea using a valid Svea 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 svea token. The customer does not need to participate in or approve the transaction, simplifying the process for subscription services or repeat purchases.

Endpoint

Copy

Copied

POST /api/checkout/v1/orders/{order_id}/payments/recurring

Request body

Copy

Copied

{
   "token": "cd45444b-e125-4660-b5c0-08dce7ff05be",
}

In this request, order_id is the identifier of the new order, and the token is retrieved from the previous order where the customer initially provided their payment details and consented to store a token for future use.

If the token is valid, the response from Svea will include the customer's billing and delivery address. The system will automatically update the provided order with this information, ensuring that the latest details connected to this token are applied to the order.

limitations:

Please note that the token usage is capped at three orders per day in the production environment to ensure optimal performance and security.
If merchant utilizes shipping (nShift), recurring orders cannot be set.

Register iframe events

Customer information iframe events

To be able to respond to changes made in the Svea Checkout iframe regarding customer information, the following iframe events needs to be registered (refer to Sveas documentation for the most up to date information):

identity.isCompany
identity.email
identity.phoneNumber
identity.companyName
identity.firstName
identity.lastName
identity.streetAddress
identity.coAddress
identity.postalCode
identity.city
identity.addressLines

When these events occur, a call can be made to the following endpoint, in order to update the customer information:

Copy

Copied

POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/customer-update

Shipping information iframe events

To be able to respond to changes made in the Svea Checkout iframe regarding shipping information, the following iframe events needs to be registered (refer to Sveas documentation for the most up to date information):

shippingConfirmed

When this event occur, a call can be made to the following endpoint, in order to update the shipping information:

Copy

Copied

POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/shipping-option-update

Backends callbacks

The Svea Checkout backend callbacks are handled by the Svea Checkout Adapter.

Validate checkout

When the user clicks on "Completed Purchase" in Svea Checkout UI a validation is sent to the validation callback. At this stage we will set the payment address so you can determine the customer. You can configure Norce Checkout to validate that all products are still available in stock and that all discounts are valid for the customer. A validation url can be configured in Norce Checkout settings.

If validation is successful your validation url return a 200 SUCCESS and Svea will continue with confirming the payment. At this point the Norce order will go to processing state and the session will be locked to any changes except status update.

If the validation failed a non 200 response will be return with message that will be displayed in the Svea Checkout UI.

Confirm payment

When the payment has been confirmed Svea will call the "Push Url" to complete the order. We update the payment and then redirects the user to the Confirmation Url of Svea checkout adapter.

It is required that you also include the Checkout iframe in your purchase confirmation page as the Checkout iframe will show important purchase details to the customer. To display the "thank you" page on another page, for example when redirecting the user to a custom thank you page, put an identical <script> element on this page as well. When the checkout is in the state of PurchaseCompleted it will show a thank you page instead of the normal checkout flow.

You do this by getting the Checkout order from Svea checkout adapter and render the snippet.

Copy

Copied

GET /api/v1/checkout/{order_id}/payments/{payment_id}

Copy

Copied

{
    "paymentId":"pujEsNeNLlTDuMWRPANoguleauN",
    "htmlSnippet":"
<div id=\"svea-checkout-container\" data-sco-sveacheckout=\"\" data-sco-sveacheckout-locale=\"sv-SE\" style=\"overflow-x: hidden; overflow-y: hidden;\">
    <noscript> Please <a href=\"http://enable-javascript.com\">enable JavaScript</a>. </noscript>
    <iframe id=\"svea-checkout-iframe\" name=\"svea-checkout-iframe\" data-sco-sveacheckout-iframeSrc=\"https://checkoutapistage.svea.com/b/index.html?orderId=9017996&merchantId=124842&authToken=someAuthToken&locale=sv-SE&enableEvents=true&_638370395429587445\" scrolling=\"no\" frameborder=\"0\" style=\"display: none; width: 1px; min-width: 100%; max-width: 100%;\"></iframe>
</div>

<script type=\"text/javascript\" src=\"https://checkoutapistage.svea.com/merchantscript/index.js?v=6a6b0af1db9429d6278062d73c274b29\"></script>
<script type=\"text/javascript\">!function(e){var t=e.document,n=t.querySelectorAll(\"[\".concat(\"data-sco-sveacheckout\",\"]\"));if(!n.length)throw new Error(\"No Svea checkout container exists on page\");function c(){return!!e.scoInitializeInjectedInstances&&(e.scoInitializeInjectedInstances(),!0)}var o,i;c()||(o=0,e.setTimeout(i=function(){o+=1,c()||(o<150?e.setTimeout(i,20):[].slice.call(n).forEach(function(e){var n=t.createElement(\"div\");n.innerHTML=\"Something went wrong, please refresh the page\",e.appendChild(n)}))},20))}(window);</script>

"
}

Pending payment

The Pending Payment flow occurs when a payment has been initiated but is placed in a Pending state for various reasons. This may include:

Awaiting a response from the external provider or bank
Missing delivery address
High order amount requiring manual intervention by Svea for approval

In these cases, the user will see the order completion page, but the Norce order remains in an accepted state. Once the payment is either accepted or declined, Svea will send an event to the

Copy

Copied

POST /api/checkout/v1/callback/orders/event

endpoint, which will update the order and payment status based on the received event.