Swish

Seamless View

schedule 10 min read

The Seamless View scenario gives your customers the opportunity to pay with Swish directly within your webshop. This gives the payer a frictionless experience as we are handling the payment in the implemented iframe on your page.

Swish Seamless View integration flow

  1. When the payer starts the purchase process, you make a POST request towards Swedbank Pay with the collected Purchase information. view-sales is a rel value in one of the operations, sent as a response from Swedbank Pay to the Merchant.
  2. Open iframe creates the Swedbank Pay hosted iframe.
  3. Show payer UI page in iframe displays the payment window as content inside of the iframe. The payer can insert mobile information for authorization.
  4. Event: OnPaymentComplete is when the payment is complete. Please note that both a successful and rejected payment reach completion, in contrast to a cancelled payment.
  5. To get the transaction result, you need to follow up with a GET request using the paymentID received in the first step.
  6. If CallbackURL is set you will receive a payment callback when the Swish dialogue is completed, and you will have to make a GET request to check the payment status.

screenshot of the seamless view swish payment page

Step 1: Create a Purchase

A Purchase payment is a straightforward way to charge the card of the payer. You need to make a POST request towards Swedbank Pay as shown below to create a purchase. An example of an expanded POST request is available in the other features section. This will generate a payment object with a unique paymentID. You will receive a JavaScript source in response.

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 Swish as payment instrument.

The URL should represent the page of where the Payment 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.

info

Please note that the paymentUrl must be able to invoke the same JavaScript URL from the same Payment as the one that initiated the payment process originally, so it should include some sort of state identifier in the URL. The state identifier is the ID of the order, shopping cart or similar that has the URL of the Payment stored.

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

warning

GDPR

GDPR sensitive data such as email, phone numbers and social security numbers must not be used directly in request fields such as payerReference. If it is necessary to use GDPR sensitive data, it must be hashed and then the hash can be used in requests towards Swedbank Pay.

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
POST /psp/swish/payments HTTP/1.1
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "payment": {
        "operation": "Purchase",
        "intent": "Sale",
        "currency": "SEK",
        "prices": [{
                "type": "Swish",
                "amount": 1500,
                "vatAmount": 0
            }
        ],
        "description": "Test Purchase",
        "generatePaymentToken": false,
        "generateRecurrenceToken": false,
        "payerReference": "AB1234",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "urls": {
            "hostUrls": [ "https://example.com" ],
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-canceled",
            "paymentUrl": "https://example.com/perform-payment",
            "callbackUrl": "https://example.com/payment-callback",
            "logoUrl": "https://example.com/payment-logo.png",
            "termsOfServiceUrl": "https://example.com/payment-terms.pdf"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "CD1234",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or123",
            "subsite": "MySubsite"
        },
        "prefillInfo": {
            "msisdn": "+46987654321"
        }
    },
    "swish": {
        "enableEcomOnly": false,
        "paymentRestrictedToAgeLimit": 18,
        "paymentRestrictedToSocialSecurityNumber": "199710202392"
    }
}
Required Field Type Description
check payment object The payment object contains information about the specific payment.
check └➔ operation string The operation that the payment is supposed to perform. The Purchase operation is used in our example. Take a look at the create swish payment section for a full examples of the following operation options: Purchase.
check └➔ intent string AutoCapture. A one phase option that enable capture of funds.
check └➔ currency string SEK
check └➔ prices object The prices resource lists the prices related to a specific payment.
check └─➔ type string Use the generic type CreditCard if you want to enable all card brands supported by merchant contract. Use card brands like Visa (for card type Visa), MasterCard (for card type Mastercard) and others if you want to specify different amount for each card brand. If you want to use more than one amount you must have one instance in the prices node for each card brand. You will not be allowed to both specify card brands and CreditCard at the same time in this field. See the Prices resource and prices object types for more information.
check └─➔ amount integer The amount (including VAT, if any) to charge the payer, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.
check └─➔ vatAmount integer The payment’s VAT (Value Added Tax) amount, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The vatAmount entered will not affect the amount shown on the payment page, which only shows the total amount. This field is used to specify how much ofthe total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.
  └➔ paymentAgeLimit integer Positive number sets requried age limit to fulfill the payment.
check └➔ description string(40) A 40 character length textual description of the purchase.
  └➔ payerReference string The reference to the payer from the merchant system, like e-mail address, mobile number, customer number etc.
check └➔ userAgent string The User-Agent string of the payer’s web browser.
check └➔ language string sv-SE, nb-NO or en-US.
check └➔ urls object The urls resource lists urls that redirects users to relevant sites.
  └─➔ hostUrls array The array of URLs valid for embedding of Swedbank Pay Hosted Views. If not supplied, view-operation will not be available.
check └─➔ completeUrl string The URL that Swedbank Pay will redirect back to when the payer has completed his or her interactions with the payment. This does not indicate a successful payment, only that it has reached a final (complete) state. A GET request needs to be performed on the payment to inspect it further. See completeUrl for details.
  └─➔ cancelUrl string The URI to redirect the payer to if the payment is canceled. Only used in redirect scenarios. Can not be used simultaneously with paymentUrl; only cancelUrl or paymentUrl can be used, not both.
  └─➔ paymentUrl string The URI that Swedbank Pay will redirect back to when the view-operation needs to be loaded, to inspect and act on the current status of the payment. Only used in Seamless Views. If both cancelUrl and paymentUrl is sent, the paymentUrl will used. See paymentUrl for details.
  └─➔ callbackUrl string The URL that Swedbank Pay will perform an HTTP POST against every time a transaction is created on the payment. See callback for details.
  └─➔ logoUrl string The URL that will be used for showing the customer logo. Must be a picture with maximum 50px height and 400px width. Requires HTTPS.
  └─➔ termsOfServiceUrl string The URI to the terms of service document the payer must accept in order to complete the payment. Note that this field is not required unless generateReferenceToken or generateRecurrenceToken is also submitted in the request. This is the Merchants, not the Swedbank Pay Terms of Service. HTTPS is a requirement.
check └➔ payeeInfo object The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details.
check └─➔ payeeId string This is the unique id that identifies this payee (like merchant) set by Swedbank Pay.
check └─➔ payeeReference string(50*) A unique reference from the merchant system. It is set per operation to ensure an exactly-once delivery of a transactional operation. See payeeReference for details.
  └─➔ payeeName string The payee name (like merchant name) that will be displayed when redirected to Swedbank Pay.
  └─➔ productCategory string A product category or number sent in from the payee/merchant. This is not validated by Swedbank Pay, but will be passed through the payment process and may be used in the settlement process.
  └─➔ orderReference String(50) The order reference should reflect the order reference found in the merchant’s systems.
  └➔ prefillInfo object An object that holds prefill information that can be inserted on the payment page.
  └─➔ msisdn string Number will be prefilled on payment page, if valid. The mobile number must have a country code prefix and be 8 to 15 digits in length.
  └─➔ subsite String(40) The subsite field can be used to perform split settlement on the payment. The subsites must be resolved with Swedbank Pay reconciliation before being used.If you send in an unknown subsite value, it will be ignored and the paymentwill be settled using the merchant’s default settlement account.
  └➔ swish object An object that holds different scenarios for Swish payments.
  └─➔ enableEcomOnly boolean true if to only enable Swish on browser-based transactions.; otherwise false to also enable Swish transactions via mobile app.
  └─➔ paymentRestrictedToAgeLimit integer Positive number that sets the required age needed to fulfill the payment. To use this feature it has to be configured in the contract.
  └─➔ paymentRestrictedToSocialSecurityNumber string When provided, the payment will be restricted to a specific social security number to make sure its the same logged in customer who is also the payer. Format: yyyyMMddxxxx. To use this feature it has to be configured in the contract.

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
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": {
      "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
      "number": 1234567890,
      "instrument": "Swish",
      "created": "2016-09-14T13:21:29.3182115Z",
      "updated": "2016-09-14T13:21:57.6627579Z",
      "state": "Ready",
      "operation": "Purchase",
      "intent": "Sale",
      "currency": "SEK",
      "amount": 0,
      "remainingCaptureAmount": 1500,
      "remainingCancellationAmount": 1500,
      "remainingReversalAmount": 0,
      "description": "Test Purchase",
      "payerReference": "AB1234",
      "initiatingSystemUserAgent": "PostmanRuntime/7.20.1",
      "userAgent": "Mozilla/5.0...",
      "language": "sv-SE",
      "prices": { "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices" },
      "transactions": { "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions" },
      "captures": { "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures" },
      "reversals": { "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals" },
      "cancellations": { "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations" },
      "urls" : { "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls" },
      "payeeInfo" : { "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo" },
      "settings": { "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/settings" }
    },
    "operations": [
      {
        "href": "https://api.externalintegration.payex.com/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "rel": "update-payment-abort",
        "method": "PATCH",
        "contentType": "application/json"
      },
      {
        "method": "POST",
        "href": "https://api.externalintegration.payex.com/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/sales",
        "rel": "create-sale"
      },
      {
        "href": "https://ecom.externalintegration.payex.com/swish/payments/authorize/5a17c24e-d459-4567-bbad-aa0f17a76119",
        "rel": "redirect-sale",
        "method": "GET",
        "contentType": "text/html"
      },
      {
        "method": "GET",
        "href": "https://ecom.dev.payex.com/swish/core/scripts/client/px.swish.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119",
        "rel": "view-sales",
        "contentType": "application/javascript"
      },
      {
        "method": "GET",
        "href": "https://ecom.externalintegration.payex.com/swish/core/scripts/client/px.swish.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119",
        "rel": "view-payment",
        "contentType": "application/javascript"
      }
    ]
}

The key information in the response is the view-sales operation. You will need to embed its href in a <script> element. The script will enable loading the payment page in an iframe in our next step.

Step 2: Display the Payment Window

You need to embed the script source on your site to create a hosted-view in an iframe; so that the payer can enter the required information in a secure Swedbank Pay hosted environment. A simplified integration has these following steps:

  1. Create a container that will contain the Seamless View iframe: <div id="swedbank-pay-seamless-view-page">.
  2. Create a <script> source within the container. Embed the href value obtained in the POST request in the <script> element. Example:
1
<script id="payment-page-script" src="https://ecom.dev.payex.com/swish/core/scripts/client/px.swish.client.js"></script>

The previous two steps gives this HTML:

HTML

1
2
3
4
5
6
7
8
9
10
11
12
13
<!DOCTYPE html>
<html>
    <head>
        <title>Swedbank Pay Seamless View is Awesome!</title>
        <!-- Here you can specify your own javascript file -->
        <script src=<YourJavaScriptFileHere>></script>
    </head>
    <body>
        <div id="swedbank-pay-seamless-view-page">
          <script id="payment-page-script" src="https://ecom.dev.payex.com/swish/core/scripts/client/px.swish.client.js"></script>
        </div>
    </body>
</html>

Lastly, initiate the Seamless View with a JavaScript call to open the iframe embedded on your website.

HTML

1
2
3
4
5
6
7
<script language="javascript">
    payex.hostedView.swish({
        // The container specifies which id the script will look for to host the
        // iframe component.
        container: "swedbank-pay-seamless-view-page"
    }).open();
</script>

Seamless View Purchase flow

The sequence diagram below shows the requests you have to send to Swedbank Pay to make a purchase. The Callback response is a simplified example in this flow. Go to the Callback section to view the complete flow.

sequenceDiagram
    activate Browser
    Browser->>-Merchant: Start Purchase
    activate Merchant
    Merchant->>-SwedbankPay: POST <Swish create payment> (operation=PURCHASE)
    activate SwedbankPay
    note left of Merchant: First API request
    SwedbankPay-->>-Merchant: Payment Response with rel:view-payment
    activate Merchant
    Merchant->>Merchant: Build html with view-payment script
    Merchant-->>-SwedbankPay: Init iFrame
    activate SwedbankPay
    SwedbankPay->>-SwedbankPay: Enter mobile number
    activate SwedbankPay
    SwedbankPay->>-Merchant: Tell payer to open Swish app
    Swish_API->>Swish_App: Ask for payment confirmation
    activate Swish_App
    Swish_App-->>-Swish_API: Payer confirms payment

        alt Callback
        activate SwedbankPay
        SwedbankPay-->>Swish_API: Callback response
        SwedbankPay->>-Merchant: Transaction callback
        end

    activate Merchant
    Merchant->>-SwedbankPay: GET <Swish payment>
    activate SwedbankPay
    SwedbankPay-->>-Merchant: Payment response
    activate Merchant
    Merchant->>-Browser: Payment Status