MobilePay Online – Seamless View

Step 1: Create A purchase

When properly set up in your merchant/webshop site and the payer starts the purchase process, you need to make a POST request towards Swedbank Pay with your Purchase information. This will generate a payment object with a unique paymentID. An example of an abbreviated POST request is provided below. You will receive a response in which you can find the JavaScript source in the view-payment operation.

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.

Seamless View Request

Request

1
2
3
4

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

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

{
    "payment": {
        "operation": "Purchase",
        "intent": "Authorization",
        "currency": "DKK",
        "prices": [
            {
                "type": "MobilePay",
                "amount": 1500,
                "vatAmount": 0,
            }
        ],
        "description": "MobilePay Test",
        "userAgent": "Mozilla/5.0",
        "language": "da-DK",
        "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://example.com/payment-callback",
            "logoUrl": "https://example.com/path/to/logo.png",
            "termsOfServiceUrl": "https://example.com/terms.pdf"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "payeeReference",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-12456",
            "subsite": "MySubsite"
        },
        "payer": {
            "payerReference": "AB1234",
        },
        "prefillInfo": {
            "msisdn": "+4598765432"
        }
    },
    "mobilepay": {
        "shoplogoUrl": "https://example.com/shoplogourl.png"
    }
}

Show fields

Field	Data type	Description
`payment`	`object`	The payment object.
`operation`	`string`	`Purchase`
`intent`	`string`	`Authorization`
`currency`	`string`	`NOK`, `SEK`, `DKK`, `USD` or `EUR`.
`prices`	`object`	The prices object.
`type`	`string`	Use the value ``.See the `prices` resource for more information.
`amount`	`integer`	The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: `10000` = `100.00` DKK, `5000` = `50.00` DKK.
`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` DKK, `5000` = `50.00` DKK. 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 of the total `amount` the VAT will be. Set to `0` (zero) if there is no VAT `amount` charged.
`feeAmount`	`integer`	If the amount given includes Fee, this may be displayed for the user in the payment page (redirect only).
`description`	`string(40)`	A 40 character length textual description of the purchase.
`userAgent`	`string`	The user agent of the payer. Should typically be set to the value of the `User-Agent` header sent by the payer’s web browser.
`language`	`string`	`da-DK`, `fi-FI` or `en-US`.
`urls`	`object`	The URLs object containing the urls used for this payment.
`hosturls`	`array`	The array of URLs valid for embedding of Swedbank Pay Seamless Views. If not supplied, view-operation will not be available.
`completeUrl`	`string`	The URL that Swedbank Pay will redirect back to when the payer has completed their 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 URL that Swedbank Pay will redirect back to when the user presses the cancel button in the payment page.
`paymentUrl`	`string`	The `paymentUrl` represents the URL 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, such as when the payer is redirected out of the Seamless View (the `<iframe>`) and sent back after completing the payment. `paymentUrl` is only used in Seamless Views and should point to the page of where the Payment Order Seamless View is hosted. If both `cancelUrl` and `paymentUrl` is sent, the `paymentUrl` will used.
`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.
`termsOfServiceUrl`	`string`	The URL to the terms of service document which the payer must accept in order to complete the payment. HTTPS is a requirement.
`payeeInfo`	`object`	This object contains the identificators of the payee of this payment.
`payeeId`	`string`	This is the unique id that identifies this payee (like merchant) set by Swedbank Pay.
`payeeReference`	`string`	A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the `transaction.number` or the `payeeReference` is sent to the acquirer. If Swedbank Pay handles the settlement, the `transaction.number` is sent and the `payeeReference` must be in the format of `A-Za-z0-9` and `string(30)`. If you handle the settlement, Swedbank Pay will send the `payeeReference` and it will be limited to the format of `string(12)`. All characters must be digits.
`payeeName`	`string`	The payee name (like merchant name) that will be displayed when redirected to Swedbank Pay.
`productCategory`	`string(50)`	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.
`subsite`	`string(40)`	The `subsite` field can be used to perform split settlement on the payment. The different `subsite` values must be resolved with Swedbank Pay reconciliation before being used. If you send in an unknown `subsite` value, it will be ignored and the payment will be settled using the merchant’s default settlement account. Must be in the format of `A-Za-z0-9`.
`payer`	`string`	The `payer` object, containing information about the payer.
`payerReference`	`string`	The reference to the payer from the merchant system, like e-mail address, mobile number, customer number etc. Mandatory if `generateRecurrenceToken`, `RecurrenceToken`, `generatePaymentToken` or `paymentToken` is `true`.
`prefillInfo`	`object`	An object that holds prefill information that can be inserted on the payment page.
`msisdn`	`string`	Number will be prefilled on MobilePays page, if valid. Only Danish and Finnish phone numbers are supported. The country code prefix is +45 and +358 respectively.
`mobilepay.shoplogoUrl`	`string`	URI to logo that will be visible at MobilePay Online. For it to display correctly in the MobilePay app, the image must be 250x250 pixels, a png or jpg served over a secure connection using https, and be publicly available. This URI will override the value configured in the contract setup.

Seamless View Response

Response

1
2

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

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

{
    "payment": {
        "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 72100003079,
        "created": "2018-09-05T14:18:44.4259255Z",
        "instrument": "MobilePay",
        "operation": "Purchase",
        "intent": "Authorization",
        "state": "Ready",
        "currency": "DKK",
        "amount": 0,
        "description": "MobilePay Test",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "userAgent": "Mozilla/5.0",
        "language": "da-DK",
        "prices": { "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices" },
        "urls": { "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls" },
        "payeeInfo": { "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeinfo" },
        "payers": { "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers" }
    },
    "operations": [
        {
            "method": "PATCH",
            "href": "https://api.externalintegration.payex.com/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "rel": "update-payment-abort"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/mobilepay/core/scripts/client/px.mobilepay.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119&Culture=da-DK",
            "rel": "view-authorization",
            "contentType": "application/javascript"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/mobilepay/core/scripts/client/px.mobilepay.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119&Culture=da-DK",
            "rel": "view-payment",
            "contentType": "application/javascript"
        }
    ]
}

The key information in the response is the view-payment 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.

Please note that nested iframes (an iframe within an iframe) are unsupported.

Step 2: Display the payment window

You need to embed the script source on your site to create a Seamless 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:

Create a container that will contain the Seamless View iframe: <div id="swedbank-pay-seamless-view-page">.
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.externalintegration.payex.com/mobilepay/core/ scripts/client/px.mobilepay.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/mobilepay/core/scripts/client/px.mobilepay.client.js"></script>
        </div>
    </body>
</html>

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

JavaScript

1
2
3
4
5
6
7

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

MobilePay Online Seamless View flow

The sequence diagram below shows the two requests you have to send to Swedbank Pay to make a purchase. The links will take you directly to the API description for the specific request.

sequenceDiagram
    participant Merchant
    participant SwedbankPay as Swedbank Pay
    participant MobilePayApp as MobilePay App
    participant MobilePayApi as MobilePay API

    activate Merchant
    Merchant->>-SwedbankPay: POST /psp/mobilepay/payments
    activate SwedbankPay
    note left of Merchant: First API request
    SwedbankPay-->>-Merchant: Payment response with rel: view-payment
    activate Merchant
    Merchant->>-SwedbankPay: Script init of iFrame
    activate SwedbankPay
    SwedbankPay-->>-Merchant: Display Payment Page
    activate Merchant
    Merchant->>Merchant: Init payment
    Merchant->>-SwedbankPay: Init request

    activate SwedbankPay
    SwedbankPay->>+MobilePayApi: POST <rel:create-authorization>
    activate MobilePayApi
    MobilePayApi-->>+SwedbankPay: Response
    activate SwedbankPay
    SwedbankPay-->>-Merchant: Display instructions page

    MobilePayApi-->>-MobilePayApp: Confirm Payment UI
    activate MobilePayApp
    MobilePayApp-->>MobilePayApp: Confirmation Dialog
    MobilePayApp-->>-MobilePayApi: Confirmation

    activate MobilePayApi
    MobilePayApi->>-SwedbankPay: Authorize Payment
    activate SwedbankPay
    SwedbankPay-->>-SwedbankPay: Process Payment
    activate SwedbankPay
    SwedbankPay-->>-MobilePayApi: Process Payment Response
    activate MobilePayApi
    MobilePayApi-->>-MobilePayApp: Transaction Status

    activate Merchant
    Merchant->>- SwedbankPay: GET <MobilePay payment>
    activate  SwedbankPay
    SwedbankPay-->>-Merchant: Payment response
    activate Merchant
    Merchant-->>-Merchant: Display payment Status

When the payer starts the purchase process, you make a POST request towards Swedbank Pay with the collected Purchase information.
rel: view-payment is a value in one of the operations, sent as a response from Swedbank Pay to the Merchant.
Open iFrame creates the Swedbank Pay Seamless View. The Seamless View displays the payment page as content inside of the iFrame.
A POST request is sent to the MobilePay API with the mobile number (optional) for authorization.
Swedbank Pay handles the dialog with MobilePay and the payer confirms the purchase in the MobilePay app.
After the purchase has been authorized, the payer will be redirected back to the merchant, where the status can be checked to ensure the payment was successful.