Checkout – Checkin

Checkin

8 min read

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.

Guest Checkout

Note: If the payer is using the Payment Menu as a guest, you can go directly to step 3, which you will find on the next page.

Request

1
2
3
4
5
6
7
8
9
10
11

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"],
    "requireShippingAddress": true
}

Field	Type	Description
`operation`	`string`	`initiate-consumer-session`, the operation to perform.
`language`	`string`	Selected language to be used in Checkin. Supported values are `sv-SE`, `nb-NO` or `en-US`.
`shippingAddressRestrictedToCountryCodes`	`string`	List of supported shipping countries for merchant. Using ISO-3166 standard. This is required unless `requireShippingAddress` is set to false.
`requireShippingAddress`	`bool`	Defaults to true. If set to false we will not collect a shipping address from the consumer.

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

{
    "token": "7e380fbb3196ea76cc45814c1d99d59b66db918ce2131b61f585645eff364871",
    "operations": [
        {   // Deprecated operation. Do not use!
            "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.

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>

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']
}));

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 Start Page

As you can see, the payer’s information is pre-filled as provided by the initial POST.

From here, there are a three ways forward, depending on the consumer. If he or she is already registered with a profile at Swedbank Pay, the information already provided will be sufficient. The consumer can simply click proceed, and the profile will appear on the page (with sensitive data masked).

If Swedbank Pay detects that the consumer hasn’t registered any personal details, two options are provided: Store details for future purchases or proceed without storing details.

Consumer UI New Consumer Options

If he or she chooses to store details, the next step is to enter their SSN.

Consumer UI SSN

Once a valid SSN has been provided, a page for address details appears. When the consumer has entered their address, the profile box shown above will be displayed.

Consumer UI Address

If the consumer opts out of storing their details, they will be sent directly to the page for address details to enter their shipping address. This info is not stored for future purchases. Please note that this is not the same as shopping as a guest.

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 Consumer
    participant Merchant
    participant SwedbankPay as Swedbank Pay

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

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

    Consumer ->>+ Consumer: Initiate Consumer Hosted View (open iframe) ②
    Consumer ->>+ SwedbankPay: Show Consumer UI page in iframe ③
    deactivate Consumer
    SwedbankPay ->>- Consumer: Consumer identification process
    activate Consumer
    Consumer ->>+ SwedbankPay: Consumer identification process
    deactivate Consumer
    SwedbankPay -->>- Consumer: show consumer completed iframe
    activate Consumer
    Consumer ->> Consumer: EVENT: onConsumerIdentified (consumerProfileRef) ④
    deactivate Consumer
    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.