Digital Payments – Instrument Mode

Instrument Mode

This feature is only available for merchants who have a specific agreement with Swedbank Pay.

With “Instrument Mode”, the Payment Menu will display only one specific payment method instead of all those configured on your merchant account. The PaymentOrder resource works just like it otherwise would, allowing you to remain largely indifferent to the payment method in use. To use the feature you need to add the instrument field in the request as shown in the example below.

It is important to only create one paymentOrder for each purchase, even if the payer changes their mind and wants to use another payment method. This is because we don’t allow creating multiple paymentOrders with the same payeeReference. If this happens, you should use the PATCH request below to reflect what the payer has chosen instead of creating a new paymentOrder. This way, you can still use the same payeeReference.

If you don’t want to use Swedbank Pay’s Payment Menu (e.g. building your own payment menu), or have multiple payment providers on your site, we strongly recommend that you implement this functionality. In this case you should use the instrument field to enforce which payment method to show. If you have an agreement with Swedbank Pay for both Card and Swish/Vipps processing, and the payer chooses either of these methods, you should add the instrument parameter with the specific payment method.

Eligibility Check

If you want to build your own menu and display at least one wallet like Apple Pay, Click to Pay or Google Pay™, you need to do an eligibility check. This is to ensure that the wallet is supported on the payer’s device or browser. The check helps you streamline the process, removing payment methods that would give the payer an error message or not be displayed in the menu.

Using The Script

Swedbank Pay provides a script to do this check, with the URL ecom.<environment>.payex.com/checkout/core/integration. Environments available for you are externalintegration and production, and you can switch integration between checkout and paymentmenu. Follow these links for test environment and production environment Checkout scripts.

Add the script tag to your website and perform the javascript call await payex.getAcceptedWallets(). We will return a string array with the wallets eligible for that purchase. The format will e.g. be ["applepay", "googlepay"].

The check should be done as close as possible to the moment the payer wants to open the payment UI. If the payer is in a situation where they may change their browser and/or device between the check is done to the payment UI is opened, the eligibility check may not be accurate to what the UI is displaying.

Additional Details

We strongly advice against using your own script to perform eligibility checks. Using our check will ensure that what we will display in the menu matches what you offer to the payer. If you do use your own, make sure that it is stricter than the one we provide.

If you are not building your own menu or don’t offer these wallets, there is no need to run the script to do the check.

Instrument Mode Request

An example with invoice as the payment method of choice.

Request

1
2
3
4

POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.x/2.0      // Version optional for 3.0 and 2.0

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
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

{
    "paymentorder": {
        "instrument": "Invoice-PayExFinancingSe",
        "operation": "Purchase",
        "currency": "SEK",
        "amount": 1500,
        "vatAmount": 375,
        "description": "Test Purchase",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE", 
        "productName": "Checkout3", // Removed in 3.1, can be excluded in 3.0 if version is added in header 
        "urls":
            "hostUrls": [ "https://example.com", "https://example.net" ],
            "paymentUrl": "https://example.com/perform-payment",
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-cancelled",
            "callbackUrl": "https://api.example.com/payment-callback",
            "termsOfServiceUrl": "https://example.com/termsandconditions.pdf"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "AB832",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-123456",
            "subsite": "MySubsite", 
            "siteId": "MySiteId", 
        },
        "payer": {
            "requireConsumerInfo": true,
            "digitalProducts": false,
            "shippingAddressRestrictedToCountryCodes": [ "NO", "US" ]
        },
        "orderItems": [
            {
                "reference": "P1",
                "name": "Product1",
                "type": "PRODUCT",
                "class": "ProductGroup1",
                "itemUrl": "https://example.com/products/123",
                "imageUrl": "https://example.com/product123.jpg",
                "description": "Product 1 description",
                "discountDescription": "Volume discount",
                "quantity": 5,
                "quantityUnit": "pcs",
                "unitPrice": 300,
                "discountPrice": 0,
                "vatPercent": 2500,
                "amount": 1500,
                "vatAmount": 375
            },
            {
                "reference": "I1",
                "name": "InvoiceFee",
                "type": "PAYMENT_FEE",
                "class": "Fees",
                "description": "Fee for paying with Invoice",
                "quantity": 1,
                "quantityUnit": "pcs",
                "unitPrice": 1900,
                "vatPercent": 0,
                "amount": 1900,
                "vatAmount": 0,
                "restrictedToInstruments": [
                    "Invoice-PayExFinancingSe"
                ]
            }
        ],
        "riskIndicator": {
            "deliveryEmailAddress": "olivia.nyhuus@payex.com",
            "deliveryTimeFrameIndicator": "01",
            "preOrderDate": "19801231",
            "preOrderPurchaseIndicator": "01",
            "shipIndicator": "01",
            "giftCardPurchase": false,
            "reOrderPurchaseIndicator": "01",
            "pickUpAddress": {
                "name": "Olivia Nyhus",
                "streetAddress": "Saltnestoppen 43",
                "coAddress": "",
                "city": "Saltnes",
                "zipCode": "1642",
                "countryCode": "NO"
            }
        }
    }
}

Instrument Mode Response

Note the implementation options Seamless View and Redirect (HostedView or Redirect in the response’s implementation field). Depending on which it is, either view-checkout (Seamless View) or redirect-checkout will appear in the response. Never both at the same time.

Response

1
2
3

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.x/2.0
api-supported-versions: 3.x/2.0

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
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

{
    "paymentOrder": {
        "id": "/psp/paymentorders/2c3f7a3e-65ca-4493-ac93-08d9dcb313fd",
        "created": "2022-01-24T10:54:05.6243371Z",
        "updated": "2022-01-24T10:54:19.2679591Z",
        "operation": "Purchase",
        "status": "Initialized",
        "currency": "SEK",
        "amount": 1500,
        "vatAmount": 375,
        "description": "Test",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "language": "sv-SE",
        "availableInstruments": [
            "Invoice-PayExFinancingSe"
        ],  
        "integration": "HostedView|Redirect",
        "instrumentMode": false,
        "guestMode": false,
        "orderItems": {
            "id": "/psp/paymentorders/2c3f7a3e-65ca-4493-ac93-08d9dcb313fd/orderitems"
        },
        "urls": {
            "id": "/psp/paymentorders/2c3f7a3e-65ca-4493-ac93-08d9dcb313fd/urls"
        },
        "payeeInfo": {
            "id": "/psp/paymentorders/2c3f7a3e-65ca-4493-ac93-08d9dcb313fd/payeeinfo"
        },
        "payer": {
            "id": "/psp/paymentorders/2c3f7a3e-65ca-4493-ac93-08d9dcb313fd/payers"
        },
        "history": {
            "id": "/psp/paymentorders/2c3f7a3e-65ca-4493-ac93-08d9dcb313fd/history"
        },
        "failed": {
            "id": "/psp/paymentorders/2c3f7a3e-65ca-4493-ac93-08d9dcb313fd/failed"
        },
        "aborted": {
            "id": "/psp/paymentorders/2c3f7a3e-65ca-4493-ac93-08d9dcb313fd/aborted"
        },
        "paid": {
            "id": "/psp/paymentorders/2c3f7a3e-65ca-4493-ac93-08d9dcb313fd/paid"
        },
        "cancelled": {
            "id": "/psp/paymentorders/2c3f7a3e-65ca-4493-ac93-08d9dcb313fd/cancelled"
        },
        "financialTransactions": {
            "id": "/psp/paymentorders/2c3f7a3e-65ca-4493-ac93-08d9dcb313fd/financialtransactions"
        },
        "failedAttempts": {
            "id": "/psp/paymentorders/2c3f7a3e-65ca-4493-ac93-08d9dcb313fd/failedattempts"
        },
        "metadata": {
            "id": "/psp/paymentorders/2c3f7a3e-65ca-4493-ac93-08d9dcb313fd/metadata"
        }
    },
      "operations": [
        {
          "method": "GET",
          "href": "https://ecom.externalintegration.payex.com/payment/menu/5a17c24e-d459-4567-bbad-aa0f17a76119?_tc_tid=30f2168171e142d38bcd4af2c3721959",
          "rel": "redirect-checkout",
          "contentType": "text/html"
        },
        {
          "method": "GET",
          "href": "https://ecom.externalintegration.payex.com/payment/core/js/px.payment.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119&culture=nb-NO&_tc_tid=30f2168171e142d38bcd4af2c3721959",
          "rel": "view-checkout",
          "contentType": "application/javascript"
        },
        {
          "href": "https://api.payex.com/psp/paymentorders/222a50ca-b268-4b32-16fa-08d6d3b73224",
          "rel":"update-order",
          "method":"PATCH",
          "contentType":"application/json"
        },
        {
          "href": "https://api.payex.com/psp/paymentorders/222a50ca-b268-4b32-16fa-08d6d3b73224",
          "rel": "abort",
          "method": "PATCH",
          "contentType": "application/json"
        },
        {
          "href": "https://api.payex.com/psp/paymentorders/222a50ca-b268-4b32-16fa-08d6d3b73224",
          "rel": "set-instrument",
          "method": "PATCH",
          "contentType": "application/json"
        }
    ]
}

PATCH Payment Method Selection

Note the rel named set-instrument, which appears among the available operations in the paymentOrder response when instrument mode is applied.

To switch payment method after the paymentOrder has been created, you can use the following PATCH request, here with Swish as an example.

Request

1
2
3
4

PATCH /psp//paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1 HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.x/2.0      // Version optional for 3.0 and 2.0

1
2
3
4
5
6

{
  "paymentorder": {
    "operation": "SetInstrument",
    "instrument": "Swish"
  }
}

Available Payment Methods

The valid methods for the paymentOrder can be retrieved from the availableInstruments parameter in the paymentOrder response. Using a merchant set up with contracts for Creditcard, Swish and Invoice, availableInstruments will look like this:

Available Methods

1
2
3

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.x/2.0
api-supported-versions: 3.x/2.0

1
2
3
4
5

"availableInstruments": [
            "CreditCard",
            "Invoice-PayExFinancingSe",
            "Swish"
        ]