This feature is only available for merchants who have a specific agreement with Swedbank Pay.
Introduction
At the moment, our payout offering consists of Trustly Payout only, but this may be expanding going forward.
There are two alternatives for implementing Trustly Payout. Select Account and Register Account. Both alternatives consist of two parts, a setup and a server-to-server call which actually triggers the payout.
The setup procedures of the two options differ somewhat, so we will describe them separately. The actual payout procedure is the same, and will be described as one.
Select Account
Select Account should be used for all consumers who will need to pick their payout account. The initial setup handles the UI part where the payer chooses their bank account. This endpoint will return a token that can be used to represent that bank account for that payer. The second part is, as mentioned before, a server-to-server endpoint where the actual payout is triggered. This lets you reuse the token multiple times if that is desired.
Select Account Setup
The initial setup can be done at an earlier time than the actual payout.
- The payer initiates the payout process on your site.
- You will have to initiate a
PaymentOrder
towards Swedbank Pay to start the payout process. It is important to set“operation=Verify”,
generateUnscheduledToken=true
andrestrictedToPayoutInstruments=true
. - The response will include an operation with a
rel:redirect-checkout
or arel:view-checkout
. This is where you need to redirect the payer, or display in your UI, to let them choose their bank account. - Redirect payer’s browser to
redirect-paymentmenu
or display therel:view-checkout
. - The Swedbank Pay payment UI will be loaded in Payout mode.
- The only option for the payer is to choose Trustly, as this is the only available payout alternative to date.
- The payer’s browser will be redirected to Trustly.
- The payer will identify themselves by BankId and choose the bank account where they want to receive the money.
- The payer is then redirected back to Swedbank Pay.
- Swedbank Pay will validate that we have received the bank account information before showing the OK message.
- The payer is redirected back to the
completeUrl
provided in the initial call. - The payer’s browser is connected to the
completeUrl
. - You then need to do a
GET
to check the status of the payout. - You will receive a
PaymentOrder
response model. You can check that the status is set toPaid
. If thePaymentOrder
is aborted or failed, something went wrong and the attempt was unsuccessful. You will get theUnscheduledToken
in the model’s paid node. - Return status to the payer about the status.
Register Account
Register Account should be used for payouts to other business entities. This implementation requires that you already have all account information for the receiving payout account. There is no interaction needed by the receiving part in this flow.
Register Account Setup
- You or the customer will trigger the payout process.
- You will have to initiate a
PaymentOrder
towards Swedbank Pay to start the payout process. It is important to setoperation=Verify
,generateUnscheduledToken=true
,restrictedToPayoutInstruments=true
. - The response will include an operation with a
rel:verify-trustly
. This is where you need to do a call to register the bank account. - Do a call to the
verify-trustly
endpoint to register the bank account details. - The response will have
status=Paid
if everything is completed. TheunscheduledToken
will be provided in the response model’sPaid
node. - If desired, you can notify the payer that the bank account is registered.
The Server-To-Server Payout Call
- When it is time to do a payout, you must initiate a new payment order. This
time there is no interaction with the payer, so it will be handled as a
server-to-server call. You must set
operation=Payout
andunscheduledToken=<token>
. It is also important to include acallbackUrl
as this call is async and will use callbacks to communicate status changes. - Swedbank Pay will initiate the payout process against Trustly.
- You will get a response that the
PaymentOrder
is initialized. The reason for this is that it takes some time before the payout is completed. - If you wish, you can now communicate to the payer that the payout is registered, but not finished.
It will take some time before a payout is either OK or Failed. There can also
be edge cases where the payout will get the Paid
status first, and changed
to failed later. It is important to design the system to handle these
scenarios. If the payout is complete the following flow will happen:
- You will get a callback.
- You will need to answer the callback with an acknowledge message.
- You need to do a
GET
on thePaymentOrder
to check the status. - It must have
status=Paid
if the payout was successful. - You can now inform the payer that the payout was successful.
If something failed in the payout process this flow will happen.
- If the payout failed, you will get a callback.
- You will need to answer the callback with an acknowledge message.
- You need to do a GET on the
PaymentOrder
to check the status. - It will have
status=Aborted
if the payout failed. - You can now inform the payer that the payout has failed and that you will try to do the payout again.
Verify Request
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
{
"paymentorder": {
"restrictedToPayoutInstruments": true,
"generateUnscheduledToken": true,
"operation": "Verify",
"productName": "Checkout3", // Removed in 3.1, can be excluded in 3.0 if version is added in header
"currency": "SEK",
"description": "Bank account verification",
"userAgent": "Mozilla/5.0...",
"language": "sv-SE",
"urls": {
"completeUrl": "http://complete.url",
"hostUrls": ["http://testmerchant.url"],
"cancelUrl": "http://cancel.url"
},
"payeeInfo": {
"payeeId": "",
"payeeReference": "",
"payeeName": "Testmerchant"
},
"payer": {
"payerReference": "",
"firstName": "Example",
"lastName": "Name",
"nationalIdentifier": {
"socialSecurityNumber": "199710202392",
"countryCode": "SE"
},
"email": "test@swedbankpay.com",
"msisdn": "+46709876543",
"address": {
"streetAddress": "Main Street 1",
"coAddress": "Apartment 123, 2 stairs up",
"city": "Stockholm",
"zipCode": "SE-11253",
"countryCode": "SE"
}
}
}
}
paymentOrder
object
check
operation
string
check
Determines the initial operation, defining the type of payment order created. Possible options are Purchase, Abort Verify, UnscheduledPurchase, Recur and Payout.
Must be set toVerify
.
productName
string
check
Checkout3
. Mandatory for Online Payments v3.0, either in this field or the header, as you won't get the operations in the response without submitting this field.
currency
string
check
restrictedToPayoutInstruments
bool
check
true
to only show Payout enabled payment methods (Trustly).
generateUnscheduledToken
bool
check
true
.
description
string
check
userAgent
string
check
The user agent of the payer. Should typically be set to the value of the User-Agent
header sent by the payer’s web browser.
language
string
check
urls
object
check
urls
object, containing the URLs relevant for the payment order.
hostUrls
array
check
completeUrl
string
check
The URL that Swedbank Pay will redirect back to when the payer has completed their interactions with the payment. This does not indicate a successful payment, only that it has reached a final (complete) state. A GET
request needs to be performed on the payment order to inspect it further. See completeUrl
for details.
cancelUrl
string
check
abort
request of the payment
or paymentorder
.
payeeInfo
object
check
The payeeInfo
object, containing information about the payee (the recipient of the money). See payeeInfo
for details.
payeeId
string
check
payeeReference
string(30)
check
A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number
or the payeeReference
is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number
is sent to the acquirer and the payeeReference
must be in the format of A-Za-z0-9
and string(30)
. If you handle the settlement, Swedbank Pay will send the payeeReference
and it will be limited to the format of string(12)
. All characters must be digits. In Invoice Payments payeeReference
is used as an invoice/receipt number, if the receiptReference
is not defined.
payeeName
string
payer
object
payer
object containing information about the payer relevant for the payment order.
payerReference
string
firstName
string
check
lastName
string
nationalIdentifier
object
restrictedToSocialSecurityNumber
parameter.
socialSecurityNumber
string
countryCode
string
email
string
msisdn
string
address
object
streetAddress
string
coAddress
string
city
string
zipCode
string
countryCode
string
SE
, NO
, or FI
.Verify Response
Note the new operation verify-trustly
, which is available if it is activated
in the merchant’s contract and the payer’s first and last name is added in the
request.
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
{
"paymentOrder": {
"id": "/psp/paymentorders/b60d08b8-0509-4abf-a722-08db68bad644",
"created": "2023-06-09T07:26:27.3013437Z",
"updated": "2023-06-09T07:26:28.6979343Z",
"operation": "Verify",
"status": "Initialized",
"currency": "SEK",
"amount": 510,
"vatAmount": 0,
"description": "Test Verification",
"initiatingSystemUserAgent": "PostmanRuntime/7.32.2",
"language": "nb-NO",
"availableInstruments": [
"Trustly"
],
"implementation": "PaymentsOnly",
"integration": "",
"instrumentMode": false,
"guestMode": false,
"urls": {
"id": "/psp/paymentorders/b60d08b8-0509-4abf-a722-08db68bad644/urls"
},
"payeeInfo": {
"id": "/psp/paymentorders/b60d08b8-0509-4abf-a722-08db68bad644/payeeinfo"
},
"payer": {
"id": "/psp/paymentorders/b60d08b8-0509-4abf-a722-08db68bad644/payers"
},
"history": {
"id": "/psp/paymentorders/b60d08b8-0509-4abf-a722-08db68bad644/history"
},
"failed": {
"id": "/psp/paymentorders/b60d08b8-0509-4abf-a722-08db68bad644/failed"
},
"aborted": {
"id": "/psp/paymentorders/b60d08b8-0509-4abf-a722-08db68bad644/aborted"
},
"paid": {
"id": "/psp/paymentorders/b60d08b8-0509-4abf-a722-08db68bad644/paid"
},
"cancelled": {
"id": "/psp/paymentorders/b60d08b8-0509-4abf-a722-08db68bad644/cancelled"
},
"financialTransactions": {
"id": "/psp/paymentorders/b60d08b8-0509-4abf-a722-08db68bad644/financialtransactions"
},
"failedAttempts": {
"id": "/psp/paymentorders/b60d08b8-0509-4abf-a722-08db68bad644/failedattempts"
},
"metadata": {
"id": "/psp/paymentorders/b60d08b8-0509-4abf-a722-08db68bad644/metadata"
}
},
"operations": [
{
"method": "PATCH",
"href": "https://api.stage.payex.com/psp/paymentorders/b60d08b8-0509-4abf-a722-08db68bad644",
"rel": "update-order",
"contentType": "application/json"
},
{
"method": "PATCH",
"href": "https://api.stage.payex.com/psp/paymentorders/b60d08b8-0509-4abf-a722-08db68bad644",
"rel": "abort",
"contentType": "application/json"
},
{
"method": "GET",
"href": "https://ecom.stage.payex.com/checkout/a8ff4fa9821b500dbb657bcba68422e20b9ba8dd2652bbc3f0f456b93774023f?_tc_tid=96f4d7cef4984a84b380e5478b7f6632",
"rel": "redirect-checkout",
"contentType": "text/html"
},
{
"method": "GET",
"href": "https://ecom.stage.payex.com/checkout/core/client/checkout/a8ff4fa9821b500dbb657bcba68422e20b9ba8dd2652bbc3f0f456b93774023f?culture=nb-NO&_tc_tid=96f4d7cef4984a84b380e5478b7f6632",
"rel": "view-checkout",
"contentType": "application/javascript"
},
{
"method": "PATCH",
"href": "https://api.stage.payex.com/psp/paymentorders/b60d08b8-0509-4abf-a722-08db68bad644",
"rel": "verify-trustly",
"contentType": "application/json"
}
]
}
paymentOrder
object
id
string
The relative URL and unique identifier of the paymentorder
resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
created
string
updated
string
operation
string
Determines the initial operation, defining the type of payment order created. Possible options are Purchase, Abort Verify, UnscheduledPurchase, Recur and Payout.
status
string
Initialized
is returned when the payment is created and still ongoing. The request example above has this status. Paid
is returned when the payer has completed the payment successfully. See the Paid response. Failed
is returned when a payment has failed. You will find an error message in the Failed response. Cancelled
is returned when an authorized amount has been fully cancelled. See the Cancelled response. It will contain fields from both the cancelled description and paid section. Aborted
is returned when the merchant has aborted the payment, or if the payer cancelled the payment in the redirect integration (on the redirect page). See the Aborted response.
currency
string
amount
integer
The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000
= 100.00
SEK, 5000
= 50.00
SEK. The amount displayed is the final amount the payer paid for their order, including any payment method specific discounts or fees.
vatAmount
integer
The payment’s VAT (Value Added Tax) amount
, entered in the lowest monetary unit of the selected currency. E.g.: 10000
= 100.00
SEK, 5000
= 50.00
SEK. The vatAmount
entered will not affect the amount
shown on the payment page, which only shows the total amount
. This field is used to specify how much of the total amount
the VAT will be. Set to 0
(zero) if there is no VAT amount
charged.
description
string(40)
A textual description of the purchase. Maximum length is 40 characters.
initiatingSystemUserAgent
string
The user agent of the HTTP client making the request, reflecting the value sent in the User-Agent
header with the initial POST
request which created the Payment Order.
language
string
sv-SE
, nb-NO
, da-DK
, en-US
or fi-FI
.
availableInstruments
string
implementation
string
Enterprise
or PaymentsOnly
. We ask that you don't build logic around this field's response. It is mainly for information purposes, as the implementation types might be subject to name changes. If this should happen, updated information will be available in this table.
integration
string
HostedView
(Seamless View) or Redirect
. This field will not be populated until the payer has opened the payment UI, and the client script has identified if Swedbank Pay or another URI is hosting the container with the payment iframe. We ask that you don't build logic around this field's response. It is mainly for information purposes. as the integration types might be subject to name changes, If this should happen, updated information will be available in this table.
instrumentMode
bool
true
or false
. Indicates if the payment is initialized with only one payment methods available.
guestMode
bool
true
or false
. Indicates if the payer chose to pay as a guest or not. When using the Payments Only implementation, this is triggered by not including a payerReference
in the original paymentOrder
request.
urls
id
urls
resource where all URLs related to the payment order can be retrieved.
payeeInfo
id
payeeInfo
resource where information related to the payee can be retrieved.
payer
id
payer
resource where information about the payer can be retrieved.
history
id
history
resource where information about the payment's history can be retrieved.
failed
id
failed
resource where information about the failed transactions can be retrieved.
aborted
id
aborted
resource where information about the aborted transactions can be retrieved.
paid
id
paid
resource where information about the paid transactions can be retrieved.
cancelled
id
cancelled
resource where information about the cancelled transactions can be retrieved.
financialTransactions
id
financialTransactions
resource where information about the financial transactions can be retrieved.
failedAttempts
id
failedAttempts
resource where information about the failed attempts can be retrieved.
metadata
id
metadata
resource where information about the metadata can be retrieved.
operations
array
The array of operations that are possible to perform on the payment order in its current state.
PATCH Verify Request
The PATCH request towards the verify-trustly
operation, containing the bank
account details.
Request
1
2
3
4
PATCH /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
{
"paymentorder": {
"operation": "VerifyTrustly",
"clearingHouse": "SWEDEN",
"bankNumber": "6112",
"accountNumber": "69706212"
}
}
paymentOrder
object
operation
string
Determines the initial operation, defining the type of payment order created. Possible options are Purchase, Abort Verify, UnscheduledPurchase, Recur and Payout.
clearingHouse
string
bankNumber
string
""
). For non-IBAN, see the example in our request or the bank number format table.
accountNumber
string
PATCH Verify Response
Note that the status in the response has changed to Paid
, with the correlating
disappearance of PATCH
operations.
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
{
"paymentOrder": {
"id": "/psp/paymentorders/<id>",
"created": "2023-07-06T05:42:07.7531238Z",
"updated": "2023-07-06T05:42:14.6086749Z",
"operation": "Verify",
"status": "Paid",
"currency": "SEK",
"amount": 510,
"vatAmount": 0,
"description": "Test Verification",
"initiatingSystemUserAgent": "PostmanRuntime/7.32.3",
"language": "nb-NO",
"availableInstruments": [
"Trustly"
],
"implementation": "PaymentsOnly",
"integration": "",
"instrumentMode": false,
"guestMode": true,
"urls": {
"id": "/psp/paymentorders/1e7e8e00-dc76-4ea5-0d7d-08db7c962a83/urls"
},
"payeeInfo": {
"id": "/psp/paymentorders/1e7e8e00-dc76-4ea5-0d7d-08db7c962a83/payeeinfo"
},
"payer": {
"id": "/psp/paymentorders/1e7e8e00-dc76-4ea5-0d7d-08db7c962a83/payers"
},
"history": {
"id": "/psp/paymentorders/1e7e8e00-dc76-4ea5-0d7d-08db7c962a83/history"
},
"failed": {
"id": "/psp/paymentorders/1e7e8e00-dc76-4ea5-0d7d-08db7c962a83/failed"
},
"aborted": {
"id": "/psp/paymentorders/1e7e8e00-dc76-4ea5-0d7d-08db7c962a83/aborted"
},
"paid": {
"id": "/psp/paymentorders/1e7e8e00-dc76-4ea5-0d7d-08db7c962a83/paid"
},
"cancelled": {
"id": "/psp/paymentorders/1e7e8e00-dc76-4ea5-0d7d-08db7c962a83/cancelled"
},
"financialTransactions": {
"id": "/psp/paymentorders/1e7e8e00-dc76-4ea5-0d7d-08db7c962a83/financialtransactions"
},
"failedAttempts": {
"id": "/psp/paymentorders/1e7e8e00-dc76-4ea5-0d7d-08db7c962a83/failedattempts"
},
"metadata": {
"id": "/psp/paymentorders/1e7e8e00-dc76-4ea5-0d7d-08db7c962a83/metadata"
}
},
"operations": "operations": [
{
"method": "GET",
"href": "https://ecom.stage.payex.com/checkout/a8ff4fa9821b500dbb657bcba68422e20b9ba8dd2652bbc3f0f456b93774023f?_tc_tid=96f4d7cef4984a84b380e5478b7f6632",
"rel": "redirect-checkout",
"contentType": "text/html"
},
{
"method": "GET",
"href": "https://ecom.stage.payex.com/checkout/core/client/checkout/a8ff4fa9821b500dbb657bcba68422e20b9ba8dd2652bbc3f0f456b93774023f?culture=nb-NO&_tc_tid=96f4d7cef4984a84b380e5478b7f6632",
"rel": "view-checkout",
"contentType": "application/javascript"
}
]
}
paymentOrder
object
id
string
The relative URL and unique identifier of the paymentorder
resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
created
string
updated
string
operation
string
Determines the initial operation, defining the type of payment order created. Possible options are Purchase, Abort Verify, UnscheduledPurchase, Recur and Payout.
status
string
Initialized
is returned when the payment is created and still ongoing. The request example above has this status. Paid
is returned when the payer has completed the payment successfully. See the Paid response. Failed
is returned when a payment has failed. You will find an error message in the Failed response. Cancelled
is returned when an authorized amount has been fully cancelled. See the Cancelled response. It will contain fields from both the cancelled description and paid section. Aborted
is returned when the merchant has aborted the payment, or if the payer cancelled the payment in the redirect integration (on the redirect page). See the Aborted response.
currency
string
amount
integer
The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000
= 100.00
SEK, 5000
= 50.00
SEK. The amount displayed is the final amount the payer paid for their order, including any payment method specific discounts or fees.
vatAmount
integer
The payment’s VAT (Value Added Tax) amount
, entered in the lowest monetary unit of the selected currency. E.g.: 10000
= 100.00
SEK, 5000
= 50.00
SEK. The vatAmount
entered will not affect the amount
shown on the payment page, which only shows the total amount
. This field is used to specify how much of the total amount
the VAT will be. Set to 0
(zero) if there is no VAT amount
charged.
description
string(40)
A textual description of the purchase. Maximum length is 40 characters.
initiatingSystemUserAgent
string
The user agent of the HTTP client making the request, reflecting the value sent in the User-Agent
header with the initial POST
request which created the Payment Order.
language
string
sv-SE
, nb-NO
, da-DK
, en-US
or fi-FI
.
availableInstruments
string
implementation
string
Enterprise
or PaymentsOnly
. We ask that you don't build logic around this field's response. It is mainly for information purposes, as the implementation types might be subject to name changes. If this should happen, updated information will be available in this table.
integration
string
HostedView
(Seamless View) or Redirect
. This field will not be populated until the payer has opened the payment UI, and the client script has identified if Swedbank Pay or another URI is hosting the container with the payment iframe. We ask that you don't build logic around this field's response. It is mainly for information purposes. as the integration types might be subject to name changes, If this should happen, updated information will be available in this table.
instrumentMode
bool
true
or false
. Indicates if the payment is initialized with only one payment method available.
guestMode
bool
true
or false
. Indicates if the payer chose to pay as a guest or not. When using the Payments Only implementation, this is triggered by not including a payerReference
in the original paymentOrder
request.
urls
id
urls
resource where all URLs related to the payment order can be retrieved.
payeeInfo
id
payeeInfo
resource where information related to the payee can be retrieved.
payer
id
payer
resource where information about the payer can be retrieved.
history
id
history
resource where information about the payment's history can be retrieved.
failed
id
failed
resource where information about the failed transactions can be retrieved.
aborted
id
aborted
resource where information about the aborted transactions can be retrieved.
paid
id
paid
resource where information about the paid transactions can be retrieved.
cancelled
id
cancelled
resource where information about the cancelled transactions can be retrieved.
financialTransactions
id
financialTransactions
resource where information about the financial transactions can be retrieved.
failedAttempts
id
failedAttempts
resource where information about the failed attempts can be retrieved.
metadata
id
metadata
resource where information about the metadata can be retrieved.
operations
array
The array of operations that are possible to perform on the payment order in its current state.
Payout Request
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
{
"paymentorder": {
"operation": "Payout",
"productName": "Checkout3", // Removed in 3.1, can be excluded in 3.0 if version is added in header
"currency": "SEK",
"amount": 1500,
"vatAmount": 0,
"unscheduledToken": "",
"description": "Bank account verification",
"userAgent": "Mozilla/5.0...",
"language": "sv-SE",
"urls": {
"callbackUrl": "http://callback.url"
},
"payeeInfo": {
"payeeId": "",
"payeeReference": "",
"payeeName": "Testmerchant"
},
"payer": {
"payerReference": ""
}
}
}
paymentOrder
object
check
operation
string
check
Determines the initial operation, defining the type of payment order created. Possible options are Purchase, Abort Verify, UnscheduledPurchase, Recur and Payout.
Must be set toPayout
.
productName
string
check
Checkout3
. Mandatory for Online Payments v3.0, either in this field or the header, as you won't get the operations in the response without submitting this field.
currency
string
check
amount
integer
check
The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000
= 100.00
SEK, 5000
= 50.00
SEK. The amount displayed is the final amount the payer paid for their order, including any payment method specific discounts or fees.
vatAmount
integer
check
The payment’s VAT (Value Added Tax) amount
, entered in the lowest monetary unit of the selected currency. E.g.: 10000
= 100.00
SEK, 5000
= 50.00
SEK. The vatAmount
entered will not affect the amount
shown on the payment page, which only shows the total amount
. This field is used to specify how much of the total amount
the VAT will be. Set to 0
(zero) if there is no VAT amount
charged.
unscheduledToken
string
description
string
check
userAgent
string
check
The user agent of the payer. Should typically be set to the value of the User-Agent
header sent by the payer’s web browser.
language
string
check
urls
object
check
urls
object, containing the URLs relevant for the payment order.
callbackUrl
string
check
The URL that Swedbank Pay will perform an HTTP POST
against every time a transaction is created on the payment order. See callback for details.
payeeInfo
object
check
The payeeInfo
object, containing information about the payee (the recipient of the money). See payeeInfo
for details.
payeeId
string
check
payeeReference
string(30)
check
A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number
or the payeeReference
is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number
is sent to the acquirer and the payeeReference
must be in the format of A-Za-z0-9
and string(30)
. If you handle the settlement, Swedbank Pay will send the payeeReference
and it will be limited to the format of string(12)
. All characters must be digits. In Invoice Payments payeeReference
is used as an invoice/receipt number, if the receiptReference
is not defined.
payeeName
string
payer
object
payer
object containing information about the payer relevant for the payment order.
payerReference
string
Payout Response
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
{
"paymentOrder": {
"id": "/psp/paymentorders/f4e47e61-37a5-4281-a5f3-08db68bc1d08",
"created": "2023-06-09T07:35:35.1855792Z",
"updated": "2023-06-09T07:35:35.6863019Z",
"operation": "Payout",
"status": "Initialized",
"currency": "SEK",
"amount": 2147483647,
"vatAmount": 0,
"description": "Test Purchase",
"initiatingSystemUserAgent": "PostmanRuntime/7.32.2",
"language": "sv-SE",
"availableInstruments": [],
"implementation": "PaymentsOnly",
"integration": "",
"instrumentMode": false,
"guestMode": true,
"orderItems": {
"id": "/psp/paymentorders/f4e47e61-37a5-4281-a5f3-08db68bc1d08/orderitems"
},
"urls": {
"id": "/psp/paymentorders/f4e47e61-37a5-4281-a5f3-08db68bc1d08/urls"
},
"payeeInfo": {
"id": "/psp/paymentorders/f4e47e61-37a5-4281-a5f3-08db68bc1d08/payeeinfo"
},
"history": {
"id": "/psp/paymentorders/f4e47e61-37a5-4281-a5f3-08db68bc1d08/history"
},
"failed": {
"id": "/psp/paymentorders/f4e47e61-37a5-4281-a5f3-08db68bc1d08/failed"
},
"aborted": {
"id": "/psp/paymentorders/f4e47e61-37a5-4281-a5f3-08db68bc1d08/aborted"
},
"paid": {
"id": "/psp/paymentorders/f4e47e61-37a5-4281-a5f3-08db68bc1d08/paid"
},
"cancelled": {
"id": "/psp/paymentorders/f4e47e61-37a5-4281-a5f3-08db68bc1d08/cancelled"
},
"financialTransactions": {
"id": "/psp/paymentorders/f4e47e61-37a5-4281-a5f3-08db68bc1d08/financialtransactions"
},
"failedAttempts": {
"id": "/psp/paymentorders/f4e47e61-37a5-4281-a5f3-08db68bc1d08/failedattempts"
},
"metadata": {
"id": "/psp/paymentorders/f4e47e61-37a5-4281-a5f3-08db68bc1d08/metadata"
}
},
"operations": []
}
paymentOrder
object
id
string
The relative URL and unique identifier of the paymentorder
resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
created
string
updated
string
operation
string
Determines the initial operation, defining the type of payment order created. Possible options are Purchase, Abort Verify, UnscheduledPurchase, Recur and Payout.
status
string
Initialized
is returned when the payment is created and still ongoing. The request example above has this status. Paid
is returned when the payer has completed the payment successfully. See the Paid response. Failed
is returned when a payment has failed. You will find an error message in the Failed response. Cancelled
is returned when an authorized amount has been fully cancelled. See the Cancelled response. It will contain fields from both the cancelled description and paid section. Aborted
is returned when the merchant has aborted the payment, or if the payer cancelled the payment in the redirect integration (on the redirect page). See the Aborted response.
currency
string
amount
integer
The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000
= 100.00
SEK, 5000
= 50.00
SEK. The amount displayed is the final amount the payer paid for their order, including any payment method specific discounts or fees.
vatAmount
integer
The payment’s VAT (Value Added Tax) amount
, entered in the lowest monetary unit of the selected currency. E.g.: 10000
= 100.00
SEK, 5000
= 50.00
SEK. The vatAmount
entered will not affect the amount
shown on the payment page, which only shows the total amount
. This field is used to specify how much of the total amount
the VAT will be. Set to 0
(zero) if there is no VAT amount
charged.
description
string(40)
A textual description of the purchase. Maximum length is 40 characters.
initiatingSystemUserAgent
string
The user agent of the HTTP client making the request, reflecting the value sent in the User-Agent
header with the initial POST
request which created the Payment Order.
language
string
sv-SE
, nb-NO
, da-DK
, en-US
or fi-FI
.
availableInstruments
string
implementation
string
Enterprise
or PaymentsOnly
. We ask that you don't build logic around this field's response. It is mainly for information purposes, as the implementation types might be subject to name changes. If this should happen, updated information will be available in this table.
integration
string
HostedView
(Seamless View) or Redirect
. This field will not be populated until the payer has opened the payment UI, and the client script has identified if Swedbank Pay or another URI is hosting the container with the payment iframe. We ask that you don't build logic around this field's response. It is mainly for information purposes. as the integration types might be subject to name changes, If this should happen, updated information will be available in this table.
instrumentMode
bool
true
or false
. Indicates if the payment is initialized with only one payment method available.
guestMode
bool
true
or false
. Indicates if the payer chose to pay as a guest or not. When using the Payments Only implementation, this is triggered by not including a payerReference
in the original paymentOrder
request.
orderItems
id
orderItems
resource where information about the order items can be retrieved.
urls
id
urls
resource where all URLs related to the payment order can be retrieved.
payeeInfo
id
payeeInfo
resource where information related to the payee can be retrieved.
payer
id
payer
resource where information about the payer can be retrieved.
history
id
history
resource where information about the payment's history can be retrieved.
failed
id
failed
resource where information about the failed transactions can be retrieved.
aborted
id
aborted
resource where information about the aborted transactions can be retrieved.
paid
id
paid
resource where information about the paid transactions can be retrieved.
cancelled
id
cancelled
resource where information about the cancelled transactions can be retrieved.
financialTransactions
id
financialTransactions
resource where information about the financial transactions can be retrieved.
failedAttempts
ic
failedAttempts
resource where information about the failed attempts can be retrieved.
metadata
id
metadata
resource where information about the metadata can be retrieved.
operations
array
The array of operations that are possible to perform on the payment order in its current state.
GET Payment Order
A GET performed after the callback is received on a paymentOrder
with status
Paid
. A field called trustlyOrderId
will appear among the details
in the
Paid
node. This can be used for support correspondance.
Response
1
2
HTTP/1.1 200 OK
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
{
"paymentOrder": {
"id": "/psp/paymentorders/3c265183-e7ee-438b-a5f4-08db68bc1d08",
"created": "2023-06-09T07:38:08.5041489Z",
"updated": "2023-06-09T07:38:25.3627725Z",
"operation": "Payout",
"status": "Paid",
"currency": "SEK",
"amount": 1000,
"vatAmount": 0,
"remainingReversalAmount": 1000,
"description": "Test Purchase",
"initiatingSystemUserAgent": "PostmanRuntime/7.32.2",
"language": "sv-SE",
"availableInstruments": [],
"implementation": "PaymentsOnly",
"integration": "",
"instrumentMode": false,
"guestMode": true,
"urls": {
"id": "/psp/paymentorders/3c265183-e7ee-438b-a5f4-08db68bc1d08/urls",
"callbackUrl": "http://test-dummy.net/payment-callback"
},
"payeeInfo": {
"id": "/psp/paymentorders/3c265183-e7ee-438b-a5f4-08db68bc1d08/payeeinfo"
},
"history": {
"id": "/psp/paymentorders/3c265183-e7ee-438b-a5f4-08db68bc1d08/history"
},
"failed": {
"id": "/psp/paymentorders/3c265183-e7ee-438b-a5f4-08db68bc1d08/failed"
},
"aborted": {
"id": "/psp/paymentorders/3c265183-e7ee-438b-a5f4-08db68bc1d08/aborted"
},
"paid": {
"id": "/psp/paymentorders/3c265183-e7ee-438b-a5f4-08db68bc1d08/paid"
"instrument": "Trustly",
"number": 79100113652,
"payeeReference": "1662373401",
"orderReference": "orderReference",
"transactionType": "Sale",
"amount": 1500,
"tokens": [
{
"type": "Unscheduled",
"token": "6d495aac-cb2b-4d94-a5f1-577baa143f2c",
"name": "492500******0004",
"expiryDate": "02/2023"
}
],
"submittedAmount": 1500,
"feeAmount": 0,
"discountAmount": 0,
"details": {
"trustlyOrderId": 123456789
}
},
"cancelled": {
"id": "/psp/paymentorders/3c265183-e7ee-438b-a5f4-08db68bc1d08/cancelled"
},
"financialTransactions": {
"id": "/psp/paymentorders/3c265183-e7ee-438b-a5f4-08db68bc1d08/financialtransactions"
},
"failedAttempts": {
"id": "/psp/paymentorders/3c265183-e7ee-438b-a5f4-08db68bc1d08/failedattempts"
},
"metadata": {
"id": "/psp/paymentorders/3c265183-e7ee-438b-a5f4-08db68bc1d08/metadata"
}
},
"operations": []
}
paymentOrder
object
id
string
The relative URL and unique identifier of the paymentorder
resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
created
string
updated
string
operation
string
Determines the initial operation, defining the type of payment order created. Possible options are Purchase, Abort Verify, UnscheduledPurchase, Recur and Payout.
status
string
Initialized
is returned when the payment is created and still ongoing. The request example above has this status. Paid
is returned when the payer has completed the payment successfully. See the Paid response. Failed
is returned when a payment has failed. You will find an error message in the Failed response. Cancelled
is returned when an authorized amount has been fully cancelled. See the Cancelled response. It will contain fields from both the cancelled description and paid section. Aborted
is returned when the merchant has aborted the payment, or if the payer cancelled the payment in the redirect integration (on the redirect page). See the Aborted response.
currency
string
amount
integer
The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000
= 100.00
SEK, 5000
= 50.00
SEK. The amount displayed is the final amount the payer paid for their order, including any payment method specific discounts or fees.
vatAmount
integer
The payment’s VAT (Value Added Tax) amount
, entered in the lowest monetary unit of the selected currency. E.g.: 10000
= 100.00
SEK, 5000
= 50.00
SEK. The vatAmount
entered will not affect the amount
shown on the payment page, which only shows the total amount
. This field is used to specify how much of the total amount
the VAT will be. Set to 0
(zero) if there is no VAT amount
charged.
description
string(40)
A textual description of the purchase. Maximum length is 40 characters.
initiatingSystemUserAgent
string
The user agent of the HTTP client making the request, reflecting the value sent in the User-Agent
header with the initial POST
request which created the Payment Order.
language
string
sv-SE
, nb-NO
, da-DK
, en-US
or fi-FI
.
availableInstruments
string
implementation
string
Enterprise
or PaymentsOnly
. We ask that you don't build logic around this field's response. It is mainly for information purposes, as the implementation types might be subject to name changes. If this should happen, updated information will be available in this table.
integration
string
HostedView
(Seamless View) or Redirect
. This field will not be populated until the payer has opened the payment UI, and the client script has identified if Swedbank Pay or another URI is hosting the container with the payment iframe. We ask that you don't build logic around this field's response. It is mainly for information purposes. as the integration types might be subject to name changes, If this should happen, updated information will be available in this table.
instrumentMode
bool
true
or false
. Indicates if the payment is initialized with only one payment method available.
guestMode
bool
true
or false
. Indicates if the payer chose to pay as a guest or not. When using the Payments Only implementation, this is triggered by not including a payerReference
in the original paymentOrder
request.
urls
string
urls
resource where all URLs related to the payment order can be retrieved.
id
string
The relative URL and unique identifier of the paymentorder
resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
callbackUrl
string
The URL that Swedbank Pay will perform an HTTP POST
against every time a transaction is created on the payment order. See callback for details.
payeeInfo
object
payer
string
payer
resource where information about the payer can be retrieved.
history
string
history
resource where information about the payment's history can be retrieved.
failed
string
failed
resource where information about the failed transactions can be retrieved.
aborted
string
aborted
resource where information about the aborted transactions can be retrieved.
paid
string
paid
resource where information about the paid transactions can be retrieved.
id
string
The relative URL and unique identifier of the paymentorder
resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
instrument
string
capture
is needed, we recommend using operations
or the transactionType
field.
number
integer
The transaction number
, useful when there’s need to reference the transaction in human communication. Not usable for programmatic identification of the transaction, where id
should be used instead.
payeeReference
string(30)
A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number
or the payeeReference
is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number
is sent to the acquirer and the payeeReference
must be in the format of A-Za-z0-9
and string(30)
. If you handle the settlement, Swedbank Pay will send the payeeReference
and it will be limited to the format of string(12)
. All characters must be digits.
transactionType
string
Authorization
or Sale
. Can be used to understand if there is a need for doing a capture on this payment order. Swedbank Pay recommends using the different operations to figure out if a capture is needed.
amount
integer
The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000
= 100.00
SEK, 5000
= 50.00
SEK. The amount displayed is the final amount the payer paid for their order, including any payment method specific discounts or fees.
tokens
integer
type
string
payment
, recurrence
, transactionOnFile
or unscheduled
. The different types of available tokens.
token
string
guid
.
name
string
expiryDate
string
feeAmount
integer
discountAmount
integer
details
integer
trustlyOrderId
string
cancelled
id
cancelled
resource where information about the cancelled transactions can be retrieved.
financialTransactions
id
financialTransactions
resource where information about the financial transactions can be retrieved.
failedAttempts
id
failedAttempts
resource where information about the failed attempts can be retrieved.
metadata
id
metadata
resource where information about the metadata can be retrieved.
operations
array
The array of operations that are possible to perform on the payment order in its current state.
Select Account Flow
Register Account Flow
(https://eu.developers.trustly.com/doc/reference/registeraccount#accountnumber-format)