Edit me....

Getting started with the API and ASPSP

Open Payments Platform uses OAuth2 (specifically OIDC) for authentication. In the following sections, we have provided step by step instructions on how you will interact with the platform. Throughout this documentation we use brackets to denote variables that need to be replaced with corresponding values. The actual domains to access are two - one for handling auth and one for doing the actual calls. See list below for values in sandbox and production.

Available AUTH_HOST values

Available API_HOST values

Register a client

Register a client to acquire client credentials. Decide what parts of the API you want access to for your new client. At this point you can choose one or several of ASPSP Information, Account Information and Payment Initiation. Read more about these below. You will get a client_id and a client_secret that you can use to authenticate with the platform. The secret will not be stored on our end so it is iportant that you keep track of it. Otherwise you'll have to obtain new credentials in the portal.

General notes about requests

X-Request-ID

All calls accept a header called X-Request-ID - this should be set to a newly generated guid. Denoted in the code with [GUID]. If your client is also a platform it would make sense to accept such an id from the client that calls you. This id is used to trace requests through our systems. Logging it somewhere together with the request will make bug hunting much easeir.

Acquire an access token for ASPSP Information

curl -X POST
    [AUTH_HOST]/connect/token
    -H 'Content-Type: application/x-www-form-urlencoded'
    -d 'client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]&scope=aspspinformation&grant_type=client_credentials'

This post will return a JSON object that looks like this:

{
    "access_token": "[ACCESS_TOKEN]",
    "expires_in": 7776000,
    "token_type": "Bearer"
}

Bring the ACCESS_TOKEN forward to subsequent calls.

Get countries

curl -X GET
    [API_HOST]/psd2/aspspinformation/v1/countries
    -H 'Authorization: Bearer [ACCESS_TOKEN]'
    -H 'X-Request-ID: [GUID]'

Query parameters

  • isoCountryCodes a comma separated list of countries to retrieve. Optional.

Response

{
    "countries": [
        {
            "isoCountryCode": "SE",
            "name": "Sweden"
        },
        {
            "isoCountryCode": "FI",
            "name": "Finland"
        },
        {
            "isoCountryCode": "DE",
            "name": "Germany"
        },
        {
            "isoCountryCode": "DK",
            "name": "Denmark"
        }
    ]
}

Where the country code and name will be according to the ISO 3166-1 alpha-2 standard.

Get one country

curl -X GET \
    [API_HOST]/psd2/aspspinformation/v1/countries/[COUNTRY_CODE]
    -H 'Authorization: Bearer [ACCESS_TOKEN]'
    -H 'X-Request-ID: 6ff9e7ee-2ac2-42d3-a188-c7314d434b9c'

Path parameter

The COUNTRY_CODE parameter should be one of the codes in the ISO 3166-1 alpha-2 standard.

Response

{
    "isoCountryCode": "SE",
    "name": "Sweden"
}

This is exactly the same as in the country list.

Get cities

curl -X GET
    [API_HOST]/psd2/aspspinformation/v1/cities
    -H 'Authorization: Bearer [ACCESS_TOKEN]'
    -H 'X-Request-ID: [GUID]'

Query parameters

  • isoCountryCodes a comma separated list of countries to retrieve cities for. Optional.
  • cityIds a comma separated list of city ids to retrieve. Optional.

The service will return all matches for the queries. So querying for SE and ba9dd929-1408-33a6-3ce2-bc45fcfaaa5c will result in both Stockholm and Helsinki being returned.

Response

{
    "cities": [
        {
            "cityId": "37efa883-c8ad-4ff7-927b-b11b02beb923",
            "name": "Stockholm",
            "isoCountryCode": "SE"
        },
        {
            "cityId": "ba9dd929-1408-33a6-3ce2-bc45fcfaaa5c",
            "name": "Helsinki",
            "isoCountryCode": "FI"
        },
        {
            "cityId": "bb97dd78-835c-9922-e700-a8b5b3f5cbba",
            "name": "Frankfurt",
            "isoCountryCode": "DE"
        },
        {
            "cityId": "8f64d9db-7f38-e13e-cbf8-809e6bc6175c",
            "name": "Copenhagen",
            "isoCountryCode": "DK"
        }
    ]
}

Get one city

curl -X GET
    [API_HOST]/psd2/aspspinformation/v1/cities/[CITY_ID]
    -H 'Authorization: Bearer [ACCESS_TOKEN]'
    -H 'X-Request-ID: [GUID]'

Path parameter

CITY_ID should be one of the ids returned from the "get cities" endpoint.

Response

{
    "cityId": "37efa883-c8ad-4ff7-927b-b11b02beb923",
    "name": "Stockholm",
    "isoCountryCode": "SE"
}

This is exactly as one item in the list returned from the "get cities" endpoint.

Get ASPSPs

curl -X GET
    [API_HOST]/psd2/aspspinformation/v1/aspsps
    -H 'Authorization: Bearer [ACCESS_TOKEN]'
    -H 'X-Request-ID: [GUID]'

Query parameters

  • isoCountryCodes a comma separated list of countries to retrieve ASPSPs for. Optional.
  • cityIds a comma separated list of city ids to retrieve ASPSPs for. Optional.

The service will return all matches for the queries. So it is possible to get all ASPSPs in Sweden and Helsinki by sending in the country code for Sweden and the city id for Helsinki.

Response

{
    "aspsps": [
        {
            "bicFi": "ESSESESS",
            "name": "Skandinaviska Enskilda Banken AB ",
            "logoUrl": "https://openbankingplatform.blob.core.windows.net/image/ESSESESS.png"
        },
        {
            "bicFi": "NDEASESS",
            "name": "Nordea Bank AB",
            "logoUrl": "https://openbankingplatform.blob.core.windows.net/image/NDEASESS.png"
        },
        {
            "bicFi": "HANDSESS",
            "name": "Handelsbanken",
            "logoUrl": "https://openbankingplatform.blob.core.windows.net/image/HANDSESS.png"
        }
    ]
}

Get ASPSP

curl -X GET
    [API_HOST]/psd2/aspspinformation/v1/aspsps/[BICFI]
    -H 'Authorization: Bearer [ACCESS_TOKEN]'
    -H 'X-Request-ID: [GUID]'

Path parameter

  • BICFI ASPSP identifier. It can be known upfront or it can be picked from the previous response.

Response

{
    "city": "Stockholm",
    "country": "Sweden",
    "postalCode": "106 40",
    "streetAddress": "Kungsträdgårdsgatan 8",
    "companyNumber": "502032-9081",
    "phone": "+46-771 365 365",
    "websiteUrl": "https://seb.se/",
    "globalPaymentProducts": [
        "sepa-credit-transfers",
        "domestic"
    ],
    "paymentProducts": [
        "swedish-domestic-private-credit-transfers",
        "swedish-domestic-private-own-accounts-transfers",
        "swedish-domestic-private-bankgiros",
        "swedish-domestic-private-plusgiros",
        "sepa-credit-transfers",
        "cross-border-credit-transfers",
        "high-value-credit-transfers",
        "dk-domestic-credit-transfers",
        "intra-company-credit-transfers",
        "no-domestic-credit-transfers",
        "pl-domestic-credit-transfers",
        "se-domestic-credit-transfers",
        "uk-domestic-credit-transfers"
    ],
    "supportedAuthorizationMethods": [
        {
            "name": "OAuth2",
            "uri": "https://auth.dev.openbankingplatform.com/.well-known/openid-configuration"
        }
    ],
    "bicFi": "ESSESESS",
    "name": "Skandinaviska Enskilda Banken AB ",
    "logoUrl": "https://opeopenbanking.blob.core.windows.net/images/ESSESESS.jpg"
}

This result contains contact details for the bank and information about how to access its services through Open Payments API.

The list of global payment products is generic payments products that we support for all banks (where it makes sense). In this case the swedish bank SEB has support for domestic payments internally in Sweden and sepa payments on the European market. When using these we have a unified API for payments that work across banks. If you want a no hassle experience where the API towards us always is the same - this is the products to use.

The list of payment products is specifically for the bank at hand. When using one of these you have to send payment information in a format the bank will accept.

Read more about the payment initiation API.

Flows of usage

The APIs in this product does not interface directly with the banks but provide information to be able to access banks dynamically. We will add banks continuously and if you get the list of banks from this API you will get access to these new banks automatically without the need to do any coding.

A typical flow in the system may be like this:

  • the user is presented a list of supported countries
  • the user select a country
  • the system retrieves a list of banks for that country
  • the user selects its bank
  • the system moves on to one of the other APIs to get account information or to initiate a payment