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

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/

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

Payload
CURL

Content type

application/json

{"creditorBic": "DEUTDEDE",
"creditorAccount": "string",
"creditorName": "string"
}

Response samples

200
400
500

Content type

application/json

Example

Successful account verification and name matching

{"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

Content type

application/json

{"dataProviderBic": "DEUTDEDE"
}

Response samples

200
400
500

Content type

application/json

Example

BIC is registered as a data provider

{"reason": "BRDP",
"dataProvider": [{"bic": "TGBATRIS",
"name": "GARANTI Bank",
"relatedDataProvider": [{"bic": "TGBAMTMT",
"name": "GARANTI Bank"
}
]
}
]
}