Swedbank Pay Developer Portal

Welcome to the Swedbank Pay Developer Portal. Please make your choice of product to integrate below or read on for more general information about Swedbank Pay’s API platform. If you are new to Swedbank Pay’s API Platform, you are strongly advised to read this entire page to the end.

Checkout

Speed up checkout by allowing your customers to check-in with Swedbank Pay, and pay with their favorite payment instruments through our payment menu.

Checkout Documentation

Payments

Identify your customer, while we take care of the payment. Choose from our uniform and wide selection of payment instruments.

Payments Documentation

Connection and Protocol

All requests towards Swedbank Pay API Platform are made with HTTP/1.1 over a secure a 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, 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.

Headers

All requests against the API Platform should have a few common headers:

HTTP request

POST /some/resource HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/problem+json; q=1.0, application/json; q=0.9
Authorization: "Bearer 123456781234123412341234567890AB"
Session-Id: 779da454399742248f2942bb064c4707
Forwarded: for=82.115.151.177; host=example.com; proto=https

URI Usage

The base URIs of the API Platform are:

An important part of REST is its use of hypermedia. Instead of having to perform complex state management and hard coding URIs 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.

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 URI. 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. 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 PATCHrequest to get a response containing the target resource including expanded properties.

This example below add the urls and authorizations property inlines to the response, enabling you to access information from these sub-resources.

HTTP request with expansion

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 nodes 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 (ISO 639-1) and country codes (ISO 3166), e.g. nb-NO, sv-SE, 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.

Operations

When a resource is created and during its lifetime, it will have a set of operations that can be performed on it. Which operations that are available in a given state varies depending on payment instrument used, what the access token is authorized to do, etc. A subset of possible operations are described below. Visit the technical reference page of a payment instrument for instrument specific operations.

JSON with Operations

{
    "payment": {},
    "operations": [
        {
            "href": "http://api.externalintegration.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "rel": "update-payment-abort",
            "method": "PATCH"
        },
        {
            "href": "https://ecom.externalintegration.payex.com/creditcard/payments/authorize/afccf3d0016340620756d5ff3e08f69b555fbe2e45ca71f4bd159ebdb0f00065",
            "rel": "redirect-authorization",
            "method": "GET"
        },
        {
            "href": "https://ecom.externalintegration.payex.com/swish/core/scripts/client/px.swish.client.js?token=afccf3d0016340620756d5ff3e08f69b555fbe2e45ca71f4bd159ebdb0f00065",
            "rel": "view-payment",
            "method": "GET",
            "contentType": "application/javascript"
        },
        {
            "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures",
            "rel": "create-capture",
            "method": "POST"
        }
    ]
}

The operations should be performed as described in each response and not as described here in the documentation. Always use the href and method as specified in the response by finding the appropriate operation based on its rel value.

PayeeReference

The payeeReference given when creating transactions and payments has some specific processing rules depending on specifications in the contract.

• It must be unique for every operation, used to ensure exactly-once delivery of a transactional operation from the merchant system.
• Its length and content validation is dependent on whether the transaction.number or the payeeReference is sent to the acquirer.
  1. If you select Option A in the settlement process (Swedbank Pay will handle the settlement), Swedbank Pay will send the transaction.number to the acquirer and the payeeReference may have the format of string(30).
  2. If you select Option B in the settlement process (you will handle the settlement yourself), Swedbank Pay will send the payeeReference to the acquirer and it will be limited to the format of string(12) and all characters must be digits.

Read more about the settlement process here.

Callback

When a change or update from the back-end system are made on a payment or transaction, Swedbank Pay will perform a callback to inform the payee (merchant) about this update.

• Setting a callbackUrl in the HTTP POST API is optional, but highly recommended. If a payer closes the browser window, a network error or something else happens that prevents the payer from being redirect from Swedbank Pay back to the merchant website, the callback is what ensures that you receive information about what happened with the payment.
• When a change or update from the back-end system are made on a payment or transaction, Swedbank Pay will perform an asynchronous server-to-server callback to inform the payee (merchant) about this update.
• Swedbank Pay will make an HTTP POST to the callbackUrl that was specified when the payee (merchant) created the payment.
• When the callbackUrl receives such a callback, an HTTP GET request must be made on the payment or on the transaction. The retrieved payment or transaction resource will give you the necessary information about the recent change/update.
• The callback will be retried if it fails. Below are the retry timings, in seconds from the initial transaction time:
  • 30 seconds
  • 60 seconds
  • 360 seconds
  • 432 seconds
  • 864 seconds
  • 1265 seconds
• The callback is sent from the following IP address: 82.115.146.1
• A callback should return a 200 OK response.

Payment Instrument Callback

{
    "payment": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 222222222
    },
    "transaction": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/<transaction type>/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "number": 333333333
    }
}

The sequence diagram below shows the HTTP POST you will receive from Swedbank Pay, and the two GET requests that you make to get the updated status.

sequenceDiagram
    Participant Merchant
    Participant SwedbankPay as Swedbank Pay

    activate SwedbankPay
    SwedbankPay->>+Merchant: POST <callbackUrl>
    deactivate SwedbankPay
    note left of Merchant: Callback by Swedbank Pay
    Merchant-->>+SwedbankPay: HTTP response
    Merchant->>+SwedbankPay: GET creditcard payment
    deactivate Merchant
    note left of Merchant: First API request
    SwedbankPay-->>+Merchant: payment resource
    deactivate SwedbankPay

Problems

When performing operations against the API, it will respond with a problem message that contain details of the error type if the request could not be successfully performed. Regardless of why the error occurred, the problem message will follow the same structure as specified in the Problem Details for HTTP APIs (RFC 7807) specification.

The structure of a problem message will look like this:

Problem Example

{
    "type": "https://api.payex.com/psp/errordetail/creditcard/inputerror",
    "title": "There was an input error",
    "detail": "Please correct the errors and retry the request",
    "instance": "ec2a9b09-601a-42ae-8e33-a5737e1cf177",
    "status": 400,
    "action": "RetryNewData",
    "problems": [{
        "name": "CreditCardParameters.Issuer",
        "description": "minimum one issuer must be enabled"
    }]
}

Common Problems

All common problem types will have a URI in the format https://api.payex.com/psp/errordetail/<payment-instrument>/<error-type>. The URI is an identifier that you can hard-code and implement logic around. It is currently not not possible to dereference this URI, although that might be possible in the future.

Payment Instrument Specific Problems

Problem types for a specific payment instrument will have a URI in the format https://api.payex.com/psp/errordetail/<payment-instrument>/<error-type>. You can read more about the payment instrument specific problem messages below:

• Card Payments
• Invoice Payments
• Swish Payments

• Vipps Payments