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@payex.com",
"msisdn": "+46709876543",
"address": {
"streetAddress": "Main Street 1",
"coAddress": "Apartment 123, 2 stairs up",
"city": "Stockholm",
"zipCode": "SE-11253",
"countryCode": "SE"
}
}
}
}
Required | Field | Type | Description |
---|---|---|---|
check | paymentOrder |
object |
The payment order object. |
check | operation |
string |
Must be set to Verify . |
check | productName |
string |
Must be set to Checkout3 . Mandatory for Digital Payments v3.0, either in this field or the header, as you won’t get the operations in the response without submitting this field. |
check | currency |
string |
The currency of the payment. |
check | restrictedToPayoutInstruments |
bool |
Set to true to only show Payout enabled payment methods (Trustly). |
check | generateUnscheduledToken |
bool |
Set to true . |
check | description |
string |
The description of the payment order. |
check | userAgent |
string |
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. |
check | language |
string |
The language of the payer. |
check | urls |
object |
The urls object, containing the URLs relevant for the payment order. |
check | hostUrls |
array |
The array of valid URLs. |
check | completeUrl |
string |
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. |
check | cancelUrl |
string |
The URL to redirect the payer to if the payment is cancelled, either by the payer or by the merchant trough an abort request of the payment or paymentorder . |
check | payeeInfo |
object |
The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details. |
check | payeeId |
string |
The ID of the payee, usually the merchant ID. |
check | payeeReference |
string |
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 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 |
The name of the payee, usually the name of the merchant. | |
payer |
object |
The payer object containing information about the payer relevant for the payment order. |
|
payerReference |
string |
The merchant’s unique reference to the payer. | |
check | firstName |
string |
The first name of the payer or the company name. |
lastName |
string |
The last name of the payer. | |
nationalIdentifier |
object |
The national identifier object. This is required when using the restrictedToSocialSecurityNumber parameter. |
|
socialSecurityNumber |
string |
The payer’s social security number. | |
countryCode |
string |
Country code of the payer. | |
email |
string |
The e-mail address of the payer. | |
msisdn |
string |
The mobile phone number of the Payer. The mobile number must have a country code prefix and be 8 to 15 digits in length. | |
address |
object |
The address object containing information about the payer’s address. | |
︎ | streetAddress |
string |
The street address of the payer. Maximum 50 characters long. |
coAddress |
string |
The payer’s CO-address (if used). | |
city |
string |
The payer’s city of residence. | |
zipCode |
string |
The postal number (ZIP code) of the payer. | |
countryCode |
string |
Country code for country of residence, e.g. 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"
}
]
}
Field | Type | Description |
---|---|---|
paymentOrder |
object |
The payment order 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 |
The ISO-8601 date of when the payment order was created. |
updated |
string |
The ISO-8601 date of when the payment order was updated. |
operation |
string |
Verify |
status |
string |
Indicates the payment order’s current status. 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 |
The currency of the payment order. |
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. |
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 40 character length textual description of the purchase. |
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. |
language |
string |
sv-SE , nb-NO , da-DK , en-US or fi-FI . |
availableInstruments |
string |
A list of payment methods available for this payment. |
implementation |
string |
The merchant’s Digital Payments implementation type. 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 |
The merchant’s Digital Payments integration type. 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 |
Set to true or false . Indicates if the payment is initialized with only one payment methods available. |
guestMode |
bool |
Set to 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 |
The URL to the urls resource where all URLs related to the payment order can be retrieved. |
payeeInfo |
id |
The URL to the payeeInfo resource where information related to the payee can be retrieved. |
payer |
id |
The URL to the payer resource where information about the payer can be retrieved. |
history |
id |
The URL to the history resource where information about the payment’s history can be retrieved. |
failed |
id |
The URL to the failed resource where information about the failed transactions can be retrieved. |
aborted |
id |
The URL to the aborted resource where information about the aborted transactions can be retrieved. |
paid |
id |
The URL to the paid resource where information about the paid transactions can be retrieved. |
cancelled |
id |
The URL to the cancelled resource where information about the cancelled transactions can be retrieved. |
financialTransactions |
id |
The URL to the financialTransactions resource where information about the financial transactions can be retrieved. |
failedAttempts |
id |
The URL to the failedAttempts resource where information about the failed attempts can be retrieved. |
metadata |
id |
The URL to the 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"
}
}
Field | Type | Description |
---|---|---|
paymentOrder |
object |
The payment order object. |
operation |
string |
Determines the initial operation, defining the type of payment order created. |
clearingHouse |
string |
The clearing house of the recipient’s bank account. Typically the name of a country in uppercase letters. |
bankNumber |
string |
The bank number identifying the recipient’s bank in the given clearing house. For bank accounts in IBAN format you should just provide an empty string (“”). For non-IBAN, see the example in our request or the bank number format table. |
accountNumber |
string |
The account number, identifying the recipient’s account in the bank. Can be either IBAN or country-specific format. See the account number format table for further information. |
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"
}
]
}
Field | Type | Description |
---|---|---|
paymentOrder |
object |
The payment order 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 |
The ISO-8601 date of when the payment order was created. |
updated |
string |
The ISO-8601 date of when the payment order was updated. |
operation |
string |
Verify |
status |
string |
Indicates the payment order’s current status. 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 |
The currency of the payment order. |
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. |
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 40 character length textual description of the purchase. |
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. |
language |
string |
sv-SE , nb-NO , da-DK , en-US or fi-FI . |
availableInstruments |
string |
A list of payment methods available for this payment. |
implementation |
string |
The merchant’s Digital Payments implementation type. 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 |
The merchant’s Digital Payments integration type. 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 |
Set to true or false . Indicates if the payment is initialized with only one payment method available. |
guestMode |
bool |
Set to 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 |
The URL to the urls resource where all URLs related to the payment order can be retrieved. |
payeeInfo |
id |
The URL to the payeeInfo resource where information related to the payee can be retrieved. |
payer |
id |
The URL to the payer resource where information about the payer can be retrieved. |
history |
id |
The URL to the history resource where information about the payment’s history can be retrieved. |
failed |
id |
The URL to the failed resource where information about the failed transactions can be retrieved. |
aborted |
id |
The URL to the aborted resource where information about the aborted transactions can be retrieved. |
paid |
id |
The URL to the paid resource where information about the paid transactions can be retrieved. |
cancelled |
id |
The URL to the cancelled resource where information about the cancelled transactions can be retrieved. |
financialTransactions |
id |
The URL to the financialTransactions resource where information about the financial transactions can be retrieved. |
failedAttempts |
id |
The URL to the failedAttempts resource where information about the failed attempts can be retrieved. |
metadata |
id |
The URL to the 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": ""
}
}
}
Required | Field | Type | Description |
---|---|---|---|
check | paymentOrder |
object |
The payment order object. |
check | operation |
string |
Must be set to Payout . |
check | productName |
string |
Must be set to Checkout3 . Mandatory for Digital Payments v3.0, either in this field or the header, as you won’t get the operations in the response without submitting this field. |
check | currency |
string |
The currency of the payment. |
check | 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. |
check | 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. |
unscheduledToken |
string |
Must be provided to specify the consumer account to be the receiver of the payout. | |
check | description |
string |
The description of the payment order. |
check | userAgent |
string |
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. |
check | language |
string |
The language of the payer. |
check | urls |
object |
The urls object, containing the URLs relevant for the payment order. |
check | 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. |
check | payeeInfo |
object |
The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details. |
check | payeeId |
string |
The ID of the payee, usually the merchant ID. |
check | payeeReference |
string |
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 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 |
The name of the payee, usually the name of the merchant. | |
payer |
object |
The payer object containing information about the payer relevant for the payment order. |
|
payerReference |
string |
The merchant’s unique reference to the payer. |
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": []
}
Field | Type | Description |
---|---|---|
paymentOrder |
object |
The payment order 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 |
The ISO-8601 date of when the payment order was created. |
updated |
string |
The ISO-8601 date of when the payment order was updated. |
operation |
string |
Purchase |
status |
string |
Indicates the payment order’s current status. 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 |
The currency of the payment order. |
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. |
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 40 character length textual description of the purchase. |
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. |
language |
string |
sv-SE , nb-NO , da-DK , en-US or fi-FI . |
availableInstruments |
string |
A list of payment methods available for this payment. |
implementation |
string |
The merchant’s Digital Payments implementation type. 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 |
The merchant’s Digital Payments integration type. 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 |
Set to true or false . Indicates if the payment is initialized with only one payment methods available. |
guestMode |
bool |
Set to 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 |
The URL to the orderItems resource where information about the order items can be retrieved. |
urls |
id |
The URL to the urls resource where all URLs related to the payment order can be retrieved. |
payeeInfo |
id |
The URL to the payeeInfo resource where information related to the payee can be retrieved. |
history |
id |
The URL to the history resource where information about the payment’s history can be retrieved. |
failed |
id |
The URL to the failed resource where information about the failed transactions can be retrieved. |
aborted |
id |
The URL to the aborted resource where information about the aborted transactions can be retrieved. |
paid |
id |
The URL to the paid resource where information about the paid transactions can be retrieved. |
cancelled |
id |
The URL to the cancelled resource where information about the cancelled transactions can be retrieved. |
financialTransactions |
id |
The URL to the financialTransactions resource where information about the financial transactions can be retrieved. |
failedAttempts |
ic |
The URL to the failedAttempts resource where information about the failed attempts can be retrieved. |
metadata |
id |
The URL to the 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": []
}
Field | Type | Description |
---|---|---|
paymentOrder |
object |
The payment order 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 |
The ISO-8601 date of when the payment order was created. |
updated |
string |
The ISO-8601 date of when the payment order was updated. |
operation |
string |
Purchase |
status |
string |
Indicates the payment order’s current status. 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 |
The currency of the payment order. |
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. |
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 40 character length textual description of the purchase. |
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. |
language |
string |
sv-SE , nb-NO , da-DK , en-US or fi-FI . |
availableInstruments |
string |
A list of payment methods available for this payment. |
implementation |
string |
The merchant’s Digital Payments implementation type. 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 |
The merchant’s Digital Payments integration type. 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 |
Set to true or false . Indicates if the payment is initialized with only one payment method available. |
guestMode |
bool |
Set to 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 |
The URL to the 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 |
The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details. |
payer |
string |
The URL to the payer resource where information about the payer can be retrieved. |
history |
string |
The URL to the history resource where information about the payment’s history can be retrieved. |
failed |
string |
The URL to the failed resource where information about the failed transactions can be retrieved. |
aborted |
string |
The URL to the aborted resource where information about the aborted transactions can be retrieved. |
paid |
string |
The URL to the 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 |
The payment method used in the fulfillment of the payment. Do not use this field for code validation purposes. To determine if a 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 |
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 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 |
This will either be set to 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. |
tokens |
integer |
A list of tokens connected to the payment. |
type |
string |
payment , recurrence , transactionOnFile or unscheduled . The different types of available tokens. |
token |
string |
The token guid . |
name |
string |
The name of the token. In the example, a masked version of a card number. |
expiryDate |
string |
The expiry date of the token. |
feeAmount |
integer |
If the payment method used had a unique fee, it will be displayed in this field. |
discountAmount |
integer |
If the payment method used had a unique discount, it will be displayed in this field. |
details |
integer |
Details connected to the payment. |
trustlyOrderId |
string |
A Trustly specific order id meant to be use if there is a support case. |
cancelled |
id |
The URL to the cancelled resource where information about the cancelled transactions can be retrieved. |
financialTransactions |
id |
The URL to the financialTransactions resource where information about the financial transactions can be retrieved. |
failedAttempts |
id |
The URL to the failedAttempts resource where information about the failed attempts can be retrieved. |
metadata |
id |
The URL to the 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)