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.
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
90
91
92
93
94
95
{
"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/09ccd29a-7c4f-4752-9396-12100cbfecce",
"rel": "abort-paymentattempt",
"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 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
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"
]