OP Corporate Account Data API (1.4)

Download OpenAPI specification:Download


OP Corporate Account Data API provides access to up-to-date information on accounts and account transactions for corporate customer use.

Authentication

Authentication in OP Corporate Account Data API is based on practices from OpenID Connect (OIDC) 1.0 and OAuth 2.0.

Security Considerations

It is extremely important that the Client ID, Client Secret and MTLS certificate private key are not exposed at any point. Together they represent the identity of the client and thereby the corporation. In the possession of an attacker they could be used to make fraudulent API calls potentially causing considerable damage.

Sandbox

To test the API in sandbox environment, please send an email at corp-payment-APIs@op.fi.

Production access

You can get production access for this API on OP API Admin.

To use these APIs against production you should replace host in the API examples below with https://corporate-api.apiauth.services.op.fi/

Change log

V1.4 (09/2022)

Added

  • Added more clarification and special cases for the usage of request parameters maxPast and maxFuture for endpoint Transactions V2

V1.3 (10/2021)

Added

  • All endpoints now support Service Provider initiated calls

Changed

V1.2 (08/2021)

Added

  • New response parameter transactionTypeCode added to endpoint Transactions V2
  • New response parameter transactionTypeDescription added to endpoint Transactions V2

V1.1 (06/2021)

Added

  • New endpoint Transactions V2 added. The new endpoint supports transaction queries with timestamps.

Deprecated

V1.0 (12/2019)

Initial version

Deprecated

The items listed here are still in production, but will be removed at a future release. Therefore it is best to avoid using these items during active development of a client. A notification will be given prior to removal in accordance with the general terms of use.

Usage example

#!/bin/bash

# To run this you need openssl and jq installed.

# Steps for registering the required keys and certificates
# 1. Valid Corporate API contract created through OP API Admin
# 2. OAuth clientId and clientSecret provisioned
# 3. MTLS private key generated: openssl genrsa -out sandbox-mtls.key 4096
# 4. MTLS certificate signing request (CN and other attributes are ignored): openssl req -new -key sandbox-mtls.key -out sandbox-mtls.csr
# 5. Valid MTLS certificate aquired from OP API Admin using the csr from step 4. and in "sandbox-mtls.crt" file

# OAuth credentials
clientId="TODO put here oauth client id"
clientSecret="TODO and here client secret"

# MTLS credentials
mtlsKey="sandbox-mtls.key"
mtlsCertificate="sandbox-mtls.crt"

API_SERVER="https://sandbox-api.apiauth.aws.op-palvelut.net"

echo "Getting access token"

reply=$(curl -s ${API_SERVER}/corporate-oidc/v1/token \
    --key ${mtlsKey} \
    --cert ${mtlsCertificate} \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d "grant_type=client_credentials&client_id=${clientId}&client_secret=${clientSecret}")

token=$(echo $reply | jq -r .access_token)
echo "Access token is: $token"

echo "Fetching account listing"
accounts=$(curl -s ${API_SERVER}/corporate-account-data/v1/accounts \
--key ${mtlsKey} \
--cert ${mtlsCertificate} \
-H "Authorization: Bearer $token")

echo $accounts | jq -C .

ACCOUNTID=$(echo $accounts | jq -r .[0].surrogateId)

echo "Fetching accountInfo for account $ACCOUNTID"

accountinfo=$(curl -s
${API_SERVER}/corporate-account-data/v1/accounts/$ACCOUNTID \
--key ${mtlsKey} \
--cert ${mtlsCertificate} \
-H "Authorization: Bearer $token")

echo $accountinfo | jq -C .

echo "Fetching transactions for account $ACCOUNTID"
transactions=$(curl -s
${API_SERVER}/corporate-account-data/v1/accounts/$ACCOUNTID/transactions \
--key ${mtlsKey} \
--cert ${mtlsCertificate} \
-H "Authorization: Bearer $token")

echo "Ttransactions for account $ACCOUNTID:"
echo $transactions | jq -C .

Accounts

Returns a list of accounts and balances

header Parameters
authorization
required
string
Example: Bearer 6c18c234b1b18b1d97c7043e2e41135c293d0da9

Bearer JWT token

X-Request-ID
string
Example: 1afb1874-5bd5-4c5a-9dbb-21a66ab23a85

Unique identifier for request. Used for debugging purposes

Responses

Request samples

curl -X GET https://sandbox-api.apiauth.aws.op-palvelut.net/corporate-account-data/v1/accounts \
-H 'authorization: string' \
-H 'X-Request-ID: 1afb1874-5bd5-4c5a-9dbb-21a66ab23a85' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' 

Response samples

Content type
application/json
[
  • {
    }
]

Account details for a single account

Returns details of a single account

path Parameters
surrogateId
required
string

Account surrogate token

header Parameters
authorization
required
string
Example: Bearer 6c18c234b1b18b1d97c7043e2e41135c293d0da9

Bearer JWT token

X-Request-ID
string
Example: 1afb1874-5bd5-4c5a-9dbb-21a66ab23a85

Unique identifier for request. Used for debugging purposes

Responses

Request samples

curl -X GET https://sandbox-api.apiauth.aws.op-palvelut.net/corporate-account-data/v1/accounts/{surrogateId} \
-H 'authorization: string' \
-H 'X-Request-ID: 1afb1874-5bd5-4c5a-9dbb-21a66ab23a85' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' 

Response samples

Content type
application/json
{
  • "bic": "OKOYFIHH",
  • "iban": "FI7450009499999999",
  • "dueDate": "29.11.2019",
  • "ownerId": "1234567-8",
  • "currency": "EUR",
  • "netBalance": "222.22",
  • "accountName": "Some name given by client",
  • "creditLimit": 0,
  • "surrogateId": "rNEl6nJ-VgIqbIfyNDBPo-Un2SBTa6zMDspKshS3J6fOlQ==",
  • "accountOwner": "Firstname Lastname",
  • "creationDate": "29.11.2011",
  • "grossBalance": "222.22",
  • "intraDayLimit": "222.22"
}

Transactions Deprecated

Returns transactions from one account based on specified time frame

Account is recognized by surrogateId. You can get account's surrogateId by calling Accounts API call.

Without parameters this method returns 50 most recent transactions. To get earlier transactions you can give optional parameters fromTimestamp and objectId. If you give both of these paramters objectId takes precedence.

This method returns at most 150 transactions. If maxPast + maxFuture > 150 call fails.

path Parameters
surrogateId
required
string

Account surrogateId. You can get this value by using Accounts API call

query Parameters
fromTimestamp
integer <int64>
Example: fromTimestamp=1556139630605000

Focus search around this moment in time. Microseconds since January 1, 1970 00:00:00.000 GMT (Gregorian). Timestamp refers to moment when transaction was entered into transaction system. If you also give objectId parameter, the objectId takes precedence.

objectId
string
Example: objectId=59986910000074_2016-01-01_201601015FVT00000027_0

Focus search around this objectId. Object ID is built based on [BBAN][date][filingId]_[additionalId]. If you also give fromTimestamp, objectId takes precedence.

maxPast
integer <int64>
Default: 50
Example: maxPast=20

Show # of items before focus point

maxFuture
integer <int64>
Default: 0
Example: maxFuture=10

Show # of items after focus point

header Parameters
authorization
required
string
Example: Bearer 6c18c234b1b18b1d97c7043e2e41135c293d0da9

Bearer JWT token

X-Request-ID
string
Example: 1afb1874-5bd5-4c5a-9dbb-21a66ab23a85

Unique identifier for request. Used for debugging purposes

Responses

Request samples

curl -X GET https://sandbox-api.apiauth.aws.op-palvelut.net/corporate-account-data/v1/accounts/{surrogateId}/transactions \
-H 'authorization: string' \
-H 'X-Request-ID: 1afb1874-5bd5-4c5a-9dbb-21a66ab23a85' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' 

Response samples

Content type
application/json
[
  • {
    }
]

Transactions V2

Returns transactions from one account based on specified time frame or specified transaction.

Account is recognized by surrogateId. You can get account's surrogateId by calling Accounts API call.

Without parameters this method returns 50 most recent transactions. To get earlier transactions you can give optional parameters fromTimestamp or objectId. If you give both of these parameters, objectId takes precedence.

This method returns at most 150 transactions. If maxPast + maxFuture > 150, the call fails. (Notice the default values on these parameters.)

Special cases for maxPast and maxFuture usage when fromTimestamp or objectId focus point is specified:

maxPast maxFuture Outcome
empty empty 50 transactions before the focus point returned
0 empty 150 transactions before the focus point returned
empty 0 50 transactions before the focus point returned (maxPast default value applied)
0 0 150 transactions before the focus point returned
empty n>0 Max 150 transactions after the focus point returned (maxFuture takes precedence over maxPast default value)
n>0 p>0 n-1 transactions before and p transactions after the focus point returned
path Parameters
surrogateId
required
string

Account surrogateId. You can get this value by using Accounts API call

query Parameters
fromTimestamp
integer <int64>
Example: fromTimestamp=1556139630605000

Focus search around this moment in time. Microseconds since January 1, 1970 00:00:00.000 GMT (Gregorian). Timestamp refers to moment when transaction was entered into transaction system. If you also give objectId parameter, the objectId takes precedence.

objectId
string
Example: objectId=59986910000074_2016-01-01_201601015FVT00000027_0

Focus search around this objectId. Object ID is built based on [BBAN][date][filingId]_[additionalId]. If you also give fromTimestamp, objectId takes precedence.

maxPast
integer <int64>
Default: 50
Example: maxPast=20

Show # of items before focus point (maximum amount 150).

maxFuture
integer <int64>
Default: 0
Example: maxFuture=10

Show # of items after focus point (maximum amount 150).

header Parameters
authorization
required
string
Example: Bearer 6c18c234b1b18b1d97c7043e2e41135c293d0da9

Bearer JWT token

X-Request-ID
string
Example: 1afb1874-5bd5-4c5a-9dbb-21a66ab23a85

Unique identifier for request. Used for debugging purposes

Responses

Request samples

curl -X GET https://sandbox-api.apiauth.aws.op-palvelut.net/corporate-account-data/v2/accounts/{surrogateId}/transactions \
-H 'authorization: string' \
-H 'X-Request-ID: 1afb1874-5bd5-4c5a-9dbb-21a66ab23a85' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' 

Response samples

Content type
application/json
[
  • {
    }
]