Trustly – Redirect

Introduction

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 resource with a unique id. You will receive a redirect URL to a Swedbank Pay payment page (redirect-sale operation).
You need to redirect the payer’s browser to that specified URL so that the payer can enter the payment details in a secure Swedbank Pay environment.
Swedbank Pay will redirect the payer’s browser to one of two specified URLs, depending on whether the payment session is followed through completely. Please note that both a successful and rejected payment reach completion.
When you detect that the payer reach your completeUrl, you need to do a GET request to receive the state of the transaction, containing the id URL generated in the first step, to receive the state of the transaction.
The Trustly window will open inside the same frame, even for the redirect integration. This means that you wont have to think about your payer being redirected to another site, and hense no need to redirect them back.

Step 1: Create A Payment

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.

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.

To initiate the payment process, you need to make a POST request to Swedbank Pay.

Redirect Request

Request

1
2
3

POST /psp/trustly/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

{
    "payment": {
        "operation": "Purchase",
        "intent": "Sale",
        "currency": "SEK",
        "prices": [
            {
                "type": "Trustly",
                "amount": 1500,
                "vatAmount": 0
            }
        ],
        "description": "Test Purchase",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "urls": {
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-cancelled",
            "hostUrls": [ "https://example.com" ],
            "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"
        },
        "payer": {
            "payerReference": "AB1234",
        },
        "prefillInfo": {
            "firstName": "Ola",
            "lastName": "Nordmann"
        }
    }
}

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. For Trustly, this will always be `Purchase` as it is currently the only available operation.
`intent`	`string`	`Sale` is the only intent option for Trustly. Performs the payment when the payer gets redirected and completes the payment, and is followed by a reversal of funds.
`currency`	`string`	`SEK`, `EUR`. The currency of the provided `amount`.
`prices`	`object`	The `prices` resource lists the prices related to a specific payment.
`type`	`string`	Use the `Trustly` type here
`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.
`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.
`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`	`array`	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.
`hostUrl`	`array`	The array of URLs valid for embedding of Swedbank Pay Seamless View. If not supplied, view-operation will not be available.
`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 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(30*)`	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 a 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`	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.

Redirect 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/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",
        "amount": 0,
        "description": "Test Purchase",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "prices": { "id": "/psp/trustly/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices" },
        "urls": { "id": "/psp/trustly/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls" },
        "payeeInfo": { "id": "/psp/trustly/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeinfo" },
        "payers": { "id": "/psp/trustly/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers" },
        "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"
        }
    ]
}

Redirect Sequence Diagram

This is an example of the Redirect scenario. For other integrations, take a look at the respective sections. The sequence diagram below shows the two requests you have to send to Swedbank Pay to make a purchase.

Swedbank Pay Trustly Payments uses the Deposit to perform a payment. After this, the payer will be presented with the returned iframe URL in order to perform the payment with their preferred bank. Once the user has completed the payment, Swedbank Pay will receive a notification asynchronously from Trustly, hence why the UI will initiate polling toward our back-end. The payment status after being redirect to completeUrl will then indicate if the payment was successful or not, or if the payment is still in progress. If the payment is still in progress, when reaching completeUrl, the Swedbank Pay has then not received a notification from Trustly that the payment has gone through yet.

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 <Trustly Payment> (operation=Purchase)
    activate SwedbankPay
    SwedbankPay-->>-Merchant: payment resource
    activate Merchant
    Merchant-->>-Consumer: authorization page
    activate Consumer
    note left of Consumer: redirect to Swedbank Pay
    Consumer->>-SwedbankPay: enter consumer details
    activate SwedbankPay
    SwedbankPay-->-Trustly: perform payment in Trustly
    activate Trustly
    Trustly-->>-Consumer: redirect to merchant
    activate Consumer
    note left of Consumer: redirect back to Merchant
    Consumer->>-Merchant: access merchant page
    activate Merchant
    note left of Merchant: Second API request
    Merchant->>-SwedbankPay: GET <Trustly payment>
    activate SwedbankPay
    SwedbankPay-->>-Merchant: payment resource
    activate Merchant
    Merchant-->>-Consumer: display purchase result

Options After Posting A Payment

Head over to after payment to see what you can do when a payment is completed. Here you will also find info on Abort and Reversal.