OP Corporate Account Verification API (1.0.1)
Download OpenAPI specification:Download
OP Corporate Account Verification API enables OP corporate customers to verify their business partner's
bank accounts. In some cases, it is also possible to do a name match check before initiating payments
(endpoint Verify account).
Before verifying the account, the receiver bank's account verification and name match checking abilities
can be validated with the API (endpoint Validate data provider).
Authentication in OP Corporate Banking APIs 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 client 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.
#!/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 "Validating data provider..."
validationResult=$(curl -s \
-d '{"dataProviderBic":"DEUTDEDE"}' \
-X POST ${API_SERVER}/account-verification/v1/data-provider-validation \
--key ${mtlsKey} \
--cert ${mtlsCertificate} \
-H "Authorization: Bearer $token")
echo "Validation result:"
echo $validationResult | jq -C .
echo "Verifying account..."
verificationResult=$(curl -s \
-d '{"creditorBic":"DEUTDEDE", "creditorAccount":"DE121234123412", "creditorName":"Bene Bene"}' \
-X POST ${API_SERVER}/account-verification/v1/verification \
--key ${mtlsKey} \
--cert ${mtlsCertificate} \
-H "Authorization: Bearer $token")
echo "Verification result:"
echo $verificationResult | jq -C .
Verify account
The service verifies that the given creditor account exists and that it's able to receive incoming funds. In addition, the service also makes an attempt to verify the creditor account credibility by matching the given creditor name with the creditor account owner name (only if the data provider bank supports it, see details below).
Verification responses
The verification response depends on the verification method applied at runtime
as well as the scope of validation services provided by the data provider. The verification response is split between
response parameter accountReceivability and accountCredibility.beneficiaryNameMatch indicating the beneficiary accounts
ability to receive funds and its credibility to be owned by the input party.
Verification response interpretation
The service provider or OP does not take liability for the verification responses and does not
provide any guarantee on the outcome of an actual transaction being sent to this account.
The information provided is meant to be as accurate as possible at the time that the request was
processed. The requester must pass the creditor name and the service provider can use this
information as part of the verification or not.
Client user responsiblities
As a consequence of the above and other requirements, the following considerations should be taken into account:
- -The service shall be used for information purposes only in anticipation of sending payment transactionspayment
- -OP shall not take any liability for any direct/indirect damages incurred
- -The request responses shall not be cached
header Parameters
| x-request-id required | string <uuid> Unique identifier for a specific request. Used for debugging purposes |
| authorization required | string Bearer JWT token |
Request Body schema: application/json
Verify account request
| creditorBic required | string^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3})... Creditor bank BIC |
| creditorAccount required | string [ 1 .. 34 ] characters Creditor account number |
| creditorName required | string [ 1 .. 140 ] characters Creditor name |
Responses
Request samples
- Payload
- CURL
{- "creditorBic": "DEUTDEDE",
- "creditorAccount": "string",
- "creditorName": "string"
}Response samples
- 200
- 400
- 500
{- "accountReceivability": 5,
- "accountCredibility": {
- "beneficiaryNameMatch": 5
}
}Validate data provider
Validates if a bank is able to verify accounts and to do name matching.
Returns all available account verification data provider banks if dataProviderBic is left empty.
header Parameters
| x-request-id required | string <uuid> Unique identifier for a specific request. Used for debugging purposes |
| authorization required | string Bearer JWT token |
Request Body schema: application/json
Validate data provider request
| dataProviderBic | string^[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9... The BIC of the bank to be validated |
Responses
Request samples
- Payload
- CURL
{- "dataProviderBic": "DEUTDEDE"
}Response samples
- 200
- 400
- 500
{- "reason": "BRDP",
- "dataProvider": [
- {
- "bic": "TGBATRIS",
- "name": "GARANTI Bank",
- "relatedDataProvider": [
- {
- "bic": "TGBAMTMT",
- "name": "GARANTI Bank"
}
]
}
]
}