Foundation
The Swedbank Pay API Platform is built using the REST architectural style and the request and responses come in the JSON format. The API has predictable, resource-oriented URLs and use default HTTP features, like HTTP authentication (using OAuth 2), HTTP methods and headers. These techniques are widely used and understood by most HTTP client libraries.
Connection and Protocol
All requests towards Swedbank Pay API Platform are made with HTTP/1.1 over a secure TLS 1.2 (or higher) connection. Older HTTP clients running on older operating systems and frameworks might receive connection errors when connecting to Swedbank Pay’s APIs. This is most likely due to the connection being made from the client with TLS 1.0 or even SSL, which are all insecure and deprecated. If such is the case, ensure that you are able to connect over a TLS 1.2 connection by reading information regarding your programming languages and environments (Java, PHP Curl, PHP Zend,{:target=”_blank”} Ruby, Python, Node.js Request).
You can inspect Swedbank Pay’s TLS and cipher suite support at SSL Labs. Support for HTTP/2 in our APIs is being investigated.
Postel’s Robustness Principle
We encourage you to keep Postel’s robustness principle
in mind. Build your integration in a way that is resilient to change, wherever
it may come. Don’t confine yourself to the limits of our current documentation
examples. A string
looking like a guid
must still be handled and stored like
a string
, not as a guid
, as it could be a URL
in the future. The day our
transactionNumber
ticks past 1,000,000, make sure your integration can handle
1,000,001. If some fields
, operations
or headers
can’t be understood, you
must be able to ignore them. We have built our requests in a way which allows
the payeeInfo
field to be placed before metadata
, or vice versa if you want.
We don’t expect a specific order of elements, so we ask that you shouldn’t
either.
Headers
All requests against the API Platform should have a few common headers:
HTTP Request
1
2
3
4
5
6
7
POST /some/resource HTTP/1.1
Content-Type: application/json;version=3.x/2.0 charset=utf-8 // Version optional except for 3.1
Authorization: "Bearer 123456781234123412341234567890AB"
User-Agent: swedbankpay-sdk-dotnet/3.0.1
Accept: application/problem+json; q=1.0, application/json; q=0.9
Session-Id: 779da454399742248f2942bb064c4707
Forwarded: for=82.115.151.177; host=example.com; proto=https
Required | Header | Description |
---|---|---|
check︎ | Content-Type |
The content type of the body of the HTTP request. Usually set to application/json . |
check︎ | Authorization |
The OAuth 2 Access Token is generated in the Merchant Portal. |
User-Agent |
The user agent of the HTTP client making the HTTP request. Should be set to identify the system performing requests towards Swedbank Pay. The value submitted here will be returned in the response field initiatingSystemUserAgent . |
|
check︎ | Accept |
The content type accepted by the client. Usually set to application/json and application/problem+json so both regular responses as well as errors can be received properly. |
Session-Id |
A trace identifier used to trace calls through the API Platform (ref RFC 7329). Each request must mint a new GUID/UUID. If no Session-Id is provided, Swedbank Pay will generate one for the request. |
|
Forwarded |
The IP address of the payer as well as the host and protocol of the payer-facing web page. When the header is present, only the for parameter containing the payer’s IP address is required, the other parameters are optional. See RFC 7239 for details. |
URL Usage
The base URLs of the API Platform are:
Environment | Base URL |
---|---|
Test | https://api.externalintegration.payex.com/ |
Production | https://api.payex.com/ |
An important part of REST is its use of hypermedia. Instead of having to perform complex state management and hard coding URLs and the availability of different operations in the client, this task is moved to the server. The client simply follows links and performs operations provided by the API, given the current state of the resource. The server controls the state and lets the client know through hypermedia what’s possible in the current state of the resource. To get an introduction to hypermedia, please watch this 20 minute video.
Don’t build URLs: It is very important that only the base URLs of Swedbank Pay’s APIs are stored in your system. All other URLs are returned dynamically in the response. Swedbank Pay cannot guarantee that your implementation will remain working if you store any other URLs in your system. When performing requests, please make sure to use the complete URLs that are returned in the response. Do not attempt to parse or build upon the returned data – you should not put any special significance to the information you might glean from an URL. URLs should be treated as opaque identifiers you can use to retrieve the identified resource – nothing more, nothing less. If you don’t follow this advice, your integration most assuredly will break when Swedbank Pay makes updates in the future.
Storing URLs
Storing URLs: In general, URLs should be discovered in responses to previous requests, not stored.
However, URLs that are used to create new resources can be stored or hard coded.
Also, the URL of the generated resource can be stored on your end to GET
it at
a later point. Note that the URLs should be stored as opaque identifiers and
should not be parsed or interpreted in any way.
Operation URLs: URLs that are returned as part of the operations
in each response should
not be stored.
See the abbreviated example below where psp/creditcard/payments
from the
POST
header is an example of the URL that can be stored, as it is used to
create a new resource. Also, the /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1
URL can be stored in order to retrieve the created payment with an HTTP GET
request later.
The URLs found within operations
such as the href
of update-payment-abort
,
https://api.externalintegration.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1
should not be
stored.
In order to find which operations you can perform on a resource and the URL of
the operation to perform, you need to retrieve the resource with an HTTP GET
request first and then find the operation in question within the operations
field.
Request
1
2
3
POST /psp/creditcard/payments HTTP/1.1
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.x/2.0 // Version optional except for 3.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"payment": {
"operation": "Purchase",
"intent": "Authorization",
"currency": "SEK",
"prices": [{
"type": "CreditCard",
"amount": 1500,
"vatAmount": 0
}
],
"description": "Test Purchase",
"generatePaymentToken": false,
"generateRecurrenceToken": false,
"userAgent": "Mozilla/5.0...",
"language": "nb-NO",
}
}
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
{
"payment": {
"id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"number": 1234567890,
"instrument": "CreditCard",
"created": "2016-09-14T13:21:29.3182115Z",
"updated": "2016-09-14T13:21:57.6627579Z",
"state": "Ready",
"operation": "Purchase",
"intent": "Authorization",
},
"operations": [
{
"rel": "update-payment-abort",
"href": "https://api.externalintegration.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"method": "PATCH",
"contentType": "application/json"
},
{
"rel": "redirect-authorization",
"href": "https://ecom.externalintegration.payex.com/creditcard/payments/authorize/5a17c24e-d459-4567-bbad-aa0f17a76119",
"method": "GET",
"contentType": "text/html"
},
{
"rel": "view-authorization",
"href": "https://ecom.externalintegration.payex.com/creditcard/core/scripts/client/px.creditcard.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119",
"method": "GET",
"contentType": "application/javascript"
}
]
}
Uniform Responses
When a POST
or PATCH
request is performed, the whole target resource
representation is returned in the response, as when performing a GET
request on the resource URL. This is an economic approach that limits the
number of necessary GET
requests.
Expansion
The payment resource contain the ID of related sub-resources in its response
properties. These sub-resources can be expanded inline by using the request
parameter expand
. The Paid
resource would for example be expanded by adding
?$expand=paid
after the paymentOrderId
. This is an effective way to limit
the number of necessary calls to the API, as you return several properties
related to a Payment resource in a single request.
Note that the expand
parameter is available to all API requests but only
applies to the request response. This means that you can use the expand
parameter on a POST
or PATCH
request to get a response containing the
target resource including expanded properties.
This example below add the urls
and authorizations
field inlines to the
response, enabling you to access information from these sub-resources.
HTTP Request with expansion
1
2
GET /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1?$expand=urls,authorizations HTTP/1.1
Host: api.externalintegration.payex.com
To avoid unnecessary overhead, you should only expand the fields you need info about.
Data Types
Some datatypes, like currency, dates and amounts, are managed in a coherent manner across the entire API Platform.
Currency
All currencies are expressed according to the
ISO 4217 standard, e.g SEK
, EUR
, NOK
.
Dates
All dates are expressed according to the ISO 8601
standard that combine dates, time and timezone data into a string, e.g.
2018-09-14T13:21:57.6627579Z
.
Locale
When defining locale, we use the combination of language
and country codes. Our payment menu UI is
currently limited to nb-NO
, sv-SE
, da-DK
fi-FI
and en-US
.
Monetary Amounts
All monetary amounts are entered in the lowest momentary units of the selected currency. The amount of SEK and NOK are in ören/ører, and EUR is in cents. Another way to put it is that the code amount is expressed as if the true amount is multiplied by 100.
True amount | Code amount |
---|---|
NOK 100.00 | 10000 |
SEK 50.00 | 5000 |
€ 10.00 | 1000 |
Migration of E-Commerce to Microsoft Azure - FAQ
We have gathered answers to the most common questions regarding the migration of our e-commerce platform and associated services to Microsoft Azure. The goal is to ensure that this transition takes place as smoothly as possible – without requiring any action from you as an integrated partner.
We are upgrading our data centers to enhance performance, stability and security, while enabling innovation for our customers and partners. As part of this, our e-commerce platform and its services are migrating to Microsoft Azure.
Data protection, privacy, IT security, and information security have always been of utmost importance to us at Swedbank Pay. After careful consideration, we have chosen Microsoft Azure as a secure cloud platform for data storage and services. Azure offers a trusted and reliable solution which meets our high standards for security and privacy.
We will provide an exact date later, but our goal is to carry out the migration gradually, starting in mid-August 2025. You will receive separate information well in advance before it affects you.
This migration means that the e-commerce platform and its services will run on Microsoft’s cloud platform, Microsoft Azure. It is a technical improvement taking place in the background, which will result in enhanced performance for you.
No, there is nothing you need to do. The migration will run its course without impacting your systems or integrations.
No, the transition to Microsoft Azure is planned, and will be carried out, without any interruptions to operations. Services will continue to function as usual throughout the process.
No, all APIs and integrations will remain unchanged. You will continue to use the same technical interfaces as before.
Your customers will not be impacted. Payment flows and services will continue to function as usual, without interruptions or changes.
No, the migration is free of charge and will not result in any additional costs for you.
All data will be stored within the EU/EEA, in compliance with GDPR (General Data Protection Regulation). We have chosen to store all data in two primary data centers in Sweden – one in Gävle and one in Sandviken. The selected backup center is also in Sweden, in Staffanstorp.
Swedbank Pay uploads personal data to Microsoft’s cloud service, Azure. Microsoft will then act as a data processor for Swedbank Pay (or a subprocessor if Swedbank Pay is acting as a data processor for you). This applies even in the case of automated data processing.
According to Microsoft’s standard DPA, data may be transferred to the USA. On July 10, 2023, the EU Commission determined that this is compliant with GDPR, meaning no additional safeguards are required as long as the transfer adheres to relevant GDPR provisions.
Microsoft offers 24/7 support, which means that support personnel may be located globally. The support is focused on the cloud application and generally does not have access to stored data. To access stored data, our approval is required (see question 11 below regarding security measures).
At Swedbank Pay, we use cryptographic techniques to ensure the integrity and confidentiality of the information, both during transmission and at rest. All data is encrypted in transit and at rest.
We have opted for the EU Data Boundary add-on for Microsoft services and control Microsoft’s support access through lockbox functionality, where each access must be approved by us and meet our requirements for the geographic location of support staff (EU or a country with an adequacy decision).
-
Learn more about the EU Data Boundary add-on.
-
Learn more about Lockbox.
We have designed our migration process with a strong focus on security and stability. Each step undergoes thorough testing and checks to ensure everything works correctly. In the event of an issue during the migration, we have procedures in place to quickly identify, address and, if necessary, roll back changes. All steps are monitored, and technical support is available throughout the process. Our goal is to ensure you are not negatively impacted, and we are always here to assist if needed.
Yes, you will have the opportunity to test our e-commerce platform in a Microsoft Azure-based test environment before the migration. We will contact you with more details on how and when you can perform the tests, including any necessary adjustments for your specific solution.
We are here to answer your questions. Where you should direct your inquiries depends on how you are connected to our e-commerce platform:
- Are you a partner or technical provider? Reach out your usual contact person at Swedbank Pay.
For technical questions: Phone: +46 8 411 10 80 Email: support.psp@swedbankpay.se
- Are you connected to our e-commerce platform via a partner or technical provider? Reach out to your contact person at the partner or provider first.
For technical questions: Phone: +46 8 411 10 80 Email: support.psp@swedbankpay.se
- Are you integrated directly with our e-commerce platform at Swedbank Pay? Reach out to your contact person at Swedbank Pay, Key Account Manager (KAM) or Technical Account Manager (TAM).
For technical questions: Phone: +46 8 411 10 80 Email: support.psp@swedbankpay.se