OP Corporate Account Data API (1.6.2)

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. You will be granted a user ID and password to access OP API Admin in the sandbox environment.

Production access

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

To use these APIs in production you should replace host in the API examples below with api.corporate-api.op.fi.

Change log

v1.6.2 (04/2024)

Changes

Released endpoint Transactions V3 in the production environment. With this endpoint, the maximum page size has been extended from 150 to 1000 transactions. In the endpoint response, parameter transactionTypeDescription also has been replaced and enhanced with parameters bookingCode and bookingCodeDescription.
Changed sandbox and production URLs for APIs and OP API Admin

Deprecated

Deprecated Transactions V2

v1.6.1 (01/2024)

Added

Added code examples for all active endpoints. Section Usage example removed.
Added servers information

v1.6 (12/2023)

Added

Added a new endpoint Transactions V3 for retrieving account transactions in the sandbox environment.

v1.5 (12/2023)

Changed

Changed the determination logic of response parameter bookingDate for endpoint Transactions V2. In detail, now the parameter returns the transaction entry date. Added more information and details for response parameters bookingDate, paymentDate and valueDate.

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

Fixed the examples on Transactions and Transactions V2 and added more clarification.

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 new response information (e.g. timestamps).

Deprecated

Deprecated endpoint Transactions

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.

Endpoint Transactions (use Transactions V3 instead)
Endpoint Transactions V2 (use Transactions V3 instead)

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

## OP Corporate Account Data API - Accounts bash script example

#!/bin/bash

# To run this script you need openssl and jq installed.

# Steps for registering the required keys and certificates
# 1. Valid Corporate API contract created in 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 downloaded from OP API Admin as file "sandbox-mtls.crt" by uploading the certificate signing request (CSR) from the previous step

# 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://api.corp-api-sandbox.test.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 .

Response samples

200
400
403
500

Content type

application/json

[{"bic": "OKOYFIHH",
"iban": "FI7450009420999999",
"name": "Companys payroll account",
"balance": "-12.3",
"currency": "EUR",
"surrogateId": "rNEl6nJ-VgIqbIfyNDBPo-Un2SBTa6zMDspKshS3J6fOlQ==",
"productNames": {"property1": "string",
"property2": "string"
}
}
]

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

## OP Corporate Account Data API - Account details bash script example

#!/bin/bash

# To run this script you need openssl and jq installed.

# Steps for registering the required keys and certificates
# 1. Valid Corporate API contract created in 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 downloaded from OP API Admin as file "sandbox-mtls.crt" by uploading the certificate signing request (CSR) from the previous step

# 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://api.corp-api-sandbox.test.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 details for account $ACCOUNTID"
details=$(curl -s
${API_SERVER}/corporate-account-data/v1/accounts/$ACCOUNTID \
--key ${mtlsKey} \
--cert ${mtlsCertificate} \
-H "Authorization: Bearer $token")

echo "Details for account $ACCOUNTID:"
echo $details | jq -C .

Response samples

200
400
403
500

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

curl -X GET https://api.corp-api-sandbox.test.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

200
400
403
500

Content type

application/json

[{"amount": "-12.35",
"message": "More money, more problems",
"currency": "EUR",
"objectId": "50009420112088_2019-05-21_20190521599956999617_9",
"archiveId": "RF613453354562",
"debtorBic": "OKOYFIHH",
"reference": "00000000000000001245",
"rfReference": "RF481245",
"valueDate": "2019-05-01T00:00:00.000Z",
"debtorName": "Debtor",
"bookingDate": "2019-05-01T00:00:00.000Z",
"creditorBic": "OKOYFIHH",
"paymentDate": "2019-05-01T00:00:00.000Z",
"creditorName": "Creditor",
"debtorAccount": "FI7450009420999999",
"creditorAccount": "FI7450009420999999",
"endToEndId": "544652-end2end"
}
]

Transactions V2 Deprecated

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

## OP Corporate Account Data API - Transactions V2 bash script example

#!/bin/bash

# To run this script you need openssl and jq installed.

# Steps for registering the required keys and certificates
# 1. Valid Corporate API contract created in 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 downloaded from OP API Admin as file "sandbox-mtls.crt" by uploading the certificate signing request (CSR) from the previous step

# 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://api.corp-api-sandbox.test.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 transactions for account $ACCOUNTID"
transactions=$(curl -s
${API_SERVER}/corporate-account-data/v2/accounts/$ACCOUNTID/transactions \
--key ${mtlsKey} \
--cert ${mtlsCertificate} \
-H "Authorization: Bearer $token")

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

Response samples

200
400
403
500

Content type

application/json

[{"amount": "-12.35",
"balanceBefore": "100.00",
"balanceAfter": "87.65",
"message": "More money, more problems",
"currency": "EUR",
"objectId": "50009420112088_2019-05-21_20190521599956999617_9",
"archiveId": "20190521599956999617",
"debtorBic": "OKOYFIHH",
"reference": "00000000000000001245",
"rfReference": "RF481245",
"valueDate": "2019-05-01T00:00:00.000Z",
"debtorName": "Debtor",
"bookingDate": "2019-05-01T00:00:00.000Z",
"creditorBic": "OKOYFIHH",
"paymentDate": "2019-05-01T00:00:00.000Z",
"creditorName": "Creditor",
"debtorAccount": "FI7450009420999999",
"creditorAccount": "FI7450009420999999",
"endToEndId": "544652-end2end",
"timestamp": 1556139630605000,
"transactionTypeCode": "101",
"transactionTypeDescription": "NOSTO",
"uetr": "97ed4827-7b6f-4491-a06f-b548d5a7512d"
}
]

Transactions V3

Returns transactions from one account based on the requested time frame.

The account is recognized by surrogateId. You can get the account's surrogateId by calling the endpoint Accounts.

With default query parameters, 50 previous transactions to date will be retrieved. To request account transactions from a specific time frame, you can fill in the optional parameters fromTimestamp and toTimeStamp. Parameter pageSize can be used to define the amount of transactions received per page. Parameter pageToken (available in the response) should be entered should you wish to continue to look up transactions on the following response page(s).

path Parameters

surrogateId

required

string

Account surrogateId. You can get this value by calling endpoint Accounts

query Parameters

fromTimestamp	integer <int64> Example: fromTimestamp=1556139630605000 Start search from this moment in time. Microseconds since January 1, 1970 00:00:00.000 GMT (Gregorian). Timestamp refers to the moment when the transaction was entered into the system. The value must be before toTimestamp and the earliest value which can be used is (current timestamp - 24 months). If no value is given, a default value of (current timestamp - 24 hours) is used.
toTimestamp	integer <int64> Example: toTimestamp=1556139630605000 End search to this moment in time. Microseconds since January 1, 1970 00:00:00.000 GMT (Gregorian). Timestamp refers to the moment when the transaction was entered into the system. The value must be after fromTimestamp. If no value is given, a the current timestamp is used as default.
pageSize	integer <int64> Default: 50 Example: pageSize=100 Amount of transactions to be included in the response. Allowed values: 50, 100, 150, 500 and 1000.
pagingToken	string Example: pagingToken=eyJmcm9tVGltZXN0YW1wIjoxNjUwODUzNTQyOTM4NzY1LCJ0b1RpbWVzdGFtcCI6MTY4MjQxMDQ5NDkzODc2NCwicm93cyI6MiwicGFnZU51bSI6MywibmV4dFRpbWVzdGFtcCI6MTY2NTEyNzA0NDQ3MTQxMn0= Paging token (base64 encoded string) for getting the next page. For the last page, the value of pagingToken is null. Please restrain from modifying any other query parameters when getting the rest of the pages.

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

## OP Corporate Account Data API - Transactions V3 bash script example

#!/bin/bash

# To run this script you need openssl and jq installed.

# Steps for registering the required keys and certificates
# 1. Valid Corporate API contract created in 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 downloaded from OP API Admin as file "sandbox-mtls.crt" by uploading the certificate signing request (CSR) from the previous step

# 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://api.corp-api-sandbox.test.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 transactions for account $ACCOUNTID"
transactions=$(curl -s
${API_SERVER}/corporate-account-data/v3/accounts/$ACCOUNTID/transactions \
--key ${mtlsKey} \
--cert ${mtlsCertificate} \
-H "Authorization: Bearer $token")

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

Response samples

200
400
403
500

Content type

application/json

{"transactions": [{"amount": "-12.35",
"archiveId": "20190521599956999617",
"balanceBefore": "100.00",
"balanceAfter": "87.65",
"bookingCode": "700",
"bookingCodeDescription": "Maksuliikennepalvelu",
"bookingDate": "2019-05-01T00:00:00.000Z",
"creditorAccount": "FI7450009420999999",
"creditorBic": "OKOYFIHH",
"creditorName": "Creditor",
"currency": "EUR",
"debtorAccount": "FI7450009420999999",
"debtorBic": "OKOYFIHH",
"debtorName": "Debtor",
"endToEndId": "544652-end2end",
"message": "More money, more problems",
"objectId": "50009420112088_2019-05-21_20190521599956999617_9",
"paymentDate": "2019-05-01T00:00:00.000Z",
"reference": "00000000000000001245",
"rfReference": "RF481245",
"timestamp": 1556139630605000,
"uetr": "97ed4827-7b6f-4491-a06f-b548d5a7512d",
"valueDate": "2019-05-01T00:00:00.000Z"
}
],
"pagingToken": "27dd4a26-9f83-4851-80e2-991356f39552"
}