OP Corporate Service Provider API (1.0)

Download OpenAPI specification:Download


OP Corporate Service Provider API allows registered service providers to manage and view mandates related to OP Corporate Banking APIs. See the documentation for currently available API products:

OP Corporate Account Data API
OP Corporate Payment API
OP Corporate Refund API
OP Corporate Transaction Filter API
OP Corporate Transaction Info API

Authentication

Authentication in OP Corporate Service Provider API 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 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 the sandbox environment, please request sandbox credentials by email at corp-payment-APIs@op.fi.

Production access

You can get production access for this API by registering as a service provider on OP API Admin.

To use these APIs in production you should replace the host in the API examples below with https://corporate-api.apiauth.services.op.fi/

Change log

V1.0 (12/2021)

Initial version

Usage example

#!/bin/bash

# To run this you need openssl and jq installed.

# Steps for registering the required keys and certificates
# 1. A valid service provider agreement created on 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
# 6. Payment signing private key generated: openssl genrsa -out sandbox-signing.key 4096
# 7. Signing csr request: openssl req -new -key sandbox-signing.key -out sandbox-signing.csr
# 8. Signing KID (key identifier) received from OP API Admin by submitting the sandbox-signing.csr.

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

# Credentials request signing keys
signingKey="sandbox-signing.key"
signingKid="TODO and here signing KID"

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 mandate listing"
contracts=$(curl -s ${API_SERVER}/corporate-service-provider/v1/mandates \
--key ${mtlsKey} \
--cert ${mtlsCertificate} \
-H "Authorization: Bearer $token")

echo $contracts | jq -C .

COMPANYID=$(echo $contracts | jq -r .[0].companyId)

echo "Fetching mandate info for company $COMPANYID"
contractinfo=$(curl -s ${API_SERVER}/corporate-service-provider/v1/mandates/$COMPANYID \
--key ${mtlsKey} \
--cert ${mtlsCertificate} \
-H "Authorization: Bearer $token")

echo $contractinfo | jq -C .

## Generate credentials with signature

# Sample credential request with dummy data
credentialRequest="{\"contractId\":\"1234567\"}"

## Signing the payload is mandatory for credential generation requests

# Issued at, in unix timestamp format
IAT=$(date +%s)

# Form the JWS header with mandatory fields
HEADER="{\"b64\":false,\"crit\":[\"b64\",\"urn:op.api.iat\"],\"alg\":\"RS256\",\"urn:op.api.iat\":${IAT},\"kid\":\"${signingKid}\"}"

# Base64 encode the header. JWT-encoding is slightly different from default output of base64, so do some transforming to make the output url-safe, and remove trailing padding (=).
HEADER_ENC=$(echo -n "${HEADER}" | base64 | tr -- '+/=' '-_ ' | tr -d '[:space:]')

# Sign the header and payload. The signature calculation in the detached body JWS is slightly different from the standard way, as the payload is not base64-encoded
# before signing, but included as-is in the signature plaintext. The signing algorithm is RS256, also known as "RSA Digital Signature Algorithm with SHA-256".
# The resulting signature is base64-encoded, and the same url-safe transformations are applied.
SIGNATURE=$(echo -n "${HEADER_ENC}.${credentialRequest}" | openssl dgst -sha256 -sign ${signingKey} -binary | openssl base64 -e -A | tr -- '+/=' '-_ ' | tr -d '[:space:]')

# The signature header includes the base64-encoded JWS header, followed by two dots (..), and the base64-urlsafe-encoded signature. The actual message payload is not
# repeated in the signature
REQ_SIGNATURE="${HEADER_ENC}..${SIGNATURE}"

# The signature is included in the "X-Req-Signature" header.
echo "Sending request to get Client ID and Secret"
clientCredentials=$(curl -s ${API_SERVER}/corporate-service-provider/v1/mandates/$COMPANYID/keys \
    --key ${mtlsKey} \
    --cert ${mtlsCertificate} \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $token" \
    -H "X-Req-Signature: ${REQ_SIGNATURE}" \
    -d "$credentialRequest")

echo $clientCredentials | jq -C .

Mandates

Returns all mandates given to your company by client companies

header Parameters
authorization
required
string

Bearer JWT token

X-Request-ID
string

Unique identifier for a specific request. Used for debugging purposes

Responses

Request samples

curl -X GET https://sandbox.apiauth.aws.op-palvelut.net/corporate-service-provider/v1/mandates \
-H 'authorization: string' \
-H 'X-Request-ID: string' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' 

Response samples

Content type
application/json; charset=UTF-8
[
  • {
    }
]

Mandates per company

Returns mandates for a single client company with given business ID.

path Parameters
companyId
required
string

Business ID (Business Identity Code) for the company whose mandates are queried.

header Parameters
authorization
required
string

Bearer JWT token

X-Request-ID
string

Unique identifier for a specific request. Used for debugging purposes

Responses

Request samples

curl -X GET https://sandbox.apiauth.aws.op-palvelut.net/corporate-service-provider/v1/mandates/{companyId} \
-H 'authorization: string' \
-H 'X-Request-ID: string' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' 

Response samples

Content type
application/json; charset=UTF-8
[
  • {
    }
]

Generate Client ID and Secret

This endpoint can be used to generate OAuth credentials for the client company that has given you a mandate. On the first time both Client ID and Client Secret are generated for the contract. Later on Client ID stays the same and only Client Secret is updated.

path Parameters
companyId
required
string

Business ID (Business Identity Code) for the company whose mandates are queried.

header Parameters
authorization
required
string

Bearer JWT token

X-Req-Signature
required
string

Body signature

X-Request-ID
string

Unique identifier for a specific request. Used for debugging purposes

Request Body schema: application/json; charset=UTF-8

Contract ID for which the credentials want to be generated.

contractId
string

ID for the contract for which client secret needs to be generated

Responses

Request samples

Content type
application/json; charset=UTF-8
{
  • "contractId": "7654321"
}

Response samples

Content type
application/json; charset=UTF-8
{
  • "contractId": "1234567",
  • "clientId": "abCd1Ef2ghijK3",
  • "clientSecret": "abCdeFG_12IjkLm-345NOpqR"
}