OP Corporate International Payment Tracking API (1.0)

Download OpenAPI specification:Download


OP Corporate International Payment Tracking API provides OP corporate customers up-to-date access to the moves of outgoing international payments.
Currently the API is in development phase, and we welcome any feedback based on the API documentation. The comments and questions may be sent to corp-payment-APIs@op.fi.

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 clientId, clientSecret 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 "Getting payment tracking information..."
details=$(curl -s ${API_SERVER}/international-payment-tracking/v1/payment-details/ \
--key ${mtlsKey} \
--cert ${mtlsCertificate} \
-H "Authorization: Bearer $token" \
-d '{"archiveId": "20190524593156999999", "account": "FI4550009420888888"}'
)

echo "Payment details:"
echo $details | jq -C .

Outbound international payment details

header Parameters
authorization
required
string
Example: Bearer 6c18c234b1b18b1d97c7043e2e41135c293d0da9

Bearer JWT token

x-request-id
required
string <uuid>

Unique identifier for a specific request. Used for debugging purposes.

Request Body schema: application/json

Outbound payments details request

account
required
string^[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}$

Creditor account number

archiveId
required
string [ 16 .. 20 ] characters

Payment archive ID (filing code). The archive ID should have 16, 18 or 20 characters, and 12th character from the right should be the number 5.

Responses

Request samples

Content type
application/json
{
  • "account": "FI4550009420888888",
  • "archiveId": "20190524593156999999"
}

Response samples

Content type
application/json; charset=UTF-8
Example
{
  • "completionTime": "2020-08-30T17:00:00.000Z",
  • "initiationTime": "2020-08-30T09:00:00.000Z",
  • "lastUpdateTime": "2020-08-30T17:00:00.000Z",
  • "steps": [
    ],
  • "status": "COMPLETED",
  • "uetr": "97ed4827-7b6f-4491-a06f-b548d5a7512d"
}