Seamless View

The Starter Seamless View integration consists of three main steps. Creating the payment order and checkin, displaying the payment menu, delivery options and checkin module in an iframe, and finally capturing the funds. In addition, there are other post purchase options you need. We get to them later on.

If you want to get an overview before proceeding, you can look at the sequence diagram. It is also available in the sidebar if you want to look at it later. Let´s get going with the two first steps of the integration.

Step 1: Create Payment Order And Checkin

When the purchase is initiated, you need to create a payment order.

Start by performing a POST request towards the paymentorder resource with payer information and a completeUrl.

We have added productName to the payment order request in this integration. You can find it in the paymentorder field. This is required if you want to use Checkout v3. If it isn´t included in your request, you won’t get the correct operations in the response.

When productName is set to checkout3, digitalProducts will be set to false by default. If digitalProducts is set to false, you also need to add shippingAddressRestrictedToCountryCodes along with ISO standard country codes.

Supported features for this integration are subscriptions (recur and unscheduled MIT), instrument mode and split settlement (subsite).

There is also a guest mode option for the payers who don’t wish to store their information. When using Starter, this is triggered when the payer chooses not to store credentials during checkin.

In some instances you need the possibility to abort purchases. This could be if a payer does not complete the purchase within a reasonable timeframe. For those instances we have abort, which you can read about in the core features. You can only use abort if the payer has not completed an authorize or a sale.

Payment Url

For our Seamless Views, the field called paymentUrl will be used when the payer is redirected out of the Seamless View (the iframe). The payer is redirected out of frame when selecting payment instruments which trigger SCA. This includes 3-D Secure card payments, credit account, invoice, MobilePay, monthly invoice payments, Trustly and Vipps.

The URL should represent the page of where the Payment Order Seamless View was hosted originally, such as the checkout page, shopping cart page, or similar. Basically, paymentUrl should be set to the same URL as that of the page where the JavaScript for the Seamless View was added to in order to initiate the payment process.

With paymentUrl in place, the retry process becomes much more convenient for both the integration and the payer.

Payment Order Request

Request

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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

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

{
    "paymentorder": {
        "operation": "Purchase",
        "currency": "SEK",
        "amount": 1500,
        "vatAmount": 375,
        "description": "Test Purchase",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "productName": "Checkout3",
        "urls": {
            "hostUrls": [ "https://example.com", "https://example.net" ],
            "paymentUrl": "https://example.com/perform-payment",
            "completeUrl": "https://example.com/payment-completed",
            "callbackUrl": "https://api.example.com/payment-callback",
            "termsOfServiceUrl": "https://example.com/termsandconditions.pdf"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "AB832",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-123456",
            "subsite": "MySubsite",
            "siteId": "MySiteId"
        },
        "payer": {
            "digitalProducts": false,
            "shippingAddressRestrictedToCountryCodes": [ "NO", "US" ]
        },
        "orderItems": [
            {
                "reference": "P1",
                "name": "Product1",
                "type": "PRODUCT",
                "class": "ProductGroup1",
                "itemUrl": "https://example.com/products/123",
                "imageUrl": "https://example.com/product123.jpg",
                "description": "Product 1 description",
                "discountDescription": "Volume discount",
                "quantity": 5,
                "quantityUnit": "pcs",
                "unitPrice": 300,
                "discountPrice": 0,
                "vatPercent": 2500,
                "amount": 1500,
                "vatAmount": 375
            }
        ],
        "riskIndicator": {
            "deliveryEmailAddress": "olivia.nyhuus@payex.com",
            "deliveryTimeFrameIndicator": "01",
            "preOrderDate": "19801231",
            "preOrderPurchaseIndicator": "01",
            "shipIndicator": "01",
            "giftCardPurchase": false,
            "reOrderPurchaseIndicator": "01",
            "pickUpAddress": {
                "name": "Olivia Nyhus",
                "streetAddress": "Saltnestoppen 43",
                "coAddress": "",
                "city": "Saltnes",
                "zipCode": "1642",
                "countryCode": "NO"
            }
        }
    }
}

Payment Order Response

Response

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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

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

{
    "paymentorder": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
        "created": "2020-06-22T10:56:56.2927632Z",
        "updated": "2020-06-22T10:56:56.4035291Z",
        "operation": "Purchase",
        "status": "Initialized",
        "currency": "SEK",
        "amount": 1500,
        "vatAmount": 375,
        "description": "Test Purchase",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "language": "sv-SE",
        "availableInstruments": [
          "CreditCard",
          "Invoice-PayExFinancingSe",
          "Invoice-PayMonthlyInvoiceSe",
          "Swish",
          "CreditAccount",
          "Trustly" ],
        "implementation": "Starter",
        "integration": "HostedView",
        "instrumentMode": false,
        "guestMode": false,
        "payer": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/payers"
        },
        "orderItems": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/orderitems"
        },
        "history": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/history"
        },
        "failed": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/failed"
        },
        "aborted": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/aborted"
        },
        "paid": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/paid"
        },
        "cancelled": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/cancelled"
        },
        "financialTransactions": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/financialtransactions"
        },
        "failedAttempts": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/failedattempts"
        },
        "metadata": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/metadata"
        }
      },
      "operations": [  
        {
          "method":"PATCH",
          "href": "https://api.payex.com/psp/paymentorders/222a50ca-b268-4b32-16fa-08d6d3b73224",
          "rel":"update-order",
          "contentType":"application/json"
        },
        {
          "method":"PATCH",
          "href": "https://api.payex.com/psp/paymentorders/222a50ca-b268-4b32-16fa-08d6d3b73224",
          "rel": "abort",
          "contentType": "application/json"
        }
       ]
      }

Step 2: Display Checkin, Delivery Options And Payment Menu

Among the operations in the POST paymentOrders response, you will find view-checkout. This is what you need to display the checkin and payment module.

Response

1
2
3
4
5
6
7
8
9
10
11

{
    "paymentOrder": {
    "operations": [
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/payment/core/js/px.payment.client.js?token=dd728a47e3ec7be442c98eafcfd9b0207377ce04c793407eb36d07faa69a32df&culture=sv-SE&_tc_tid=30f2168171e142d38bcd4af2c3721959",
            "rel": "view-checkout",
            "contentType": "application/javascript"
        },
    ]
}

Load The Seamless View

Embed the href in a <script> element. That script will then load the Seamless View.

To load the Checkout from the JavaScript URL obtained in the backend API response, it needs to be set as a script element’s src attribute. You can cause a page reload and do this with static HTML, or you can avoid the page refresh by invoking the POST to create the payment order through Ajax, and then create the script element with JavaScript. The HTML code will be unchanged in this example.

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

var request = new XMLHttpRequest();
request.addEventListener('load', function () {
    response = JSON.parse(this.responseText);
    var script = document.createElement('script');
    var operation = response.operations.find(function (o) {
        return o.rel === 'view-checkout';
    });
    script.setAttribute('src', operation.href);
    script.onload = function () {
        // When the 'view-checkout' script is loaded, we can initialize the
        // Payment Menu inside our 'payment-menu' container.
        // To open the Checkin
        window.payex.hostedView.checkout({
            container: {
                checkin: "checkin-container",
                paymentMenu: "payment-menu-container",
            },
            culture: 'nb-No',
            // If payer is identified
            onPayerIdentified: function onPayerIdentified(payerIdentified) {
                console.log(payerIdentified);
            },
            // If payer chooses "Not you?"
            onPayerUnidentified: function onPayerUnidentified(payerUnidentified) {
            console.log(payerUnidentified);
            },
            onEventNotification: function onEventNotification(eventNotification) {
                console.log(eventNotification);
            },
        }).open("checkin");
    };
    // Append the Checkout script to the <head>
    var head = document.getElementsByTagName('head')[0];
    head.appendChild(script);
});
// Like before, you should replace the address here with
// your own endpoint.
request.open('GET', '<Your-Backend-Endpoint-Here>', true);
request.setRequestHeader('Content-Type', 'application/json; charset=utf-8');
request.send();

When you get notified about the event onPayerIdentified, you need to do a GET on the paymentOrder. By expanding the payer field, you should get all the info you need to calculate shipping costs. You can now update the paymentOrder with a PATCH if you need to, using the patch from operations in the paymentOrder response.

Response

1
2
3
4
5
6
7
8
9

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

        {
            "method": "PATCH",
            "href": "https://ecom.externalintegration.payex.com/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
            "rel": "update-order",
            "contentType": "application/json"
        }

JavaScript

1
2
3
4
5
6
7
8

//to open the Payment Menu
window.payex.hostedView.checkout({
    container: {
        checkin: "checkin-container",
        paymentMenu: "payment-menu-container",
    },
    culture: 'nb-No',
}).open("paymentmenu");

HTML

1
2
3
4
5
6
7
8
9
10
11

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

How It Looks

First you will see a Checkin module where the payer can enter their email and phone number.

A known payer will be sent directly to the payment menu shown further below. If we detect that the payer is new, we give them the option to store their details or proceed without storing. If that happens, these checkin steps will appear.

After choosing yes or no, the payer must enter their SSN.

With digital products, the payer will be sent directly to delivery options after they select to store their details (see below). For mixed goods, the SSN input view will expand and the payer must enter their shipping address. Payers choosing not to store credentials (guests) must also enter their shipping address.

After checking in, the payer’s contact details and shipping address are shown for mixed goods. Note the new “Remember me” checkbox. The first time the checks in, the box will appear unchecked. If checked during a purchase, it will appear like the screenshot below during future check-ins, with a “Not you?” option in the top right corner.

You can now perform the GET on the payment order and display the available delivery option(s) to the payer. How the delivery options are displayed is up to you. This is how they appear in our demoshop.

For digital products, only contact details will be shown. “Remember me” will work the same way as with mixed goods.

When the payer chooses a delivery option, you can PATCH the payment order and open the payment menu. The payer can then proceed with the purchase.

Once a purchase is complete, you can perform a GET towards the paymentOrders resource to see the purchase state.

Events

When integrating Seamless View, especially with Starter where it’s the only option, we strongly recommend that you implement the onPaid event, as it will give you the best setup. Even with this implemented, you need to check the payment status towards our APIs, as the payer can make changes in the browser at any time.

When implementing Starter, you also need to subscribe to the event onPayerUnidentified when you implement onPayerIdentified. This is needed for the “Remember Me” feature to work. It is a part of the acceptance criteria, meaning you won’t get the green light to go live with your Starter implementation without it.

You can read more about the different Seamless View Events available in the feature section.