API docs by Redocly

OP PSD2 Payment Initiation Service API (v1.1)

Download OpenAPI specification:Download

PSD2 support: tpp-support@op.fi



NOTE: Calling PSD2 APIs with Postman is not supported at this time.

OP PSD2 Payment Initiation Service API (PIS) allows Third-Party Providers (TPP) to create and submit SEPA payments. Check our PSD2 page for more information about the APIs and the regulation.

This is version 1 of our PSD2 PIS API. We recommend using version 2, as version 1 will be deprecated in the near future.

Using this API requires authenticating the client application, and end user authentication and authorization.

See the full workflow for PSD2 PIS API >

Sandbox

PSD2 APIs are available in sandbox free of charge for both licensed and unlicensed developers. Full details for sandbox access.

Production access

Following the regulation, using PSD2 APIs is free of charge also in production. However, a Third-Party Provider has to apply for an AISP/PISP license from a financial authority (e.g. FIN-FSA in Finland) and obtain valid QWAC and QSEAL certificates. Full details for production access.

Access to business accounts

Only the account holder, i.e. the company, can grant TPPs the right to access the company's business accounts. However, technically the company representative, i.e. the business user, is the actor who in practice confirms with their banking codes the access to business accounts for the TPP.

As the business user is not the holder of the account, the user needs an additional access right from the account holder in order to be able to confirm the requests sent by authorized TPPs.

Instructions for the additional access right registration are available at op.fi in Finnish, Swedish, and English.

After this registration, the business user is able to confirm (or reject) the requests sent by TPPs.

SEPA payments

OP PSD2 PIS API supports the initiation of SEPA payments. Payments are considered SEPA payments when:

  • the currency of the payment is Euro,
  • payee’s account number is in IBAN format, and
  • the payee’s account holding bank is located inside the EU/ETA area.

SEPA payment processing in OP PSD2 API:

  1. SEPA payment initiation starts with Create SEPA payment request.
  2. Payment is then submitted using Submit SEPA payment request.
  3. SEPA payments can be initiated as single, bundle or recurring payments.

Single, bundle and recurring SEPA payments:

  • Single payment can contain only one submission in the request indicated by one (1) in the Count field. If Count field is not present, a default value of 1 will be used.
  • Bundle payment contains several SEPA payment elements in the request. Payments in the bundle may be single or recurring payments.
  • Recurring payment is a single payment where the value of the Count field is greater than one (1). For example, if the value in the Count field is five (5), the payment can be submitted five times to the same payee with the same amount.
  • Regardless of the type of the SEPA payments (single, recurring, bundle), the Payment Services User (PSU) can confirm the payments in one go.

SEPA payment schedule:

  • SEPA payments can be initiated and submitted at any point of time on any calendar day, even on non-banking days except for possible maintenance breaks in the OP PSD2 PIS API.
  • After the payment has been submitted to the OP PSD2 PIS API, the payment is processed instantly and debited from the payer’s account. Payment may be rejected later when sent to the receiving bank.
  • If the payee holds an account in OP, the payment will be credited to the payee’s account almost immediately.
  • Payment status can be requested at any point of time on any calendar day.

PISP can revoke the payment in two ways:

  • By "Delete SEPA payment before it’s submitted" for single payment transaction (including also recurring payment).
  • By "Revoke authorization (bundle)" for payment bundle.

SEPA payment with future due date:

  • OP PSD2 PIS API does not schedule SEPA payments to wait for the execution on a desired future due date. That is the responsibility of the PISP. Any payment submitted to OP PSD2 PIS API will be processed and debited immediately.
  • If the PSU wants to initiate a payment with future due date, the PSU can confirm the payment or payments at one go on a certain day, but it is on the responsibility of the PISP to submit the payment(s) on due date as per instructed by the PSU.
  • This applies also to recurring payments as they are certain kind of due date payments which are paid on steady intervals.
  • Please make sure that the access and refresh tokens are still valid at the time of the submission of the payments on due date, especially when the due date is far in the future. If need be, use the refresh token to get new access_token.

Create SEPA payment

See the full workflow for PSD2 PIS API >

header Parameters
Authorization
required
string

An Authorisation Token as per https://tools.ietf.org/html/rfc6750. Represents the Client Application, obtained via Client Credentials Grant.

x-idempotency-key
required
string <= 40 characters ^(?!\s)(.*)(\S)$

Every payment will be created only once per x-idempotency-key.

x-api-key
string

API Key

x-jws-signature
string

A detached JWS signature of the body of the payload. This is required for exemption flow and will be always checked when given. Signature is created using your QSealC.

x-fapi-customer-last-logged-time
string^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Fe...

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address
string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id
string

An RFC4122 UID used as a correlation id.

x-customer-user-agent
string

Indicates the user-agent that the PSU is using.

Request Body schema: application/json; charset=utf-8
One of
required
FinnishReference (string) or CrossBorderReference (string)
required
MonetaryEuroAmount (string)

Amount of the payment, value 0,01 - 999 999 999,99 eur

required
object (SepaPayee)

Payee details. For non-domestic payments (i.e. IBAN not starting with FI) address and country are required.

authorizationId
string

Authorization bundle id. Used to bundle several payments to one authorization. Foreign payments can't be bundled with SEPA payments.

count
number <int32> >= 1

Defines the recurrence of the payment. Default value is 1, i.e. single payment. If the value is higher than 1, then the payment is considered as recurring payment to the same payee with the same amount. Payment can be repeatedly submitted according to the number in count element.

object

Payer element is used to define the debit account. If the debit account is not given in the request, then the PSU must choose the debit account from an account list presented by the ASPSP on the authentication and authorization. PSU can select the debit account during the authorization flow only when it is not given by the TPP.

message
string <= 140 characters

Message for the payee and payer's account statement

ultimatePayee
string <= 70 characters

Name of the ultimate payee aka ultimate creditor

originalPayer
string <= 70 characters

Name of the original payer aka ultimate debtor

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "authorizationId": "string",
  • "amountEUR": "string",
  • "count": 1,
  • "payee": {
    },
  • "payer": {
    },
  • "message": "string",
  • "reference": "string",
  • "ultimatePayee": "string",
  • "originalPayer": "string"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "authorizationId": "string",
  • "amountEUR": "string",
  • "count": 1,
  • "payee": {
    },
  • "payer": {
    },
  • "message": "string",
  • "reference": "string",
  • "ultimatePayee": "string",
  • "originalPayer": "string",
  • "paymentId": "string",
  • "paymentType": "SepaPayment",
  • "detailsOfCharges": "SHA",
  • "paymentOrder": "SEPA",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "status": "Unauthorized",
  • "submissions": [
    ]
}

Get SEPA payment details

path Parameters
paymentId
required
string

Payment ID

header Parameters
x-api-key
string

API Key

Authorization
string

An Authorisation Token as per https://tools.ietf.org/html/rfc6750

x-fapi-customer-last-logged-time
string^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Fe...

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address
string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id
string

An RFC4122 UID used as a correlation id.

x-customer-user-agent
string

Indicates the user-agent that the PSU is using.

Responses

Request samples 

curl -X GET https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v1/sepa-payments/{paymentId} \
-H 'x-api-key: string' \
-H 'Authorization: string' \
-H 'x-fapi-customer-last-logged-time: string' \
-H 'x-fapi-customer-ip-address: string' \
-H 'x-fapi-interaction-id: string' \
-H 'x-customer-user-agent: string' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json; charset=utf-8
{
  • "authorizationId": "string",
  • "amountEUR": "string",
  • "count": 1,
  • "payee": {
    },
  • "payer": {
    },
  • "message": "string",
  • "reference": "string",
  • "ultimatePayee": "string",
  • "originalPayer": "string",
  • "paymentId": "string",
  • "paymentType": "SepaPayment",
  • "detailsOfCharges": "SHA",
  • "paymentOrder": "SEPA",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "status": "Unauthorized",
  • "submissions": [
    ]
}

Delete SEPA payment before it's submitted

path Parameters
paymentId
required
string

Payment ID

header Parameters
x-api-key
string

API Key

Authorization
string

An Authorisation Token as per https://tools.ietf.org/html/rfc6750

x-fapi-customer-last-logged-time
string^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Fe...

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address
string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id
string

An RFC4122 UID used as a correlation id.

x-customer-user-agent
string

Indicates the user-agent that the PSU is using.

Responses

Request samples 

curl -X DELETE https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v1/sepa-payments/{paymentId} \
-H 'x-api-key: string' \
-H 'Authorization: string' \
-H 'x-fapi-customer-last-logged-time: string' \
-H 'x-fapi-customer-ip-address: string' \
-H 'x-fapi-interaction-id: string' \
-H 'x-customer-user-agent: string' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json; charset=utf-8
{
  • "authorizationId": "string",
  • "amountEUR": "string",
  • "count": 1,
  • "payee": {
    },
  • "payer": {
    },
  • "message": "string",
  • "reference": "string",
  • "ultimatePayee": "string",
  • "originalPayer": "string",
  • "paymentId": "string",
  • "paymentType": "SepaPayment",
  • "detailsOfCharges": "SHA",
  • "paymentOrder": "SEPA",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "status": "Unauthorized",
  • "submissions": [
    ]
}

List SEPA payment submissions

path Parameters
paymentId
required
string

Payment ID

header Parameters
x-api-key
string

API Key

Authorization
string

An Authorisation Token as per https://tools.ietf.org/html/rfc6750

x-fapi-customer-last-logged-time
string^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Fe...

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address
string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id
string

An RFC4122 UID used as a correlation id.

x-customer-user-agent
string

Indicates the user-agent that the PSU is using.

Responses

Request samples 

curl -X GET https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v1/sepa-payments/{paymentId}/submissions \
-H 'x-api-key: string' \
-H 'Authorization: string' \
-H 'x-fapi-customer-last-logged-time: string' \
-H 'x-fapi-customer-ip-address: string' \
-H 'x-fapi-interaction-id: string' \
-H 'x-customer-user-agent: string' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json; charset=utf-8
{
  • "submissions": [
    ]
}

Submit SEPA payment

path Parameters
submissionId
required
string^[a-zA-Z0-9.,_\-]{1,40}$

Submission ID generated by TPP. Must be unique per payment.

paymentId
required
string

Payment ID

header Parameters
x-api-key
string

API Key

Authorization
string

An Authorisation Token as per https://tools.ietf.org/html/rfc6750

x-fapi-customer-last-logged-time
string^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Fe...

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address
string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id
string

An RFC4122 UID used as a correlation id.

x-customer-user-agent
string

Indicates the user-agent that the PSU is using.

x-sandbox-scenario
string

Sandbox only parameter for simulating error conditions. Supported values are:

  • InsufficientFunds: Simulates condition where payer account has insufficient funds during submission of payment. * PaymentSystemUnavailable: Simulates error condition where payment submission ends up in Pending state. * FutureSimulation=<DURATION>: Simulates advancement in time expressed in ISO 8601 duration (time) format (PnDTnHnMn.nS). Example: FutureSimulation=PT24H * PaymentFail: Simulates payment submission failure due to unspecified reason. * SandboxAuthorized=<authorizationId>: Simulates authorization allowing by pass of OAuth authorization flow. Used in submission of payment where payment is authorized with sandbox authorize endpoint /authorizations/:authorizationId/sandbox-authorize * PaymentFail=Reason: Simulates payment submission failure due to one of following reason:
    • AccountClosed: the payer account is closed and can not be debited from
    • InvalidPayee: the payee account is unusable and can not be credited to
    • LimitExceeded: account withdrawal limit exceeded
  • PaymentSubmitFailed: Simulates condition where Accepted payment is later rejected. * PaymentSubmitSuccess: Simulates condition where Accepted payment is successfully processed and transions to Submitted
Request Body schema: application/json; charset=utf-8
object

Submission identifier: submission can be retried using same submissionId. API guarantees that submission is only processed once per submissionId. Allows retry also in case of backend failure of e.g. insufficient funds.

Responses

Request samples

Content type
application/json; charset=utf-8
{ }

Response samples

Content type
application/json; charset=utf-8
{
  • "submissionId": "string",
  • "archiveId": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "status": "Accepted"
}

Get SEPA submission

path Parameters
submissionId
required
string^[a-zA-Z0-9.,_\-]{1,40}$

Submission ID generated by TPP. Must be unique per payment.

paymentId
required
string

Payment ID

header Parameters
x-api-key
string

API Key

Authorization
string

An Authorisation Token as per https://tools.ietf.org/html/rfc6750

x-fapi-customer-last-logged-time
string^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Fe...

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address
string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id
string

An RFC4122 UID used as a correlation id.

x-customer-user-agent
string

Indicates the user-agent that the PSU is using.

x-sandbox-scenario
string

Sandbox only parameter for simulating error conditions. Supported values are:

  • InsufficientFunds: Simulates condition where payer account has insufficient funds during submission of payment. * PaymentSystemUnavailable: Simulates error condition where payment submission ends up in Pending state. * FutureSimulation=<DURATION>: Simulates advancement in time expressed in ISO 8601 duration (time) format (PnDTnHnMn.nS). Example: FutureSimulation=PT24H * PaymentFail: Simulates payment submission failure due to unspecified reason. * SandboxAuthorized=<authorizationId>: Simulates authorization allowing by pass of OAuth authorization flow. Used in submission of payment where payment is authorized with sandbox authorize endpoint /authorizations/:authorizationId/sandbox-authorize * PaymentFail=Reason: Simulates payment submission failure due to one of following reason:
    • AccountClosed: the payer account is closed and can not be debited from
    • InvalidPayee: the payee account is unusable and can not be credited to
    • LimitExceeded: account withdrawal limit exceeded
  • PaymentSubmitFailed: Simulates condition where Accepted payment is later rejected. * PaymentSubmitSuccess: Simulates condition where Accepted payment is successfully processed and transions to Submitted

Responses

Request samples 

curl -X GET https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v1/sepa-payments/{paymentId}/submissions/{submissionId} \
-H 'x-api-key: string' \
-H 'Authorization: string' \
-H 'x-fapi-customer-last-logged-time: string' \
-H 'x-fapi-customer-ip-address: string' \
-H 'x-fapi-interaction-id: string' \
-H 'x-customer-user-agent: string' \
-H 'x-sandbox-scenario: string' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json; charset=utf-8
{
  • "submissionId": "string",
  • "archiveId": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "status": "Accepted"
}

Get payment authorization (bundle)

path Parameters
authorizationId
required
string

Authorization ID

header Parameters
Authorization
required
string

An Authorisation Token as per https://tools.ietf.org/html/rfc6750. Represents the Client Application, obtained via Client Credentials Grant.

x-api-key
string

API Key

x-fapi-customer-last-logged-time
string^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Fe...

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address
string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id
string

An RFC4122 UID used as a correlation id.

x-customer-user-agent
string

Indicates the user-agent that the PSU is using.

Responses

Request samples 

curl -X GET https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v1/authorizations/{authorizationId} \
-H 'x-api-key: string' \
-H 'Authorization: string' \
-H 'x-fapi-customer-last-logged-time: string' \
-H 'x-fapi-customer-ip-address: string' \
-H 'x-fapi-interaction-id: string' \
-H 'x-customer-user-agent: string' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json; charset=utf-8
{
  • "authorizationId": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "authorized": "2019-08-24T14:15:22Z",
  • "status": "Unauthorized",
  • "sepaPayments": [
    ],
  • "foreignPayments": [
    ]
}

Revoke authorization (bundle)

All the unsubmitted payment transactions included in the bundle will be revoked. If some of the bundle/recurring payments have already submitted, then the revocation applies only to the remaining payments.

path Parameters
authorizationId
required
string

Authorization ID

header Parameters
Authorization
required
string

An Authorisation Token as per https://tools.ietf.org/html/rfc6750. Represents the Client Application, obtained via Client Credentials Grant.

x-api-key
string

API Key

x-fapi-customer-last-logged-time
string^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Fe...

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address
string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id
string

An RFC4122 UID used as a correlation id.

x-customer-user-agent
string

Indicates the user-agent that the PSU is using.

Responses

Request samples 

curl -X DELETE https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v1/authorizations/{authorizationId} \
-H 'x-api-key: string' \
-H 'Authorization: string' \
-H 'x-fapi-customer-last-logged-time: string' \
-H 'x-fapi-customer-ip-address: string' \
-H 'x-fapi-interaction-id: string' \
-H 'x-customer-user-agent: string' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json; charset=utf-8
{
  • "authorizationId": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "authorized": "2019-08-24T14:15:22Z",
  • "status": "Unauthorized",
  • "sepaPayments": [
    ],
  • "foreignPayments": [
    ]
}

Find payments by authorizationId

path Parameters
authorizationId
required
string

Authorization ID

header Parameters
x-api-key
string

API Key

Authorization
string

An Authorisation Token as per https://tools.ietf.org/html/rfc6750

x-fapi-customer-last-logged-time
string^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Fe...

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address
string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id
string

An RFC4122 UID used as a correlation id.

x-customer-user-agent
string

Indicates the user-agent that the PSU is using.

Responses

Request samples 

curl -X GET https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v1/authorizations/{authorizationId}/payments \
-H 'x-api-key: string' \
-H 'Authorization: string' \
-H 'x-fapi-customer-last-logged-time: string' \
-H 'x-fapi-customer-ip-address: string' \
-H 'x-fapi-interaction-id: string' \
-H 'x-customer-user-agent: string' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json; charset=utf-8
{
  • "payments": [
    ]
}

Foreign payments

OP PSD2 PIS API supports the initiation of foreign payments. Payments are considered foreign payments when any of the following criteria applies:

  • The currency of the payment is not Euro.
  • Payee’s account number is not in IBAN format.
  • The payee’s account holding bank is located outside the EU/ETA area.

OP PSD2 PIS API foreign payment processing:

  1. Foreign payment initiation starts with Create Foreign payment request.
  2. Foreign payment is then submitted immediately by PISP using Submit foreign payment request.

Foreign payment processing schedule:

  • Foreign payment can be submitted at any time of the day, but it will be debited according to scheduled processing cycles.
  • Cut-off time for the same day processing of foreign payments is at 16.00 EET with a few exceptions on shorter banking days when the cut-off time is at 12.00 EET.
  • Foreign payments received after the cut-off time will be processed and debited on the next banking day.
  • Final status of the foreign payment is created after the last processing cycle at end of the banking day the payment is debited, approximately at 24.00 EET.
  • TPPs can check the status with the Get foreign payment submission request.

Revocation of the foreign payment:

  • Revocation of the confirmed foreign payment is possible only prior to the submission of the payment to OP. Already submitted payments cannot be revoked. Revocation must be done through the PISP.

Create Foreign payment

See the full workflow for PSD2 PIS API >

Foreign payment initiation rules:

  • Foreign payments must always be initiated as single payment, i.e. one at a time, and the PISP must submit the payment immediately after the PSU has confirmed the payment request.
  • Foreign payments cannot be recurring payments, i.e. paid repeatedly with the same amount and to the same payee.
  • Foreign payments cannot be part of a bundle either, i.e. several foreign payments included in the request. If the PSU wants to initiate several foreign payments, then each payment must be initiated, confirmed and submitted separately.
header Parameters
Authorization
required
string

An Authorisation Token as per https://tools.ietf.org/html/rfc6750. Represents the Client Application, obtained via Client Credentials Grant.

x-idempotency-key
required
string <= 40 characters ^(?!\s)(.*)(\S)$

Every payment will be created only once per x-idempotency-key.

x-api-key
string

API Key

x-jws-signature
string

A detached JWS signature of the body of the payload. This is required for exemption flow and will be always checked when given. Signature is created using your QSealC.

x-fapi-customer-last-logged-time
string^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Fe...

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address
string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id
string

An RFC4122 UID used as a correlation id.

x-customer-user-agent
string

Indicates the user-agent that the PSU is using.

Request Body schema: application/json; charset=utf-8
amount
required
string <number> (MonetaryAmount) ^\d{1,13}(?:\.\d\d)?$

Positive (greater-than zero) monetary amount.

currency
required
string (Currency) ^[A-Z]{3}$

ISO 4127 currency code

required
object (ForeignPayee)

Payee details for foreign payments.

message
required
string <= 140 characters

Message for the payee and payer's account statement

detailsOfCharges
string
Enum: "SHA" "OUR"

Charge bearer. If not given, then default value of SHA will be used. SHA (default/recommended) = both parties pay their own banking fees OUR = payer pays all the banking fees

paymentOrder
string
Enum: "NORM" "HIGH"

Foreign payment type code. NORM (default) = regular foreign payment HIGH = urgent foreign payment

object
exchangeRateReference
string <= 15 characters

Reference number related to the FX deal for the payment amount. If given, then exchange rate according to the FX deal is used (FX deal = Foreign currency exchange deal). If not given then bank will use the daily exchange rates.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "detailsOfCharges": "SHA",
  • "paymentOrder": "NORM",
  • "amount": "string",
  • "currency": "string",
  • "payee": {
    },
  • "payer": {
    },
  • "message": "string",
  • "exchangeRateReference": "string"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "detailsOfCharges": "SHA",
  • "paymentOrder": "NORM",
  • "amount": "string",
  • "currency": "string",
  • "payee": {
    },
  • "payer": {
    },
  • "message": "string",
  • "exchangeRateReference": "string",
  • "authorizationId": "string",
  • "paymentId": "string",
  • "paymentType": "ForeignPayment",
  • "count": 0,
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "status": "Unauthorized",
  • "submissions": [
    ]
}

Get foreign payment details

path Parameters
paymentId
required
string

Payment ID

header Parameters
x-api-key
string

API Key

Authorization
string

An Authorisation Token as per https://tools.ietf.org/html/rfc6750

x-fapi-customer-last-logged-time
string^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Fe...

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address
string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id
string

An RFC4122 UID used as a correlation id.

x-customer-user-agent
string

Indicates the user-agent that the PSU is using.

Responses

Request samples 

curl -X GET https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v1/foreign-payments/{paymentId} \
-H 'x-api-key: string' \
-H 'Authorization: string' \
-H 'x-fapi-customer-last-logged-time: string' \
-H 'x-fapi-customer-ip-address: string' \
-H 'x-fapi-interaction-id: string' \
-H 'x-customer-user-agent: string' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json; charset=utf-8
{
  • "detailsOfCharges": "SHA",
  • "paymentOrder": "NORM",
  • "amount": "string",
  • "currency": "string",
  • "payee": {
    },
  • "payer": {
    },
  • "message": "string",
  • "exchangeRateReference": "string",
  • "authorizationId": "string",
  • "paymentId": "string",
  • "paymentType": "ForeignPayment",
  • "count": 0,
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "status": "Unauthorized",
  • "submissions": [
    ]
}

Delete foreign payment before it's submitted

path Parameters
paymentId
required
string

Payment ID

header Parameters
x-api-key
string

API Key

Authorization
string

An Authorisation Token as per https://tools.ietf.org/html/rfc6750

x-fapi-customer-last-logged-time
string^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Fe...

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address
string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id
string

An RFC4122 UID used as a correlation id.

x-customer-user-agent
string

Indicates the user-agent that the PSU is using.

Responses

Request samples 

curl -X DELETE https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v1/foreign-payments/{paymentId} \
-H 'x-api-key: string' \
-H 'Authorization: string' \
-H 'x-fapi-customer-last-logged-time: string' \
-H 'x-fapi-customer-ip-address: string' \
-H 'x-fapi-interaction-id: string' \
-H 'x-customer-user-agent: string' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json; charset=utf-8
{
  • "detailsOfCharges": "SHA",
  • "paymentOrder": "NORM",
  • "amount": "string",
  • "currency": "string",
  • "payee": {
    },
  • "payer": {
    },
  • "message": "string",
  • "exchangeRateReference": "string",
  • "authorizationId": "string",
  • "paymentId": "string",
  • "paymentType": "ForeignPayment",
  • "count": 0,
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "status": "Unauthorized",
  • "submissions": [
    ]
}

List foreign payment submissions

path Parameters
paymentId
required
string

Payment ID

header Parameters
x-api-key
string

API Key

Authorization
string

An Authorisation Token as per https://tools.ietf.org/html/rfc6750

x-fapi-customer-last-logged-time
string^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Fe...

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address
string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id
string

An RFC4122 UID used as a correlation id.

x-customer-user-agent
string

Indicates the user-agent that the PSU is using.

Responses

Request samples 

curl -X GET https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v1/foreign-payments/{paymentId}/submissions \
-H 'x-api-key: string' \
-H 'Authorization: string' \
-H 'x-fapi-customer-last-logged-time: string' \
-H 'x-fapi-customer-ip-address: string' \
-H 'x-fapi-interaction-id: string' \
-H 'x-customer-user-agent: string' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json; charset=utf-8
{
  • "submissions": [
    ]
}

Submit foreign payment

path Parameters
submissionId
required
string^[a-zA-Z0-9.,_\-]{1,40}$

Submission ID generated by TPP. Must be unique per payment.

paymentId
required
string

Payment ID

header Parameters
x-api-key
string

API Key

Authorization
string

An Authorisation Token as per https://tools.ietf.org/html/rfc6750

x-fapi-customer-last-logged-time
string^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Fe...

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address
string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id
string

An RFC4122 UID used as a correlation id.

x-customer-user-agent
string

Indicates the user-agent that the PSU is using.

x-sandbox-scenario
string

Sandbox only parameter for simulating error conditions. Supported values are:

  • InsufficientFunds: Simulates condition where payer account has insufficient funds during submission of payment. * PaymentSystemUnavailable: Simulates error condition where payment submission ends up in Pending state. * FutureSimulation=<DURATION>: Simulates advancement in time expressed in ISO 8601 duration (time) format (PnDTnHnMn.nS). Example: FutureSimulation=PT24H * PaymentFail: Simulates payment submission failure due to unspecified reason. * SandboxAuthorized=<authorizationId>: Simulates authorization allowing by pass of OAuth authorization flow. Used in submission of payment where payment is authorized with sandbox authorize endpoint /authorizations/:authorizationId/sandbox-authorize * PaymentFail=Reason: Simulates payment submission failure due to one of following reason:
    • AccountClosed: the payer account is closed and can not be debited from
    • InvalidPayee: the payee account is unusable and can not be credited to
    • LimitExceeded: account withdrawal limit exceeded
  • PaymentSubmitFailed: Simulates condition where Accepted payment is later rejected. * PaymentSubmitSuccess: Simulates condition where Accepted payment is successfully processed and transions to Submitted
Request Body schema: application/json; charset=utf-8
object

Submission identifier: submission can be retried using same submissionId. API guarantees that submission is only processed once per submissionId. Allows retry also in case of backend failure of e.g. insufficient funds.

Responses

Request samples

Content type
application/json; charset=utf-8
{ }

Response samples

Content type
application/json; charset=utf-8
{
  • "submissionId": "string",
  • "archiveId": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "status": "Accepted"
}

Get foreign payment submission

path Parameters
submissionId
required
string^[a-zA-Z0-9.,_\-]{1,40}$

Submission ID generated by TPP. Must be unique per payment.

paymentId
required
string

Payment ID

header Parameters
x-api-key
string

API Key

Authorization
string

An Authorisation Token as per https://tools.ietf.org/html/rfc6750

x-fapi-customer-last-logged-time
string^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Fe...

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address
string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id
string

An RFC4122 UID used as a correlation id.

x-customer-user-agent
string

Indicates the user-agent that the PSU is using.

x-sandbox-scenario
string

Sandbox only parameter for simulating error conditions. Supported values are:

  • InsufficientFunds: Simulates condition where payer account has insufficient funds during submission of payment. * PaymentSystemUnavailable: Simulates error condition where payment submission ends up in Pending state. * FutureSimulation=<DURATION>: Simulates advancement in time expressed in ISO 8601 duration (time) format (PnDTnHnMn.nS). Example: FutureSimulation=PT24H * PaymentFail: Simulates payment submission failure due to unspecified reason. * SandboxAuthorized=<authorizationId>: Simulates authorization allowing by pass of OAuth authorization flow. Used in submission of payment where payment is authorized with sandbox authorize endpoint /authorizations/:authorizationId/sandbox-authorize * PaymentFail=Reason: Simulates payment submission failure due to one of following reason:
    • AccountClosed: the payer account is closed and can not be debited from
    • InvalidPayee: the payee account is unusable and can not be credited to
    • LimitExceeded: account withdrawal limit exceeded
  • PaymentSubmitFailed: Simulates condition where Accepted payment is later rejected. * PaymentSubmitSuccess: Simulates condition where Accepted payment is successfully processed and transions to Submitted

Responses

Request samples 

curl -X GET https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v1/foreign-payments/{paymentId}/submissions/{submissionId} \
-H 'x-api-key: string' \
-H 'Authorization: string' \
-H 'x-fapi-customer-last-logged-time: string' \
-H 'x-fapi-customer-ip-address: string' \
-H 'x-fapi-interaction-id: string' \
-H 'x-customer-user-agent: string' \
-H 'x-sandbox-scenario: string' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json; charset=utf-8
{
  • "submissionId": "string",
  • "archiveId": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "status": "Accepted"
}

Get payment authorization (bundle)

path Parameters
authorizationId
required
string

Authorization ID

header Parameters
Authorization
required
string

An Authorisation Token as per https://tools.ietf.org/html/rfc6750. Represents the Client Application, obtained via Client Credentials Grant.

x-api-key
string

API Key

x-fapi-customer-last-logged-time
string^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Fe...

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address
string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id
string

An RFC4122 UID used as a correlation id.

x-customer-user-agent
string

Indicates the user-agent that the PSU is using.

Responses

Request samples 

curl -X GET https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v1/authorizations/{authorizationId} \
-H 'x-api-key: string' \
-H 'Authorization: string' \
-H 'x-fapi-customer-last-logged-time: string' \
-H 'x-fapi-customer-ip-address: string' \
-H 'x-fapi-interaction-id: string' \
-H 'x-customer-user-agent: string' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json; charset=utf-8
{
  • "authorizationId": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "authorized": "2019-08-24T14:15:22Z",
  • "status": "Unauthorized",
  • "sepaPayments": [
    ],
  • "foreignPayments": [
    ]
}

Revoke authorization (bundle)

All the unsubmitted payment transactions included in the bundle will be revoked. If some of the bundle/recurring payments have already submitted, then the revocation applies only to the remaining payments.

path Parameters
authorizationId
required
string

Authorization ID

header Parameters
Authorization
required
string

An Authorisation Token as per https://tools.ietf.org/html/rfc6750. Represents the Client Application, obtained via Client Credentials Grant.

x-api-key
string

API Key

x-fapi-customer-last-logged-time
string^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Fe...

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address
string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id
string

An RFC4122 UID used as a correlation id.

x-customer-user-agent
string

Indicates the user-agent that the PSU is using.

Responses

Request samples 

curl -X DELETE https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v1/authorizations/{authorizationId} \
-H 'x-api-key: string' \
-H 'Authorization: string' \
-H 'x-fapi-customer-last-logged-time: string' \
-H 'x-fapi-customer-ip-address: string' \
-H 'x-fapi-interaction-id: string' \
-H 'x-customer-user-agent: string' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json; charset=utf-8
{
  • "authorizationId": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "authorized": "2019-08-24T14:15:22Z",
  • "status": "Unauthorized",
  • "sepaPayments": [
    ],
  • "foreignPayments": [
    ]
}

Find payments by authorizationId

path Parameters
authorizationId
required
string

Authorization ID

header Parameters
x-api-key
string

API Key

Authorization
string

An Authorisation Token as per https://tools.ietf.org/html/rfc6750

x-fapi-customer-last-logged-time
string^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Fe...

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address
string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id
string

An RFC4122 UID used as a correlation id.

x-customer-user-agent
string

Indicates the user-agent that the PSU is using.

Responses

Request samples 

curl -X GET https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v1/authorizations/{authorizationId}/payments \
-H 'x-api-key: string' \
-H 'Authorization: string' \
-H 'x-fapi-customer-last-logged-time: string' \
-H 'x-fapi-customer-ip-address: string' \
-H 'x-fapi-interaction-id: string' \
-H 'x-customer-user-agent: string' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json; charset=utf-8
{
  • "payments": [
    ]
}

Sandbox-only features

This endpoint can be used in sandbox to authorize payment directly, skipping OAuth.

path Parameters
authorizationId
required
string

Authorization ID

Responses

Request samples 

curl -X POST https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v1/authorizations/{authorizationId}/sandbox-authorize \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json; charset=utf-8
{
  • "authorizationId": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "authorized": "2019-08-24T14:15:22Z",
  • "status": "Unauthorized",
  • "sepaPayments": [
    ],
  • "foreignPayments": [
    ]
}

This endpoint can be used in sandbox to reject payment directly, skipping OAuth.

path Parameters
authorizationId
required
string

Authorization ID

Responses

Request samples 

curl -X POST https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v1/authorizations/{authorizationId}/sandbox-reject \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json; charset=utf-8
{
  • "authorizationId": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "authorized": "2019-08-24T14:15:22Z",
  • "status": "Unauthorized",
  • "sepaPayments": [
    ],
  • "foreignPayments": [
    ]
}