Overview

You're currently using the beta version of our APIs. All API requests require an API key and an authorization token. See below for more information.


Availability

Our sandbox APIs are available to anyone wanting to test or develop their applications.

To get started with our APIs register yourself and create an app.

When you have an app, you can try our APIs like this:

curl -X GET \
  https://sandbox.apis.op-palvelut.fi/v1/accounts \
  -H 'x-api-key: * your_apps__api-key *' \
  -H 'x-authorization: b6910384440ce06f495976f96a162e2ab1bafbb4' \
  -H 'x-request-id: 111' \
  -H 'x-session-id: 234'

Sandbox environment

This sandbox is your environment to get to know about our APIs. It provides the same APIs as our production environment but with mock data.

Currently the sandbox environment is in beta stage, so some changes to the APIs and request header structure are subject to change.


Authentication

Currently authentication is simulated with static tokens. You can pass along the x-authorization header with one of following tokens to get access to different end-user data:

Token
fdb6c7c24bbc3a2c4144c1848825ab7d3a4ccb43
b6910384440ce06f495976f96a162e2ab1bafbb4
7a66629ddf3691a66eb6466ab7a9f610de531047
3af871a0e3ebfc46f375ff2b63d1414982bd4f76

Security

All requests are made over https to ensure that request payload and headers are encrypted. Be aware that TLS 1.0 and 1.1 versions are nearing their end of life, so we strongly encourage you to use clients that support TLS version 1.2.


API Security Considerations For Production

  • Security requirements and mechanisms for a particular API depends on the risk level of the service and the confidentiality of the data processed.

  • Authentication and authorization requirements are set according to the risk levels as well.

  • As a minimum requirement, confidential data must be protected both in transit and in store.

  • Risk levels are evaluated and security levels and requirements are set accordingly, please see the table below.

Security levelAccess Control Requirements
HighThe client app must be authenticated and authorized to use the API. Strong customer authentication methods are used to authenticate the end-user using the OIDC protocol. The end-user can also be subject to fine grained authorization within the API processing logic. TLS Mutual authentication and encryption is compulsory.
SubstantialThe client app must be authenticated and authorized to use the API. Strong customer authentication of the end-user as well as end-user authorization is often required.
BasicThe client app must be registered and will be authenticated prior to granting access to the API. A user can be a technical user e.g. a system or a process and it must be authorized to use the API. Usually, there is no need to authenticate the end-user, though the user information can be relayed in the payload.
OpenClient application must be registered.
  • Refer to the technical documentation of the API in question for detailed security implementation guidelines.

API Versioning

API's version is embedded in the URI: sandbox.apis.op-palvelut.fi/v1/accounts. The v1 part of the URI is the current major version for the API. When the next major version of the API is published the version number is increased by one e.g. sandbox.apis.op-palvelut.fi/v2/accounts. Backward compatibility between major API versions is not guaranteed and usually previous major version is deprecated when new version is published.


Requests

Every request requires these headers:

NameExampleDescription
x-api-keya161-43ee-b222Consumer application's API key
x-session-idc38a-11e7-abc4Session identifier for in-memory data
x-request-idstringRequest unique identifier (not validated at the moment)
x-authorizationsee authenticationToken for end-user simulation

Rate limiting

Currently requests to all sandbox APIs are limited to 1000 requests / application / day. If the daily limit is reached the server responds with a HTTP status code 429 (see below) along with X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers, which tells the caller that the request limit has been reached.

If you feel that 1000 requests per day isn't enough for your developer application feel free to contact us, along with a description of your usage needs.


Responses

Normal operation of an API request is indicated in a response message by an HTTP status in the range of 200-399.

The list below summarizes HTTP normal operation status codes.

  • 200 OK

    • A successful retrieval or update operation
  • 400 BAD REQUEST

    • The request contained invalid or missing request headers, parameters or payload. A retry of an identical request will not succeed.
  • 401 UNAUTHORIZED

    • Resource access requires user identification. Identity token is missing or invalid.
    • Possible error conditions:

      • Validation errors of headers or payload
      • Missing or malformed content, invalid encoding etc.
  • 429 TOO MANY REQUESTS

    • Optional, used when a request is rejected due to rate limiting.
  • 500 INTERNAL SERVER ERROR

    • A system error, specified in detail by the error data descriptor in the response payload.

      • Possible error conditions include:
      • Runtime exception in a service
      • Application server failure
      • Unrecoverable technical exception
      • Business level exception
  • 503 SERVICE UNAVAILABLE

    • The service exists but it is temporarily unavailable, e.g. due to overload or maintenance. The application server instance is not accepting requests.

Errors

Sometimes the execution of an API call fails and the error situation must be handled. In these cases, the error situation is indicated by proper HTTP status code as defined in response status code listing. In addition to standard HTTP status codes, also custom consumable error descriptors are provided to the client as part of the response payload. The examples below show the structure of an error descriptor in JSON format which is the default format for REST APIs. The error descriptor might contain 1-n errors. If there is an error descriptor in the response, it is the only payload data available. The following table describes the error descriptor content.

FieldRequiredDescription
IdyesA unique identifier for the error event, for example UUID. Generated on the server side when the error occurs.
LevelyesError level can be FATAL, ERROR or WARN. For a FATAL, no retry is likely to succeed without server side maintenance measures. An ERROR may be temporary and the request may be retried later. A WARN level error indicates that as part of the request execution, something went wrong but the end result is ok.
TypeyesAllowed error types are SECURITY, VALIDATION, TECHNICAL and BUSINESS. A BUSINESS type of an error message must include a business specific error code and a an optional detailed error code.
MessageyesA textual description of the error condition.
CodenoAn error code defined by the application, for errors of type BUSINESS only.
DetailedConstraitViolationsnoDetailed map of validation fields and constraints that failed, for errors of type VALIDATION only.

Error descriptor is attached to the response message payload as children of top-level element "errors" in the event of a server side error.

{
    "errors": [
        {
            "id": "G_-20343744:143e886a59f:-7ff9",
            "level": "ERROR",
            "type": "BUSINESS",
            "message": "Account balance exceeded",
            "code": "ACC_ERR_123"
        }
      ]
}

App Registration

First register on our Developer site here If you have already registered, create a new Application here Choose the API products that your application is going to use.

After the application is created you can find your application's API keys in the application table. Use this key in the x-api-key header.

Do not share your API key with the public e.g. public github repo, on a website, in a code sample etc.

You're allowed to share the app key within your team.

When you're done developing your application or service and want start using our production APIs please let us know.

Because this is just a beta version of the developer site, callback url and API secrets are not in use at the moment.


Examples

Get all accounts
curl -X GET \
  https://sandbox.apis.op-palvelut.fi/v1/accounts \
  -H 'x-api-key: * your_api-key *' \
  -H 'x-authorization: b6910384440ce06f495976f96a162e2ab1bafbb4' \
  -H 'x-request-id: 111' \
  -H 'x-session-id: 234'

Will return

[
    {
        "accounId": "064418ca1d292a5112e9804af4dc66df5b90203c",
        "accountType": "710001",
        "iban": "FI2350009421535899",
        "bic": "OKOYFIHH",
        "accountName": "KÄYTTÖTILI",
        "balance": 0,
        "amountAvailable": 0,
        "currency": "EUR",
        "ownerId": "b6910384440ce06f495976f96a162e2ab1bafbb4"
    },
    {...}
]

Stay up to date with our API development

Subscribe to our newsletter and we will keep you up to date when there is new features added


op-cover-banking logo

Banking

Products

prod-accounts

Accounts

Account APIs provide read-only methods to access your accounts and transactions information.

prod-payments

Payments

Payment APIs allows you to initiate and confirm SEPA payments between participants.

About

Banking is OP’s largest business segment providing customers with a comprehensive range of products and services. In the coming years, we will see a big shift in banking as the PSD2 obliges European banks to open their APIs. We consider this as a great opportunity to collaborate with FinTechs and start-ups in expanding the services we offer to our customers.

Development

OP is dedicated to continously develop our Banking APIs. Through our sandbox, at this moment, you can use the Accounts and Payments APIs. When you're ready and want to go live with your service or application, just contact us.

During 2018 we're going to release many more APIs in our sandbox.

Pricing & Usage

Sandbox APIs are free to use although some restrictions on the number of calls apply.

Contact

For all API questions just reach out to api@op.fi and we'll get right back to you.


op-cover-wealth logo

Wealth

Products

prod-fund

Funds

APIs for user's holdings, fund information and creating redemption and subscription orders.

prod-holdings

Holdings

APIs for user's holdings information.

About

Our APIs for mutual funds open new possibilities to embed the concept of saving and investing as part of other service experiences. We offer a set of APIs allowing you to invest in funds, view your current ownerships and their development, as well as redeem ownerships.

Unlike many other products, mutual funds do not have a minimum investment limitation, hence making it possible to accumulate savings over time also through very small one time transactions. Mutual fund APIs make investments accessible to wider customer groups with innovative new distribution arrangements.

Development

We are looking to release more Wealth API Products later this year, in the area of stock market trading and custodies. These APIs will be available in production to selected partners.

Pricing & Usage

Sandbox APIs are free to use although some restrictions on the number of calls apply.

Contact

For all API questions just reach out to api@op.fi and we'll get right back to you.

Feedback & Support

We appreciate any feedback, questions or thoughts you might have. Please include your email address if you want us to reply.


Contact

Contact us at api@op.fi