Swedbank Pay Checkout – Checkin

Swedbank Pay Checkout consists of two parts: Checkin and Payment Menu. In the sections that follow you’ll find examples of the HTTP requests, responses and HTML code you will need to implement in order to complete the Swedbank Pay Checkout integration. To finalize Checkout you first have to Checkin. To check in, the payer needs to be identified.

Step 1: Initiate session for consumer identification

The payer will be identified with the consumers resource and will be persisted to streamline future Payment Menu processes. Payer identification is done through the initiate-consumer-session operation.

Request

1
2
3
4
5
6
7
8
9
10

POST /psp/consumers HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "operation": "initiate-consumer-session",
    "language": "sv-SE",
    "shippingAddressRestrictedToCountryCodes" : ["NO", "SE", "DK"]
}
Required Field Type Description
check operation string initiate-consumer-session, the operation to perform.
check language string Selected language to be used in Checkin. Supported values are sv-SE, nb-NO or en-US.
check shippingAddressRestrictedToCountryCodes string List of supported shipping countries for merchant. Using ISO-3166 standard.

When the request has been sent, a response containing an array of operations that can be acted upon will be returned:

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

HTTP/1.1 200 OK
Content-Type: application/json

{
    "token": "7e380fbb3196ea76cc45814c1d99d59b66db918ce2131b61f585645eff364871",
    "operations": [
        {
            "method": "GET",
            "rel": "redirect-consumer-identification",
            "href": "https://ecom.externalintegration.payex.com/consumers/sessions/7e380fbb3196ea76cc45814c1d99d59b66db918ce2131b61f585645eff364871",
            "contentType": "text/html"
        },
        {
            "method": "GET",
            "rel": "view-consumer-identification",
            "href": "https://ecom.externalintegration.payex.com/consumers/core/scripts/client/px.consumer.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119",
            "contentType": "application/javascript"
        }
    ]
}
Field Type Description
token string A session token used to initiate Checkout UI.
operations array The array of operation objects to choose from, described in detail in the table below.
└➔ rel string The relational name of the operation, used as a programmatic identifier to find the correct operation given the current state of the application.
└➔ method string The HTTP method to use when performing the operation.
└➔ contentType string The HTTP content type of the target URI. Indicates what sort of resource is to be found at the URI, how it is expected to be used and behave.
└➔ href string The target URI of the operation.

Step 2: Display Swedbank Pay Checkin module

The response from the POST of consumer information contains a few operations. The combination of rel, method and contentType should give you a clue how the operation should be performed. The view-consumer-identification operation and its application/javascript content type gives us a clue that the operation is meant to be embedded in a <script> element in an HTML document.

warning

In our example we will focus on using the view-consumer-identification solution. The redirect-consumer-identification method redirects the user to Swedbank’s own site to handle the checkin and is used in other implementations. redirect-consumer-identification should only be used in test enviroments. It is not suitable for the production environment as there is no simple way of retrieving the consumerProfileRef.

HTML

1
2
3
4
5
6
7
8
9
10
11
12

<!DOCTYPE html>
<html>
    <head>
        <title>Swedbank Pay Checkout is Awesome!</title>
    </head>
    <body>
        <div id="checkin"></div>
        <div id="payment-menu"></div>
        <!-- Here you can specify your own javascript file -->
        <script src="<Your-JavaScript-File-Here>"></script>
    </body>
</html>
info

The Checkin and Payment Menu components (the two <iframe> elements) must be separate (one must not replace the other).

In the HTML, you only need to add two <div> elements to place the check-in and payment menu inside of. The JavaScript will handle the rest when it comes to handling the check-in and payment menu.

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

var request = new XMLHttpRequest();

request.addEventListener('load', function () {
    // We will assume that our own backend returns the
    // exact same as what SwedbankPay returns.
    var response = JSON.parse(this.responseText);
    var script = document.createElement('script');
    // This assumes that the operations from the response of the POST from the
    // payment order is returned verbatim from the server to the Ajax:
    var operation = response.operations.find(function (o) {
        return o.rel === 'view-consumer-identification';
    });

    script.setAttribute('src', operation.href);
    script.onload = function () {
        payex.hostedView.consumer({
            // The container specifies which id the script will look for
            // to host the checkin component
            container: 'checkin',
            onConsumerIdentified: function onConsumerIdentified(consumerIdentifiedEvent) {
                // consumerIdentifiedEvent.consumerProfileRef contains the reference
                // to the identified consumer which we need to pass on to the
                // Payment Order to initialize a personalized Payment Menu.
                console.log(consumerIdentifiedEvent);
            },
            onShippingDetailsAvailable: function onShippingDetailsAvailable(shippingDetailsAvailableEvent) {
                console.log(shippingDetailsAvailableEvent);
            }
        }).open();
    };
    // Appending the script to the head
    var head = document.getElementsByTagName('head')[0];
    head.appendChild(script);
});

// Place in your own API endpoint here.
request.open('POST', '<Your-Backend-Endpoint-Here>', true);
request.setRequestHeader('Content-Type', 'application/json; charset=utf-8');
// In this example we'll send in all of the information mentioned before,
// in the request to the endpoint.
request.send(JSON.stringify({
    operation: 'initiate-consumer-session',
    language: 'sv-SE',
    shippingAddressRestrictedToCountryCodes: ['NO', 'SE']
}));
info

Note that we add the script at the end of the body. This ensures that every element (like the container <div> elements) has loaded in before we try to access them with our script.

With the scripts loading in after the entire page is loaded, we can access the <div> container that the Checkin will be hosted in. After that has all loaded, you should see something like this:

Consumer UI

As you can see, the payer’s information is pre-filled as provided by the initial POST. With a consumerProfileRef safely tucked into our pocket, the Checkin is complete and we can move on to Payment Menu.

A complete overview of how the process of identifying the payer through Checkin is illustrated in the sequence diagram below.

sequenceDiagram
    participant Payer
    participant Merchant
    participant SwedbankPay as Swedbank Pay

        rect rgba(238, 112, 35, 0.05)
            note left of Payer: Checkin

    Payer ->>+ Merchant: Start Checkin
    Merchant ->>+ SwedbankPay: POST /psp/consumers
    deactivate Merchant
    SwedbankPay -->>+ Merchant: rel:view-consumer-identification ①
    deactivate SwedbankPay
    Merchant -->>- Payer: Show Checkin on Merchant Page

    Payer ->>+ Payer: Initiate Consumer Hosted View (open iframe) ②
    Payer ->>+ SwedbankPay: Show Consumer UI page in iframe ③
    deactivate Payer
    SwedbankPay ->>- Payer: Consumer identification process
    activate Payer
    Payer ->>+ SwedbankPay: Consumer identification process
    deactivate Payer
    SwedbankPay -->>- Payer: show consumer completed iframe
    activate Payer
    Payer ->> Payer: EVENT: onConsumerIdentified (consumerProfileRef) ④
    deactivate Payer
    end

If a browser refresh is performed after the payer has checked in, the payment menu must be shown even though onConsumerIdentified is not invoked.

Additional events during Checkin can also be implemented in the configuration object, such as onConsumerIdentified, onShippingDetailsAvailableand onBillingDetailsAvailable. Read more about these in the Checkin events section.

Note on consumer data

During this stage some consumer data is stored. Read more about our Data Protection Policy for details on which information we store and its duration.