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

Authentication in OP Corporate Banking APIs 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 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.

Sandbox

To test the API in sandbox environment, please send an email at corp-payment-APIs@op.fi.

Production access

The API will be published in production in the summer of 2023.

Usage example

#!/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

Content type
application/json
{
  • "creditorBic": "DEUTDEDE",
  • "creditorAccount": "string",
  • "creditorName": "string"
}

Response samples

Content type
application/json
Example
{
  • "accountReceivability": 5,
  • "accountCredibility": {
    }
}

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

Content type
application/json
{
  • "dataProviderBic": "DEUTDEDE"
}

Response samples

Content type
application/json
Example
{
  • "reason": "BRDP",
  • "dataProvider": [
    ]
}