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
instrument 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 instrument 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 instrument. 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 instrument to show. If you have an
agreement with Swedbank Pay for both Card and Swish/Vipps processing, and the
payer chooses either of these instruments, you should add the instrument
parameter with the specific payment instrument.
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.
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 do an await payex.getAcceptedWallets()
.
We will return a string array with the wallets eligible for that purchase. The
format will e.g. be ["applepay"]
.
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 instrument of choice.
Request
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
POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"paymentorder": {
"operation": "Purchase",
"currency": "SEK",
"amount": 1500,
"vatAmount": 375,
"description": "Test Purchase",
"userAgent": "Mozilla/5.0...",
"language": "sv-SE",
"instrument": "Invoice-PayExFinancingSe",
"productName": "Checkout3",
"implementation": "Enterprise",
"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
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
HTTP/1.1 200 OK
Content-Type: application/json
{
"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"
],
"implementation": "Enterprise",
{
"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"
}
]
}
1
] } ```
PATCH Instrument Selection
Note the rel
named set-instrument
, which appears among the available
operations in the paymentOrder
response when instrument mode is applied.
To switch instrument after the paymentOrder
has been created, you can use the
following PATCH
request, here with Swish as an example.
1
2
3
4
5
6
7
8
9
10
11
PATCH /psp//paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1 HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"paymentorder": {
"operation": "SetInstrument",
"instrument": "Swish"
}
}
Available Instruments
The valid instruments 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:
1
2
3
4
5
"availableInstruments": [
"CreditCard",
"Invoice-PayExFinancingSe",
"Swish"
]