Digital Payments

Payout

Paying out funds to the consumer’s account.

Edit "Payout" on GitHub

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.

  1. The payer initiates the payout process on your site.
  2. You will have to initiate a PaymentOrder towards Swedbank Pay to start the payout process. It is important to set “operation=Verify”, generateUnscheduledToken=true and restrictedToPayoutInstruments=true.
  3. The response will include an operation with a rel:redirect-checkout or a rel:view-checkout. This is where you need to redirect the payer, or display in your UI, to let them choose their bank account.
  4. Redirect payer’s browser to redirect-paymentmenu or display the rel:view-checkout.
  5. The Swedbank Pay payment UI will be loaded in Payout mode.
  6. The only option for the payer is to choose Trustly, as this is the only available payout alternative to date.
  7. The payer’s browser will be redirected to Trustly.
  8. The payer will identify themselves by BankId and choose the bank account where they want to receive the money.
  9. The payer is then redirected back to Swedbank Pay.
  10. Swedbank Pay will validate that we have received the bank account information before showing the OK message.
  11. The payer is redirected back to the completeUrl provided in the initial call.
  12. The payer’s browser is connected to the completeUrl.
  13. You then need to do a GET to check the status of the payout.
  14. You will receive a PaymentOrder response model. You can check that the status is set to Paid. If the PaymentOrder is aborted or failed, something went wrong and the attempt was unsuccessful. You will get the UnscheduledToken in the model’s paid node.
  15. 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

  1. You or the customer will trigger the payout process.
  2. You will have to initiate a PaymentOrder towards Swedbank Pay to start the payout process. It is important to set operation=Verify, generateUnscheduledToken=true, restrictedToPayoutInstruments=true.
  3. 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.
  4. Do a call to the verify-trustly endpoint to register the bank account details.
  5. The response will have status=Paid if everything is completed. The unscheduledToken will be provided in the response model’s Paid node.
  6. If desired, you can notify the payer that the bank account is registered.

The Server-To-Server Payout Call

  1. 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 and unscheduledToken=<token>. It is also important to include a callbackUrl as this call is async and will use callbacks to communicate status changes.
  2. Swedbank Pay will initiate the payout process against Trustly.
  3. 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.
  4. 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:

  1. You will get a callback.
  2. You will need to answer the callback with an acknowledge message.
  3. You need to do a GET on the PaymentOrder to check the status.
  4. It must have status=Paid if the payout was successful.
  5. You can now inform the payer that the payout was successful.

If something failed in the payout process this flow will happen.

  1. If the payout failed, you will get a callback.
  2. You will need to answer the callback with an acknowledge message.
  3. You need to do a GET on the PaymentOrder to check the status.
  4. It will have status=Aborted if the payout failed.
  5. 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 .
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 URLs valid for embedding of Swedbank Pay Seamless Views. Not needed to implement the Swedbank Pay redirect flow.
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. The amount displayed is the final amount the payer paid for their order, including any 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 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 Order.
language string sv-SE, nb-NO, da-DK, en-US or fi-FI.
availableInstruments string A list of 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. The amount displayed is the final amount the payer paid for their order, including any 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 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 Order.
language string sv-SE, nb-NO, da-DK, en-US or fi-FI.
availableInstruments string A list of 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 .
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. The amount displayed is the final amount the payer paid for their order, including any method specific discounts or fees.
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. The amount displayed is the final amount the payer paid for their order, including any 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 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 Order.
language string sv-SE, nb-NO, da-DK, en-US or fi-FI.
availableInstruments string A list of 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. The amount displayed is the final amount the payer paid for their order, including any 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 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 Order.
language string sv-SE, nb-NO, da-DK, en-US or fi-FI.
availableInstruments string A list of 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. The amount displayed is the final amount the payer paid for their order, including any method specific discounts or fees.
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

Select account flow chart

Register Account Flow

Register account flow chart

(https://eu.developers.trustly.com/doc/reference/registeraccount#accountnumber-format)