OP Corporate Transaction Filter API (1.0)
Download OpenAPI specification:Download
OP Corporate Transaction Filter returns either debit or credit transactions for one account based on the given search parameters and endpoint used.
Authentication for OP Corporate Transaction Filter 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 the sandbox environment, please send an email to 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 the host in the API examples below with https://corporate-api.apiauth.services.op.fi/
#!/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 acquired 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"
### FILTER CREDIT TRANSACTIONS BY DATE RANGE
echo "Get all credit transactions between 15.1 – 30.1.2020:"
filtered=$(curl -s \
-d '{"accountIban":"FI3859991620004143","startDate":"2020-01-15T00:00:01Z","endDate":"2020-01-30T00:00:01Z"}' \
-H "Content-Type: application/json" \
-H 'Accept: application/json' \
-X POST ${API_SERVER}/corporate-transaction-filter/v2/credit-transactions \
--key ${mtlsKey} \
--cert ${mtlsCertificate} \
-H "Authorization: Bearer $token")
echo -e "\n"
echo -e "FILTERED TRANSACTIONS BETWEEN 15.1 – 30.1.2020:\n"
echo $filtered | jq -C .
### FILTER DEBIT TRANSACTIONS BY REFERENCE
echo "Get debit transactions with a reference 00000000000000396224:"
filtered=$(curl -s \
-d '{"accountIban":"FI3859991620004143","startDate":"2020-01-01T00:00:01Z","endDate":"2020-01-30T00:00:01Z","reference":"00000000000000396224"}' \
-H "Content-Type: application/json" \
-H 'Accept: application/json' \
-X POST ${API_SERVER}/corporate-transaction-filter/v2/debit-transactions \
--key ${mtlsKey} \
--cert ${mtlsCertificate} \
-H "Authorization: Bearer $token")
echo -e "\n"
echo -e "FILTERED TRANSACTION WITH A REFERENCE:\n"
echo $filtered | jq -C .
### FILTER CREDIT TRANSACTIONS BY AMOUNT RANGE AND PAYER NAME
echo "Get payments between €0.00 and €10.00 from a company:"
filtered=$(curl -s \
-d '{"accountIban":"FI3859991620004143","startDate":"2020-01-01T00:00:01Z","endDate":"2020-01-30T00:00:01Z","minAmount":"0.00","maxAmount":"10.00","debtorName":"YRITYS KOLMONEN"}' \
-H "Content-Type: application/json" \
-H 'Accept: application/json' \
-X POST ${API_SERVER}/corporate-transaction-filter/v2/credit-transactions \
--key ${mtlsKey} \
--cert ${mtlsCertificate} \
-H "Authorization: Bearer $token")
echo -e "\n"
echo -e "FILTERED CREDIT TRANSACTIONS BETWEEN €0 AND €10.00 FROM A COMPANY:\n"
echo $filtered | jq -C .
Debit transactions
Returns debit transactions from one account based on search parameters
The parameters accountIban
, startDate
and endDate
are mandatory. Time range is limited between 0–30 days and response to maximum of 10 transactions. You should give additional search parameters to filter transactions. These parameters are described below. If the query resulted in more than 10 transactions, the number of transactions that were left out is returned in the skipped
field. Please adjust the filter parameters accordingly so that the result list corresponds with your needs.
header Parameters
Authorization required | string Example: Bearer 6c18c234b1b18b1d97c7043e2e41135c293d0da9 Bearer JWT token - You can get JWT token by calling |
X-Request-ID | string Example: 1afb1874-5bd5-4c5a-9dbb-21a66ab23a85 Unique identifier for request. Used for debugging purposes |
Request Body schema: application/json
Search Parameters
accountIban required | string IBAN for the account where the debit transactions are being searched |
startDate required | string Start date for transaction query ( ISO8601 Format ) |
endDate required | string End date for transaction query (ISO8601 format) |
type | string Indicates type of the transaction (always DEBIT) |
amount | string Payment amount. Overrides minAmount and maxAmount. |
message | string Payment message. The search parameter can be a substring of a message. |
maxAmount | string Returns transactions below maxAmount |
minAmount | string Returns transactions above minAmount |
reference | string Structured payment reference |
endToEndId | string Unique identification, as assigned by the original initiating party, to unambiguously identify the original transaction. |
creditorName | string Recipient name |
creditorAccount | string Recipient account IBAN |
Responses
Request samples
- Payload
- CURL
{- "type": "DEBIT",
- "amount": "14.00",
- "endDate": "2020-01-15T15:53:00Z",
- "message": "MONEY FOR NOTHING",
- "maxAmount": "20.00",
- "minAmount": "5.00",
- "reference": "00000000026819569389",
- "startDate": "2008-09-15T15:53:00Z",
- "endToEndId": "544652-end2end",
- "accountIban": "FI7450009420999999",
- "creditorName": "MRS. ANOTHER PERSON",
- "creditorAccount": "FI7450009420999999"
}
Response samples
- 200
- 400
- 403
- 500
{- "list": [
- {
- "amount": "12.35",
- "message": "MONEY FOR NOTHING",
- "archiveId": "RF613453354562",
- "debtorBic": "OKOYFIHH",
- "reference": "00000000026819569389",
- "timestamp": "01-31-2020T08:50:13+02:00",
- "valueDate": "2020-03-10",
- "debtorName": "Debtor",
- "endToEndId": "544652-end2end",
- "rfReference": "RF562975",
- "bookingDate": "2020-03-10",
- "creditorBic": "OKOYFIHH",
- "paymentDate": "2020-03-10",
- "creditorName": "MRS. ANOTHER PERSON",
- "debtorAccount": "FI7450009420999999",
- "transactionId": "50009420112088_2019-05-21_20190521599956999617_9",
- "creditorAccount": "FI7450009420999999"
}
], - "skipped": 0
}
Credit transactions
Returns credit transactions from one account based on search parameters
The parameters accountIban
, startDate
and endDate
are mandatory. Time range is limited between 0–30 days and response to maximum of 10 transactions. You should give additional search parameters to filter transactions. These parameters are described below. If the query resulted in more than 10 transactions, the number of transactions that were left out is returned in the skipped
field. Please adjust the filter parameters accordingly so that the result list corresponds with your needs.
header Parameters
Authorization required | string Example: Bearer 6c18c234b1b18b1d97c7043e2e41135c293d0da9 Bearer JWT token - You can get JWT token by calling |
X-Request-ID | string Example: 1afb1874-5bd5-4c5a-9dbb-21a66ab23a85 Unique identifier for request. Used for debugging purposes |
Request Body schema: application/json
Search Parameters
accountIban required | string IBAN for the account where the credit transactions are being searched |
startDate required | string Start date for transaction query ( ISO8601 Format ) |
endDate required | string End date for transaction query ( ISO8601 Format ) |
amount | string Payment amount. Overrides minAmount and maxAmount. |
message | string Payment message. The search parameter can be a substring of a message. |
maxAmount | string Returns transactions below maxAmount |
minAmount | string Returns transactions above minAmount |
reference | string Structured payment reference |
debtorName | string Payer name |
endToEndId | string Unique identification, as assigned by the original initiating party, to unambiguously identify the original transaction. |
Responses
Request samples
- Payload
- CURL
{- "amount": "14.00",
- "endDate": "2020-01-15T15:53:00Z",
- "message": "MONEY FOR NOTHING",
- "maxAmount": "20.00",
- "minAmount": "5.00",
- "reference": "00000000026819569389",
- "startDate": "2008-09-15T15:53:00Z",
- "debtorName": "MR. PERSON",
- "endToEndId": "544652-end2end",
- "accountIban": "FI7450009420999999"
}
Response samples
- 200
- 400
- 403
- 500
{- "list": [
- {
- "type": "CREDIT",
- "amount": "12.35",
- "message": "MONEY FOR NOTHING",
- "archiveId": "RF613453354562",
- "reference": "00000000026819569389",
- "timestamp": "01-31-2020T08:50:13+02:00",
- "valueDate": "2020-03-10",
- "debtorName": "MR. PERSON",
- "endToEndId": "544652-end2end",
- "rfReference": "RF562975",
- "bookingDate": "2020-03-10",
- "creditorBic": "OKOYFIHH",
- "paymentDate": "2020-03-10",
- "creditorName": "Creditor",
- "transactionId": "50009420112088_2019-05-21_20190521599956999617_9",
- "creditorAccount": "FI7450009420999999"
}
], - "skipped": 0
}