Swish – Redirect

Introduction

When the payer starts the purchase process, you make a POST request towards Swedbank Pay with the collected Purchase information. This will generate a payment object with a unique paymentID. You either receive a Redirect URL to a hosted page or a JavaScript source in response.
You need to redirect the payer to the payment page to enter the Swish registered mobile number. This triggers the initiation of a sales transaction.
Swedbank Pay handles the dialog with Swish and the payer confirms the purchase in the Swish app.
Swedbank Pay will redirect the payer’s browser to - or display directly in the iFrame - one of two specified URLs, depending on whether the payment session is followed through completely or cancelled beforehand. Please note that both a successful and rejected payment reach completion, in contrast to a cancelled payment.

The payer is redirected to Swedbank Pay hosted pages and prompted to insert their phone number to initiate the sales transaction.

Swish is a one-phase payment method that is based on sales transactions not involving capture or cancellation operations.

Paying with Swish using Swedbank Pay

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

All valid options when posting in a payment with operation equal to Purchase. The Purchase example shown below.

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.

Redirect Request

Request

1
2
3

POST /psp/swish/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
41
42
43
44

{
    "payment": {
        "operation": "Purchase",
        "intent": "Sale",
        "currency": "SEK",
        "prices": [
            {
                "type": "Swish",
                "amount": 1500,
                "vatAmount": 0
            }
        ],
        "description": "Test Purchase",
        "userAgent": "Mozilla/5.0...",
        "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",
            "logoUrl": "https://example.com/logo.png",
            "termsOfServiceUrl": "https://example.com/terms.pdf"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "ref-123456",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-123456",
            "subsite": "MySubsite"
        },
        "payer": {
            "payerReference": "AB1234",
        },
        "prefillInfo": {
            "msisdn": "+46739000001"
        }
    },
    "swish": {
        "enableEcomOnly": false,
        "paymentRestrictedToAgeLimit": 18,
        "paymentRestrictedToSocialSecurityNumber": "199710202392"
    }
}

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 `Purchase` operation is used in our example.
`intent`	`string`	`Sale`.
`currency`	`string`	`SEK`.
`prices`	`object`	The `prices` array lists the prices related to a specific payment.
`type`	`string`	`Swish`.
`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.
`paymentAgeLimit`	`integer`	Positive number sets required age limit to fulfill the payment.
`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`	`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.
`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`	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`	An object holding information which, when available, will be prefilled 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.
`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 in-app payments.
`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.

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
41
42
43
44
45
46
47

{
    "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",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.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" },
        "payers": { "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers" },
        "settings": { "id": "/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/settings" }
    },
    "operations": [
        {
            "method": "POST",
            "href": "https://api.externalintegration.payex.com/psp/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/sales",
            "rel": "create-sale"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/swish/payments/authorize/5a17c24e-d459-4567-bbad-aa0f17a76119",
            "rel": "redirect-sale",
        },
        {
            "method": "PATCH",
            "href": "https://api.externalintegration.payex.com/swish/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "rel": "update-payment-abort"
        },
    ]
}

Redirect Sequence Diagram

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 resource
    activate Merchant
    Merchant-->>-Browser: Response with redirectUrl
    activate Browser
    Browser->>-SwedbankPay: Redirect to Payment page
    note left of SwedbankPay: Redirect to Swedbank Pay
    activate Browser
    Browser->>-SwedbankPay: Enter mobile number
    activate Merchant
    Merchant->>-SwedbankPay: POST <Sale transaction>
    activate SwedbankPay
    SwedbankPay-->>-Merchant: Transaction Resource
    activate SwedbankPay
    SwedbankPay--x-Browser: Tell payer to open Swish app
    Swish_API->>Swish_App: Ask for payment confirmation
    activate Swish_App
    Swish_App-->>-Swish_API: Payer confirms payment
    activate Swish_API

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

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