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 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 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/
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 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.
- Response model
TransactionsResponse
(useTransactionsResponseV2
instead) - Endpoint Transactions (use Transactions V2 instead)
#!/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
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
- 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
- CURL
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
- 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://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
- 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-01",
- "debtorName": "Debtor",
- "bookingDate": "2019-05-01",
- "creditorBic": "OKOYFIHH",
- "paymentDate": "2019-05-01",
- "creditorName": "Creditor",
- "debtorAccount": "FI7450009420999999",
- "creditorAccount": "FI7450009420999999",
- "endToEndId": "544652-end2end"
}
]
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 | 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
- CURL
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
- 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": 20190521599957000000,
- "debtorBic": "OKOYFIHH",
- "reference": "00000000000000001245",
- "rfReference": "RF481245",
- "valueDate": "2019-05-01",
- "debtorName": "Debtor",
- "bookingDate": "2019-05-01",
- "creditorBic": "OKOYFIHH",
- "paymentDate": "2019-05-01",
- "creditorName": "Creditor",
- "debtorAccount": "FI7450009420999999",
- "creditorAccount": "FI7450009420999999",
- "endToEndId": "544652-end2end",
- "timestamp": 1556139630605000,
- "transactionTypeCode": 101,
- "transactionTypeDescription": "NOSTO",
- "uetr": "97ed4827-7b6f-4491-a06f-b548d5a7512d"
}
]