Payment Menu v2 – 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 payment methods, you should add the instrument parameter with the specific payment method.

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

{
    "paymentorder": {
        "instrument": "Invoice-PayExFinancingSe",
        "operation": "Purchase",
        "currency": "SEK",
        "amount": 1500,
        "vatAmount": 375,
        "description": "Test Purchase",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE", 
        "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", 
        },
        "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

Depending on which implementation you are using, either view-paymentorder (Seamless View) or redirect-paymentorder will appear in the response. Never both at the same time.

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
66
67
68
69
70
71
72
73

{
    "paymentOrder": {
        "id": "/psp/paymentorders/4dec0b0f-a385-452a-cc38-08d9f53bb7a8",
        "created": "2022-02-23T12:59:10.9600933Z",
        "updated": "2022-02-23T12:59:11.77654Z",
        "operation": "Purchase",
        "state": "Ready",
        "currency": "SEK",
        "amount": 1500,
        "vatAmount": 375,
        "description": "Testing - Stage",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "userAgent": "Mozilla/5.0",
        "language": "sv-SE",
        "instrument": "CreditCard",
        "availableInstruments": [
            "Invoice-PayExFinancingSe",
        ],
        "integration": "",
        "urls": {
            "id": "/psp/paymentorders/4dec0b0f-a385-452a-cc38-08d9f53bb7a8/urls"
        },
        "payeeInfo": {
            "id": "/psp/paymentorders/4dec0b0f-a385-452a-cc38-08d9f53bb7a8/payeeInfo"
        },
        "payer": {
            "id": "/psp/paymentorders/4dec0b0f-a385-452a-cc38-08d9f53bb7a8/payers"
        },
        "payments": {
            "id": "/psp/paymentorders/4dec0b0f-a385-452a-cc38-08d9f53bb7a8/payments"
        },
        "currentPayment": {
            "id": "/psp/paymentorders/4dec0b0f-a385-452a-cc38-08d9f53bb7a8/currentpayment"
        },
        "items": [{
            "creditCard": {
                "cardBrands": ["Visa", "MasterCard", "Amex", "Dankort", "Forbrugsforeningen", "Maestro", "Ica"]
            }
        }]
    },
    "operations": [
        {
        "method": "PATCH",
        "href": "https://api.stage.payex.com/psp/paymentorders/4dec0b0f-a385-452a-cc38-08d9f53bb7a8",
        "rel": "update-paymentorder-updateorder",
        "contentType": "application/json"
        },
        {
        "method": "PATCH",
        "href": "https://api.stage.payex.com/psp/paymentorders/4dec0b0f-a385-452a-cc38-08d9f53bb7a8",
        "rel": "update-paymentorder-abort",
        "contentType": "application/json"
        },
        {
        "method": "PATCH",
        "href": "https://api.stage.payex.com/psp/paymentorders/4dec0b0f-a385-452a-cc38-08d9f53bb7a8",
        "rel": "update-paymentorder-setinstrument",
        "contentType": "application/json"
        },
        {
        "method": "GET",
        "href": "https://ecom.stage.payex.com/paymentmenu/23ef8b8f5088711f6f2cdbc55ad4dad673fee24a70c7788a5dc8f50c6c7ba835?_tc_tid=30f2168171e142d38bcd4af2c3721959",
        "rel": "redirect-paymentorder",
        "contentType": "text/html"
        }
        {
        "method": "GET",
        "href": "https://ecom.stage.payex.com/paymentmenu/core/client/paymentmenu/23ef8b8f5088711f6f2cdbc55ad4dad673fee24a70c7788a5dc8f50c6c7ba835?culture=sv-SE&_tc_tid=30f2168171e142d38bcd4af2c3721959",
        "rel": "view-paymentorder",
        "contentType": "application/javascript"
        }
    ]
}

PATCH Payment Method Selection

Note the rel named update-paymentorder-setinstrument, 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 payment 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 Payment Methods

1
2

HTTP/1.1 200 OK
Content-Type: application/json

1
2
3
4
5

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