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 paymentOrder
s 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
{
"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 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"
]