Trustly

Seamless View

schedule 10 min read

The Seamless View scenario represents the opportunity to implement Trustly directly in your webshop.

Introduction

Seamless View provides an integration of the payment process directly on your website. This solution offers a smooth shopping experience with Swedbank Pay Payments 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 website.

screenshot of the Trustly payment window

link

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

A Trustly payment is a straightforward way to perform a direct-bank payment.

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 Payment resource.

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

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

{
    "payment": {
        "operation": "Purchase",
        "intent": "Sale",
        "currency": "SEK",
        "prices": [
            {
                "type": "Trustly",
                "amount": 1500,
                "vatAmount": 0
            }
        ],
        "description": "Test Purchase",
        "payerReference": "SomeReference",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "urls": {
            "completeUrl": "https://example.com/payment-completed",
            "callbackUrl": "https://example.com/payment-callback",
            "logoUrl": "https://example.com/logo.png",
            "termsOfServiceUrl": "https://example.com/terms.pdf"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "PR123",
            "payeeName": "Merchant1",
            "productCategory": "PC1234",
            "subsite": "MySubsite"
        },
        "prefillInfo": {
            "firstName": "Ola",
            "lastName": "Nordmann"
        }
    }
}
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. For Trustly, this will always be Purchase as it is currently the only available operation.
check └➔ intent string Sale is the only intent option for Trustly. Performs the payment when the end-user gets redirected and completes the payment.
check └➔ currency string SEK, EUR. The currency of the provided amount.
check └➔ prices object The prices resource lists the prices related to a specific payment.
check └─➔ type string Use the Trustly type here
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.
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 consumer’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.
  └─➔ hostUrl array The array of URLs valid for embedding of Swedbank Pay Seamless View. 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.
  └─➔ 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.
  └─➔ paymentUrl string The URI that Swedbank Pay will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment.
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(30*) 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 to consumer 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.
  └─➔ 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.
  └─➔ prefillInfo object Object representing information of what the UI text fields should be populated with
  └─➔ firstName string Prefilled value to put in the first name text box.
  └─➔ lastName string Prefilled value to put in the last name text box.

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

{	
    "payment": {	
        "id": "/psp/trustly/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",	
        "number": 99590008046,	
        "created": "2020-05-26T12:31:19.3106483Z",	
        "updated": "2020-05-26T12:31:19.4513673Z",	
        "instrument": "Trustly",	
        "operation": "Purchase",	
        "intent": "Sale",	
        "state": "Ready",	
        "currency": "SEK",	
        "prices": {	
            "id": "/psp/trustly/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices"	
        },	
        "amount": 0,	
        "description": "Test Purchase",	
        "payerReference": "SomeReference",	
        "initiatingSystemUserAgent": "PostmanRuntime/7.25.0",	
        "userAgent": "Mozilla/5.0...",	
        "language": "sv-SE",	
        "urls": {	
            "id": "/psp/trustly/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls"	
        },	
        "payeeInfo": {	
            "id": "/psp/trustly/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeinfo"	
        },	
        "metadata": {	
            "id": "/psp/trustly/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/metadata"	
        }	
    },	
    "operations": [	
        {	
            "method": "PATCH",	
            "href": "https://api.externalintegration.payex.com/psp/trustly/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",	
            "rel": "update-payment-abort"	
        },	
        {	
            "method": "POST",	
            "href": "https://api.externalintegration.payex.com/psp/trustly/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/sales",	
            "rel": "create-sale"	
        },	
        {	
            "method": "GET",	
            "href": "https://ecom.externalintegration.payex.com/trustly/payments/sales/8f3ba6c8f4e3f6125ae6c18bec15c612747cf2c35dc5cac35d4bebc10cf7317e",	
            "rel": "redirect-sale"	
        },	
        {	
            "method": "GET",	
            "href": "https://ecom.externalintegration.payex.com/trustly/core/scripts/client/px.trustly.client.js?token=8f3ba6c8f4e3f6125ae6c18bec15c612747cf2c35dc5cac35d4bebc10cf7317e&operation=sale",	
            "rel": "view-sales",	
            "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

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:

  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.externalintegration.payex.com/trustly/core/ scripts/client/px.trustly.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.externalintegration.payex.com/trustly/core/scripts/client/px.trustly.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
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.externalintegration.payex.com/trustly/core/scripts/client/px.trustly.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.trustly({
        // 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 Trustly payment process.

sequenceDiagram
    participant SwedbankPay as Swedbank Pay
    participant Merchant
    participant Consumer
    participant Trustly
    Consumer->>Merchant: Start purchase
    activate Merchant
    note left of Merchant: First API request
    Merchant->>-SwedbankPay: POST /psp/trustly/payments
    activate Merchant
    Merchant-->>-Consumer: Display all details and final price
    activate Consumer
    note left of Consumer: Open iframe ③
    Consumer->>Consumer: Input first name and last name
    Consumer->>-SwedbankPay: Confirm purchase
    activate SwedbankPay
    SwedbankPay->>-Trustly: Perform payment
    activate Trustly
    Trustly-->>-Merchant: Transaction result
    activate Merchant
    note left of Merchant: Second API request
    Merchant->>-SwedbankPay: GET <payment.id>
    activate SwedbankPay
    SwedbankPay-->>-Merchant: payment resource
    activate Merchant
    Merchant-->>-Consumer: Display result