Invoice – Seamless View

Availability: Note that this invoice integration is no longer available in Sweden. If you are a Swedish merchant and wish to offer invoice as a payment option, this has to be done through our payment order implementation.

Introduction

Seamless View provides an integration of the payment process directly on your website. This solution offers a smooth shopping experience with Swedbank Pay payment pages seamlessly integrated in an iframe on your website. The payer does not need to leave your webpage, since we are handling the payment in the iframe on your page.

How It Looks

screenshot of the invoice payment window

Callback URL: It is mandatory to set a callbackUrl in the POST request creating the payment. When callbackUrl is set, Swedbank Pay will send a POST request to this URL when the payer has fulfilled the payment. Upon receiving this POST request, a subsequent GET request towards the id of the payment generated initially must be made to receive the state of the transaction.

Step 1: Create The Payment

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.

A FinancingConsumer payment is a straightforward way to invoice a payer. It is followed up by posting a capture, cancellation or reversal transaction.

An example of an abbreviated POST request is provided below. Each individual field of the JSON document is described in the following section. An example of an expanded POST request is available in the other features section.

When properly set up in your merchant/webshop site and the payer starts the invoice process, you need to make a POST request towards Swedbank Pay with your invoice information. This will generate a payment object with a unique paymentID. You will receive a JavaScript source in response.

Seamless View Request

Request

1
2
3

POST /psp/invoice/payments HTTP/1.1
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

{
    "payment": {
        "operation": "FinancingConsumer",
        "intent": "Authorization",
        "currency": "SEK",
        "prices": [
            {
                "type": "Invoice",
                "amount": 1500,
                "vatAmount": 0
            }
        ],
        "description": "Test Invoice",
        "userAgent": "Mozilla/5.0...",
        "generatePaymentToken": false,
        "paymentToken": ""
        "language": "sv-SE",
        "urls": {
            "hosturls": [
                "https://example.com"
            ],
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-cancelled",
            "callbackUrl": "https://example.com/payment-callback",
            "termsOfServiceUrl": "https://example.com/payment-terms.pdf"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "CD1234",
            "payeeName": "Merchant1",
            "productCategory": "A123"
        },
        "payer": {
            "payerReference": "AB1234",
        },
    },
    "invoice": {
        "invoiceType": "PayExFinancingSe"
    }
}

Show fields

Field	Type	Description
`payment`	`object`	The `payment` object contains information about the specific payment.
`operation`	`string`	The operation that the `payment` is supposed to perform. The `FinancingConsumer` operation is used in our example.
`intent`	`string`	`Authorization`. Reserves the amount, and is followed by a cancellation or capture of funds.
`currency`	`string`	NOK or SEK.
`prices`	`object`	The `prices` resource lists the prices related to a specific payment.
`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` SEK, `5000` = `50.00` SEK.
`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 of the total `amount` the VAT will be. Set to `0` (zero) if there is no VAT `amount` charged.
`description`	`string(40)`	A 40 character length textual description of the purchase.
`generatePaymentToken`	`boolean`	`true` or `false`. Set this to `true` if you want to create a paymentToken for future use as One Click.
`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`	`sv-SE`, `nb-NO` or `en-US`.
`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 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 to redirect the payer to if the payment is cancelled. Only used in redirect scenarios. Can not be used simultaneously with`paymentUrl`; only cancelUrl or`paymentUrl`can be used, not both.
`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`	The `payeeInfo` object, containing information about the payee (the recipient of the money). See `payeeInfo` for details.
`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. In Invoice Payments `payeeReference` is used as an invoice/receipt number, if the `receiptReference` is not defined.
`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.
`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`.
`invoiceType`	`string`	`PayExFinancingSe`, `PayExFinancingNo` or `PayExFinancingFi` depending on which country you’re doing business with Swedbank Pay in. (Other external financing partner names must be agreed upon with Swedbank Pay.)

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

{
    "payment": {
        "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 1234567890,
        "instrument": "Invoice",
        "created": "YYYY-MM-DDThh:mm:ssZ",
        "updated": "YYYY-MM-DDThh:mm:ssZ",
        "operation": "FinancingConsumer",
        "intent": "Authorization",
        "state": "Ready",
        "currency": "SEK",
        "prices": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices"
        },
        "amount": 0,
        "description": "Test Purchase",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "urls": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls"
        },
        "payeeInfo": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeinfo"
        },
        "payers": {
           "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers"
        },
        "metadata": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/metadata"
        }
    },
    "operations": [
        {
            "method": "POST",
            "href": "https://api.externalintegration.payex.com/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/approvedlegaladdress",
            "rel": "create-approved-legal-address",
            "contentType": "application/json"
        },
        {
            "method": "POST",
            "href": "https://api.externalintegration.payex.com/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations",
            "rel": "create-authorization",
            "contentType": "application/json"
        },
        {
            "method": "PATCH",
            "href": "https://api.externalintegration.payex.com/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "rel": "update-payment-abort",
            "contentType": "application/json"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/invoice/payments/authorize/5a17c24e-d459-4567-bbad-aa0f17a76119",
            "rel": "redirect-authorization",
            "contentType": "text/html"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/invoice/core/scripts/client/px.invoice.client.js?5a17c24e-d459-4567-bbad-aa0f17a76119&operation=authorize",
            "rel": "view-authorization",
            "contentType": "application/javascript"
        }
    ]
}

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

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 payment details 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/invoice/core/ scripts/client/px.invoice.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/invoice/core/scripts/client/px.invoice.client.js"></script>
        </div>
    </body>
</html>

Loading The JavaScript

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.invoice({
        // The container specifies which id the script will look for to host the
        // iframe component.
        container: "swedbank-pay-seamless-view-page"
    }).open();
</script>

Purchase Flow

The sequence diagram below shows a high level description of the invoice process.

sequenceDiagram
    Payer->>Merchant: Start purchase
    activate Merchant
    note left of Merchant: First API request
    Merchant->>-SwedbankPay: POST /psp/invoice/payments ①
    activate SwedbankPay
    SwedbankPay-->>-Merchant: rel: view-authorization ②
    activate Merchant
    Merchant-->>-Payer: Display all details and final price
    activate Payer
    note left of Payer: Open iframe ③
    Payer->>Payer: Input email and mobile number
    Payer->>-Merchant: Confirm purchase
    activate Merchant
    note left of Merchant: Second API request
    Merchant->>-SwedbankPay: Post psp/invoice/authorization ④
    activate SwedbankPay
    SwedbankPay-->>-Merchant: Transaction result
    activate Merchant
    note left of Merchant: Third API request
    Merchant->>-SwedbankPay: GET <payment.id> ⑤
    activate SwedbankPay
    SwedbankPay-->>-Merchant: payment resource
    activate Merchant
    Merchant-->>-Payer: Display result

Note that the invoice will not be created/distributed before you have made a capture request.