Payment Order

Step 1: Create Payment Order

We start by performing a POST request towards the paymentorder resource in order to create a Payment Order.

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 methods which trigger SCA. This includes 3-D Secure card payments, installment 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.

Request

Payment Order Request

Request

Copy json to clipboard

1
2
3
4

POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.x/2.0      // Version optional for 3.0 and 2.0

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

{
    "paymentorder": {
        "operation": "Purchase",
        "currency": "SEK",
        "amount": 1500,
        "vatAmount": 375,
        "description": "Test Purchase",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "generatePaymentToken": false,
        "generateRecurrenceToken": false,
        "generateUnscheduledToken": false,
        "urls": {
            "hostUrls": [ "https://example.com", "https://example.net" ],
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-cancelled",
            "paymentUrl": "https://example.com/perform-payment",
            "callbackUrl": "https://api.example.com/payment-callback",
            "termsOfServiceUrl": "https://example.com/termsandconditions.pdf",
            "logoUrl": "https://example.com/logo.png"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "AB832",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-123456",
            "subsite": "MySubsite"
        },
        "payer": {  
            "email": "olivia.nyhuus@swedbankpay.com",
            "msisdn": "+4798765432",
            "workPhoneNumber" : "+4787654321",
            "homePhoneNumber" : "+4776543210"
        },
        "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@swedbankpay.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

Copy json to clipboard

1
2
3

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.x/2.0
api-supported-versions: 3.x/2.0

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
74
75
76
77

{
    "paymentorder": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
        "instrument": "CreditCard",
        "paymentToken" : "5a17c24e-d459-4567-bbad-aa0f17a76119",
        "recurrenceToken": 2c327f17-1818-425a-9657-5d7d69778b31,
        "unscheduledToken": 064c3cbd-9401-4356-aba2-92cc3484313b,
        "created": "2020-06-22T10:56:56.2927632Z",
        "updated": "2020-06-22T10:56:56.4035291Z",
        "operation": "Purchase",
        "state": "Ready",
        "currency": "SEK",
        "amount": 10000,
        "vatAmount": 0,
        "orderItems": {
            "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/orderitems"
        },
        "description": "test description",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "userAgent": "Mozilla/5.0",
        "language": "sv-SE",
        "urls": {
            "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/urls"
        },
        "payeeInfo": {
            "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payeeInfo"
        },
        "payments": {
            "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payments"
        },
        "currentPayment": {
            "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/currentpayment"
        },
        "items": [
            {
                "creditCard": {
                    "cardBrands": [
                        "Visa",
                        "MasterCard"
                    ]
                }
            }
        ]
    }
    "operations": [
        {
            "method": "PATCH",
            "href": "https://ecom.externalintegration.payex.com/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
            "rel": "update-paymentorder-updateorder",
            "contentType": "application/json"
        },
        {
            "method": "PATCH",
            "href": "https://api.externalintegration.payex.com/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
            "rel": "update-paymentorder-abort",
            "contentType": "application/json"
        },
        {
            "method": "PATCH",
            "href": "https://ecom.externalintegration.payex.com/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
            "rel": "update-paymentorder-expandinstrument",
            "contentType": "application/json"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/paymentmenu/5a17c24e-d459-4567-bbad-aa0f17a76119?_tc_tid=30f2168171e142d38bcd4af2c3721959",
            "rel": "redirect-paymentorder",
            "contentType": "text/html"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/paymentmenu/core/scripts/client/px.paymentmenu.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119&culture=nb-NO&_tc_tid=30f2168171e142d38bcd4af2c3721959",
            "rel": "view-paymentorder",
            "contentType": "application/javascript"
        }
    ]
}

Response

The response should include this (abbreviated for brevity):

Response

Copy json to clipboard

1
2

HTTP/1.1 201 Created
Content-Type: application/json

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

{
    "paymentorder": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce"
    },
    "operations": [
        {
            "href": "&_tc_tid=30f2168171e142d38bcd4af2c3721959",
            "rel": "view-paymentorder",
            "method": "GET",
            "contentType": "application/javascript"
        }
    ]
}

The paymentorder object is abbreviated since it’s just the id and operations we are interested in. Store the id of the Payment Order in your system to look up status on the completed payment later.

Then find the view-paymentorder operation and embed its href in a <script> element. That script will then load the Seamless View for the Payment Menu. We will look into how to hook that up next.

Step 2: Display the Payment Menu

To load the payment menu from the JavaScript URL obtained in the back end API response, it needs to be set as a script element’s src attribute in an HTML document.

You can cause a page reload and do this with backend-rendered 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. We will demonstrate how to do a JavaScript-based integration below.

First the minimum HTML required to initialize the Payment Menu:

HTML

1
2
3
4
5
6
7
8
9
10
11

<!DOCTYPE html>
<html>
    <head>
        <title>Swedbank Pay Payment Menu v2</title>
    </head>
    <body>
        <div id="payment-menu"></div>
        <!-- Here you can specify your own JavaScript file -->
        <script src="<Your-JavaScript-File>"></script>
    </body>
</html>

What happens inside <Your-JavaScript-File> should look something alike the following:

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

var request = new XMLHttpRequest();
request.addEventListener('load', function () {
    response = JSON.parse(this.responseText);
    var script = document.createElement('script');
    // The JavaScript expects a JSON response looking like the created
    // Payment Order, containing the operation 'view-paymentorder.
    var operation = response.operations.find(function (o) {
        return o.rel === 'view-paymentorder';
    });
    script.setAttribute('src', operation.href);
    script.onload = function () {
        // Initialize the Payment Menu and inject it into the 'payment-menu'
        // container <div> defined in the HTML document above.
        payex.hostedView.paymentMenu({
            container: 'payment-menu',
            culture: 'sv-SE'
        }).open();
    };
    // Append the Payment Menu script to the <head>
    var head = document.getElementsByTagName('head')[0];
    head.appendChild(script);
});
// You should replace the address here with your own backend endpoint.
request.open('POST', '<Your-Backend-Endpoint>', true);
request.setRequestHeader('Content-Type', 'application/json; charset=utf-8');
// We will send an object containing the amount the Payment Order should be
// created with. This should of course not be hard coded and you may want to
// send more data from the front-end to the back-end to create a Payment Order
// for your particular use-case.
request.send(JSON.stringify({ amount: 1200 }));

Monitoring The Script URL

If you choose to stay with Seamless View, please take the following under advisement.

To ensure compliance, we recommend implementing Content Security Policy rules to monitor and authorize scripts.

Merchants must whitelist the following domains to restrict browser content retrieval to approved sources. While https://.payex.com and https://.swedbankpay.com cover most payment methods, digital wallets such as Apple Pay, Click to Pay, and Google Pay are delivered via Payair. Alongside the Payair URL, these wallets may also generate URLs from Apple, Google, MasterCard, and Visa. See the table below for more information.

When it comes to ACS URLs, nothing is loaded from the ACS domain in the merchant’s end. It will either happen within Swedbank Pay’s domain or as a redirect, which will repeal the merchant’s CSP.

The list below includes important URLs, but may not be exhaustive. Merchants need to stay up to date in case of URL changes, or if you need to whitelist URLs not listed here.

For further details, refer to section 4.6.3 and 11.6.1 in this PCI-DSS document.

How Seamless View Looks

This should bring up the Payment Menu in a Seamless View. It should look like this, depending on whether the payer is identified (top) or a guest user (bottom):

When the payer completes the payment, the Payment Menu script will be signaled and a full redirect to the completeUrl sent in with the Payment Order will be performed. When the completeUrl on your server is hit, you can inspect the status on the stored paymentorder.id on the server, and then perform capture.

If the payment is a Sale or one-phase purchase, it will be automatically captured. A third scenario is if the goods are sent physically to the payer; then you should not do a capture until the goods are sent.

You may open and close the payment menu using .open() and .close() functions. You can also invoke .refresh() to update the Payment Menu after any changes to the order.

Below, you will see a complete overview of the payment menu process. Notice that there are two ways of performing the payment:

• Payer performs payment out of iframe.
• Payer performs payment within iframe.

sequenceDiagram
    participant Payer
    participant Merchant
    participant SwedbankPay as Swedbank Pay

rect rgba(138, 205, 195, 0.1)
            activate Payer
            note left of Payer: Payment Menu
            Payer ->>+ Merchant: Initiate Purchase
            deactivate Payer
            Merchant ->>+ SwedbankPay: POST /psp/paymentorders (paymentUrl, payer)
            deactivate Merchant
            SwedbankPay -->>+ Merchant: rel:view-paymentorder
            deactivate SwedbankPay
            Merchant -->>- Payer: Display Payment Menu on Merchant Page
            activate Payer
            Payer ->> Payer: Initiate Payment Menu Seamless View (open iframe)
            Payer -->>+ SwedbankPay: Show Payment UI page in iframe
            deactivate Payer
            SwedbankPay ->>+ Payer: Do payment logic
            deactivate SwedbankPay

                opt Payer perform payment out of iFrame
                    Payer ->> Payer: Redirect to 3rd party
                    Payer ->>+ 3rdParty: Redirect to 3rdPartyUrl URL
                    deactivate Payer
                    3rdParty -->>+ Payer: Redirect back to paymentUrl (merchant)
                    deactivate 3rdParty
                    Payer ->> Payer: Initiate Payment Menu Seamless View (open iframe)
                    Payer ->>+ SwedbankPay: Show Payment UI page in iframe
                    deactivate Payer
                    SwedbankPay ->> Payer: Do payment logic
                end

        SwedbankPay -->> Payer: Payment status
        deactivate SwedbankPay

            alt If payment is completed
              activate Payer
              Payer ->> Payer: Event: onPaymentCompleted
              Payer ->>+ Merchant: Check payment status
              deactivate Payer
              Merchant ->>+ SwedbankPay: GET <paymentorder.id>
              deactivate Merchant
              SwedbankPay ->>+ Merchant: rel: paid-paymentorder
              deactivate SwedbankPay
              opt Get PaymentOrder Details (if paid-paymentorder operation exist)
                activate Payer
                deactivate Payer
                Merchant ->>+ SwedbankPay: GET rel: paid-paymentorder
                deactivate Merchant
                SwedbankPay -->> Merchant: Payment Details
                deactivate SwedbankPay
              end
            end

            opt If payment is failed
              activate Payer
              Payer ->> Payer: Event: OnPaymentFailed
              Payer ->>+ Merchant: Check payment status
              deactivate Payer
              Merchant ->>+ SwedbankPay: GET {paymentorder.id}
              deactivate Merchant
              SwedbankPay -->>+ Merchant: rel: failed-paymentorder
              deactivate SwedbankPay
              opt Get PaymentOrder Details (if failed-paymentorder operation exist)
              activate Payer
              deactivate Payer
              Merchant ->>+ SwedbankPay: GET rel: failed-paymentorder
              deactivate Merchant
              SwedbankPay -->> Merchant: Payment Details
              deactivate SwedbankPay
              end
            end
        activate Merchant
        Merchant -->>- Payer: Show Purchase complete
            opt PaymentOrder Callback (if callbackUrls is set)
              activate Payer
              deactivate Payer
                  SwedbankPay ->> Merchant: POST Payment Callback
              end
            end