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 in OP Corporate Account Data API is based on practices from OpenID Connect (OIDC) 1.0 and OAuth 2.0.
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.
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.
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.
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 parametersbookingCode
andbookingCodeDescription
. - 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 parametersbookingDate
,paymentDate
andvalueDate
.
V1.4 (09/2022)
Added
- Added more clarification and special cases for the usage of request parameters
maxPast
andmaxFuture
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
- CLI
- C#
- Java
- Node.js
- PHP
- Python
- CURL
## 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
[- {
- "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
- CLI
- C#
- Java
- Node.js
- PHP
- Python
- CURL
## 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
{- "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 | string Example: objectId=59986910000074_2016-01-01_201601015FVT00000027_0 Focus search around this |
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
[- {
- "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 | string Example: objectId=59986910000074_2016-01-01_201601015FVT00000027_0 Focus search around this |
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
- CLI
- C#
- Java
- Node.js
- PHP
- Python
- CURL
## 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
[- {
- "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
- CLI
- C#
- Java
- Node.js
- PHP
- Python
- CURL
## 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
{- "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"
}