API docs by Redocly

OP Corporate Transaction Info API (1.0)

Download OpenAPI specification:Download

Support: corp-payment-APIs@op.fi


OP Corporate Transaction Info API provides OP's corporate customers with more information about transactions on their account for reconciliation purposes. The API returns the payer name and payer address for credit transactions on the corporate account when the payment has been originated from an OP account.

Authentication

Authentication in OP Corporate Transaction Info 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 MTLS 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 send an email to 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/

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. 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 "Payer details"
details=$(curl -s ${API_SERVER}/corporate-transaction-info/v1/payer-details \
    --key ${mtlsKey} \
    --cert ${mtlsCertificate} \
    -H "Authorization: Bearer $token" \
    -d '{"archiveId": "20190524593156999999", "accountIban": "FI4550009420888888"}')

echo details | jq -C .

Payer details

Returns name and address of the payer

header Parameters
authorization
required
string
Example: Bearer 6c18c234b1b18b1d97c7043e2e41135c293d0da9

Bearer JWT token

X-Request-ID
string
Example: 1afb1874-5bd5-4c5a-9dbb-21a66ab23a85

Unique identifier for a specific request. Used for debugging purposes

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

Details of the transaction to be queried.

archiveId
required
string [ 16 .. 20 ] characters

Accepted format for the archive id is a string of 16, 18 or 20 characters.

accountIban
required
string

IBAN account which has received the original payment.

Responses

Request samples

Content type
application/json; charset=UTF-8
{
  • "archiveId": "20190524593156999999",
  • "accountIban": "FI4550009420888888"
}

Response samples

Content type
application/json; charset=UTF-8
{
  • "archiveId": "20190524593156999999",
  • "amount": "10.00",
  • "debtorName": "Debbie Debtor",
  • "debtorAddress": {
    }
}