{
"openapi": "3.0.1",
"info": {
"title": "OP PSD2 Payment Initiation Service API",
"contact": {
"name": "PSD2 support",
"email": "tpp-support@op.fi"
},
"version": "2.0",
"description": "
\nOP PSD2 Payment Initiation Service API (PIS) allows Third-Party Providers (TPP) to create and submit SEPA payments. [Read more about PSD2 regulation and our APIs.](/psd2)\n
\nUsing this API requires authenticating the client application, and end user authentication and authorization.\n
\nPlease note that calling OP's PSD2 APIs with Postman is not supported at this time.\n
\n[Go to the full workflow for PSD2 PIS API V2 >](/p/workflow-for-op-psd2-payment-initiation-service-api-v2)\n## Terminology\n* AISP: Account Information Service Provider\n* ASPSP: Account Servicing Payment Service Provider\n* PISP: Payment Initiation Service Provider\n* PSP: Payment Service Provider\n* PSU: Payment Service User\n* TPP: Third-Party Provider accessing the API\n\n## Sandbox\n PSD2 APIs are available in sandbox free of charge for both licensed and unlicensed developers. [See full details for sandbox access.](/p/psd2-tpp-setup#user-content-sandbox-access)\n## Production access\n 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 licence from a financial authority (e.g. [FIN-FSA](https://www.finanssivalvonta.fi/en/regulation/regulatory-framework/psd2/) in Finland) and obtain valid [QWAC and QSEAL certificates](https://esignature.ec.europa.eu/efda/tl-browser/#/screen/home). [See full details for production access.](/p/psd2-tpp-setup#user-content-production-access)\n\n## General guidelines related to payments\n[See guidelines for payment services on op.fi.](https://www.op.fi/corporate-customers/information-to-software-suppliers/downloadable-instructions-for-customers) Please note that the guidelines on op.fi are general. Some of the instructions can be payment type, service or channel specific and they are not necessarily applicable to payments initiated through PSD2 PIS API.\n\n## Access to business accounts\n\nOnly the account holder, i.e. the company, can grant TPPs the right to access the company's business accounts. \nHowever, technically the company representative, i.e. the business user, is the actor who in practice confirms with their banking codes \nthe access to business accounts for the TPP.\n
\nAs the business user is not the holder of the account, the user needs an additional access right from the account holder \nin order to be able to confirm the requests sent by authorized TPPs. \n
\nInstructions for the additional access right registration are available at op.fi in [Finnish](https://www.op.fi/web/aspa/ukk/yritykset/yritystilit#heading2), [Swedish](https://www.op.fi/web/aspa/vanliga-fragor/foretagskunder/foretagskonton#heading2), and [English](https://www.op.fi/web/aspa/faq/corporate-customers/corporate-accounts#heading2).\n
\nAfter this registration, the business user is able to confirm or reject the requests sent by TPPs."
},
"tags": [
{
"name": "SEPA payments",
"description": "OP PSD2 PIS API supports the initiation of SEPA payments. A payment is considered a SEPA payment when:\n * the currency of the payment is Euro,\n * payee’s account number is in IBAN format, and\n * the payee’s account holding bank is located inside the EU/ETA area.\n\nSEPA payment processing in OP PSD2 PIS API:\n 1. SEPA payment initiation starts with Create SEPA payment request.\n 2. Payment is then submitted using Submit SEPA payment request.\n 3. SEPA payments can be initiated as immediate, scheduled or recurring payments.\n 4. Payments can be bundled together for authorization with single SCA.\n\nBundle payment authorization:\n * Authorization bundle can contain multiple payments to be authorized with single SCA.\n * Bundle can contain immediate, scheduled and recurring SEPA payments.\n * Payments are bundled together by using the same authorizationId provided by the first payment in the bundle.\n * Regardless of the type of SEPA payment (immediate, recurring or scheduled), the Payment Services User (PSU) can confirm the payments in one go.\n\nImmediate SEPA payments:\n * Immediate SEPA payments are processed immediately after their submission. \n * TPP is provided immediate feedback if the payment was successfully debited to payer account.\n * TPP may also be provided feedback if the payment has been credited to payee account.\n * Payment must be submitted immediately after authorization. For future dated payments use scheduled SEPA payments.\n\nScheduled and recurring SEPA payments:\n * Scheduled and recurring payments are submitted for later processing by the bank at their respective due dates.\n * TPP can fetch the payment status at any time.\n\nSEPA payment schedule:\n * 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.\n * After the payment has been submitted to the OP PSD2 PIS API, the payment can be processed instantly and debited from the payer’s account or deferred to be processed at a later due date. Payment may be rejected later when sent to the receiving bank.\n * If the payee holds an account in OP, the payment will be credited to the payee’s account almost immediately.\n * Payment status can be requested at any point of time on any calendar day.\n * Future dated payments are processed according to OP's normal processing schedule.\n\nPISP can revoke the payment in three ways:\n * by deleting SEPA payment before it is authorized for single payment transaction (including also recurring payment)\n * by revoking authorization (bundle) before it is authorized for payment bundle\n * by cancelling via SCA after it is authorized and before it is submitted for processing for immediate payments or before its due date for scheduled and recurring payments. \n\nPSU can revoke payments in two ways:\n * by requesting PISP to revoke the payment in the above mentioned ways\n * by cancelling the payment in OP's online channels (mobile and web).\n\nNote: PISP also acting as PSP or on behalf of PSP and using their own or PSPs name and account number as payee must provide the ultimatePayee field. For clarification, here ultimate Payee is the merchant/other actor the PSU expects to see in the payment info. For everyone else this is optional. For further information please refer to the [report from the ERPB working group on transparency for retail payment end-users](https://www.ecb.europa.eu/paym/groups/erpb/shared/pdf/15th-ERPB-meeting/Final_report_of_the_ERPB_working_group_on_transparency_for_retail_payments_end_-_users.pdf?e53826e577a16eced647ffe382578861).\n"
},
{
"name": "Foreign payments",
"description": "OP PSD2 PIS API supports the initiation of foreign payments. Payments are considered foreign payments when any of the following criteria apply:\n * The currency of the payment is not Euro.\n * The Payee’s account number is not in IBAN format.\n * The payee’s account holding bank is located outside the EU/ETA area.\n\nOP PSD2 PIS API foreign payment processing:\n 1. Foreign payment initiation starts with Create Foreign payment request.\n 2. A foreign payment is then submitted immediately by PISP using Submit foreign payment request.\n\nForeign payment processing schedule:\n * A foreign payment can be submitted at any time of the day, but it will be debited according to scheduled processing cycles.\n * The 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.\n * Foreign payments received after the cut-off time will be processed and debited on the next banking day.\n * The final status of the foreign payment is created after the last processing cycle at the end of the banking day the payment is debited, approximately at 24.00 EET.\n * TPPs can check the status with the Get foreign payment submission request.\n\nRevocation of the foreign payment:\n * 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.\n"
}
],
"servers": [
{
"url": "https://psd2.mtls.sandbox.apis.op.fi/payments-psd2/v2"
}
],
"paths": {
"/sepa-payments": {
"post": {
"tags": [
"SEPA payments"
],
"summary": "Create SEPA payment",
"description": "[Go to the full workflow for PSD2 PIS API V2 >](/p/workflow-for-op-psd2-payment-initiation-service-api-v2)\n",
"operationId": "createSepaPayment",
"parameters": [
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/ClientCredAuthorizationParam"
},
{
"$ref": "#/components/parameters/x-jws-signature-Param"
},
{
"$ref": "#/components/parameters/x-fapi-customer-last-logged-time-Param"
},
{
"$ref": "#/components/parameters/x-fapi-customer-ip-address-Param"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
},
{
"$ref": "#/components/parameters/x-customer-user-agent-Param"
},
{
"$ref": "#/components/parameters/x-idempotency-key"
}
],
"requestBody": {
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/SepaPaymentRequest"
}
}
}
},
"responses": {
"201": {
"$ref": "#/components/responses/CreateSepaPaymentResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
}
},
"/sepa-payments/{paymentId}": {
"get": {
"tags": [
"SEPA payments"
],
"summary": "Get SEPA payment details",
"operationId": "getSepaPayment",
"parameters": [
{
"$ref": "#/components/parameters/paymentId"
},
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/AuthorizationParam"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
},
{
"$ref": "#/components/parameters/x-sandbox-scenario-Param"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/GetSepaPaymentResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
},
"delete": {
"tags": [
"SEPA payments"
],
"summary": "Delete SEPA payment",
"description": "Deleting payment after it is authorized requires separate SCA approval from PSU.",
"operationId": "revokeSepaPayment",
"parameters": [
{
"$ref": "#/components/parameters/paymentId"
},
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/AuthorizationParam"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/GetSepaPaymentResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
}
},
"/sepa-payments/{paymentId}/submit": {
"post": {
"tags": [
"SEPA payments"
],
"summary": "Submit SEPA payment",
"operationId": "submitSepaPayment",
"parameters": [
{
"$ref": "#/components/parameters/paymentId"
},
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/AuthorizationParam"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
},
{
"$ref": "#/components/parameters/x-sandbox-scenario-Param"
}
],
"requestBody": {
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/SubmitSepaPaymentRequest"
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/SubmitSepaPaymentResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
}
},
"/scheduled-sepa-payments": {
"post": {
"tags": [
"SEPA payments"
],
"summary": "Create scheduled SEPA payment",
"description": "[Go to the full workflow for PSD2 PIS API V2 >](/p/workflow-for-op-psd2-payment-initiation-service-api-v2)\n",
"operationId": "createScheduledSepaPayment",
"parameters": [
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/ClientCredAuthorizationParam"
},
{
"$ref": "#/components/parameters/x-jws-signature-Param"
},
{
"$ref": "#/components/parameters/x-fapi-customer-last-logged-time-Param"
},
{
"$ref": "#/components/parameters/x-fapi-customer-ip-address-Param"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
},
{
"$ref": "#/components/parameters/x-customer-user-agent-Param"
},
{
"$ref": "#/components/parameters/x-idempotency-key"
}
],
"requestBody": {
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/ScheduledSepaPaymentRequest"
}
}
}
},
"responses": {
"201": {
"$ref": "#/components/responses/CreateScheduledSepaPaymentResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
}
},
"/scheduled-sepa-payments/{paymentId}": {
"get": {
"tags": [
"SEPA payments"
],
"summary": "Get scheduled SEPA payment details",
"description": "[Go to the full workflow for PSD2 PIS API V2 >](/p/workflow-for-op-psd2-payment-initiation-service-api-v2)\n",
"operationId": "getScheduledSepaPayment",
"parameters": [
{
"$ref": "#/components/parameters/paymentId"
},
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/AuthorizationParam"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
},
{
"$ref": "#/components/parameters/x-sandbox-scenario-Param"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/GetScheduledSepaPaymentResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
},
"delete": {
"tags": [
"SEPA payments"
],
"summary": "Delete scheduled SEPA payment",
"description": "Deleting payment after it is authorized requires separate SCA approval from PSU.",
"operationId": "revokeScheduledSepaPayment",
"parameters": [
{
"$ref": "#/components/parameters/paymentId"
},
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/AuthorizationParam"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/GetScheduledSepaPaymentResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
}
},
"/scheduled-sepa-payments/{paymentId}/submit": {
"post": {
"tags": [
"SEPA payments"
],
"summary": "Submit scheduled SEPA payment",
"description": "[Go to the full workflow for PSD2 PIS API V2 >](/p/workflow-for-op-psd2-payment-initiation-service-api-v2)\n",
"operationId": "confirmScheduledSepaPayment",
"parameters": [
{
"$ref": "#/components/parameters/paymentId"
},
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/AuthorizationParam"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
},
{
"$ref": "#/components/parameters/x-sandbox-scenario-Param"
}
],
"requestBody": {
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/ConfirmScheduledSepaPaymentRequest"
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/ConfirmScheduledSepaPaymentResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
}
},
"/recurring-sepa-payments": {
"post": {
"tags": [
"SEPA payments"
],
"summary": "Create recurring SEPA payment",
"description": "[Go to the full workflow for PSD2 PIS API V2 >](/p/workflow-for-op-psd2-payment-initiation-service-api-v2)\n",
"operationId": "createRecurringSepaPayment",
"parameters": [
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/ClientCredAuthorizationParam"
},
{
"$ref": "#/components/parameters/x-jws-signature-Param"
},
{
"$ref": "#/components/parameters/x-fapi-customer-last-logged-time-Param"
},
{
"$ref": "#/components/parameters/x-fapi-customer-ip-address-Param"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
},
{
"$ref": "#/components/parameters/x-customer-user-agent-Param"
},
{
"$ref": "#/components/parameters/x-idempotency-key"
}
],
"requestBody": {
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/RecurringSepaPaymentRequest"
}
}
}
},
"responses": {
"201": {
"$ref": "#/components/responses/CreateRecurringSepaPaymentResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
}
},
"/recurring-sepa-payments/{paymentId}": {
"get": {
"tags": [
"SEPA payments"
],
"summary": "Get recurring SEPA payment details",
"description": "[Go to the full workflow for PSD2 PIS API V2 >](/p/workflow-for-op-psd2-payment-initiation-service-api-v2)\n",
"operationId": "getRecurringSepaPayment",
"parameters": [
{
"$ref": "#/components/parameters/paymentId"
},
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/AuthorizationParam"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
},
{
"$ref": "#/components/parameters/x-sandbox-scenario-Param"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/GetRecurringSepaPaymentResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
},
"delete": {
"tags": [
"SEPA payments"
],
"summary": "Delete recurring SEPA payment",
"description": "Deleting payment after it is authorized requires separate SCA approval from PSU.",
"operationId": "revokeRecurringSepaPayment",
"parameters": [
{
"$ref": "#/components/parameters/paymentId"
},
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/AuthorizationParam"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/GetRecurringSepaPaymentResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
}
},
"/recurring-sepa-payments/{paymentId}/submit": {
"post": {
"tags": [
"SEPA payments"
],
"summary": "Confirm recurring SEPA payment",
"description": "[Go to the full workflow for PSD2 PIS API V2 >](/p/workflow-for-op-psd2-payment-initiation-service-api-v2)\n",
"operationId": "confirmRecurringSepaPayment",
"parameters": [
{
"$ref": "#/components/parameters/paymentId"
},
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/AuthorizationParam"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
},
{
"$ref": "#/components/parameters/x-sandbox-scenario-Param"
}
],
"requestBody": {
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/ConfirmRecurringSepaPaymentRequest"
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/ConfirmRecurringSepaPaymentResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
}
},
"/recurring-sepa-payments/{paymentId}/recurrence/{dueDate}": {
"get": {
"tags": [
"SEPA payments"
],
"summary": "Get recurring SEPA payment recurrence details",
"description": "[Go to the full workflow for PSD2 PIS API V2 >](/p/workflow-for-op-psd2-payment-initiation-service-api-v2)\n",
"operationId": "getRecurringSepaPaymentRecurrence",
"parameters": [
{
"$ref": "#/components/parameters/paymentId"
},
{
"$ref": "#/components/parameters/dueDate"
},
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/AuthorizationParam"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/GetRecurringSepaPaymentRecurrenceResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
}
},
"/foreign-payments": {
"post": {
"tags": [
"Foreign payments"
],
"summary": "Create foreign payment",
"description": "[Go to the full workflow for PSD2 PIS API V2 >](/p/workflow-for-op-psd2-payment-initiation-service-api-v2)\n\n Restrictions in initiating foreign payments:\n * Foreign payments must always be initiated as single payments, i.e. one at a time.\n * The PISP must submit the payment immediately after the PSU has confirmed the payment request.\n * Foreign payments cannot be recurring payments, i.e. paid repeatedly with the same amount and to the same payee.\n * Foreign payments cannot be part of a bundle, 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.\n",
"operationId": "createForeignPayment",
"parameters": [
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/ClientCredAuthorizationParam"
},
{
"$ref": "#/components/parameters/x-jws-signature-Param"
},
{
"$ref": "#/components/parameters/x-fapi-customer-last-logged-time-Param"
},
{
"$ref": "#/components/parameters/x-fapi-customer-ip-address-Param"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
},
{
"$ref": "#/components/parameters/x-customer-user-agent-Param"
},
{
"$ref": "#/components/parameters/x-idempotency-key"
}
],
"requestBody": {
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/ForeignPaymentRequest"
}
}
}
},
"responses": {
"201": {
"$ref": "#/components/responses/CreateForeignPaymentResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
}
},
"/foreign-payments/{paymentId}": {
"get": {
"tags": [
"Foreign payments"
],
"summary": "Get foreign payment details",
"operationId": "getForeignPayment",
"parameters": [
{
"$ref": "#/components/parameters/paymentId"
},
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/AuthorizationParam"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
},
{
"$ref": "#/components/parameters/x-sandbox-scenario-Param"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/GetForeignPaymentResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
},
"delete": {
"tags": [
"Foreign payments"
],
"summary": "Delete foreign payment",
"description": "Deleting payment after it is authorized requires separate SCA approval from PSU.",
"operationId": "revokeForeignPayment",
"parameters": [
{
"$ref": "#/components/parameters/paymentId"
},
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/AuthorizationParam"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/GetForeignPaymentResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
}
},
"/foreign-payments/{paymentId}/submit": {
"post": {
"tags": [
"Foreign payments"
],
"summary": "Submit foreign payment",
"operationId": "submitForeignPayment",
"parameters": [
{
"$ref": "#/components/parameters/paymentId"
},
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/AuthorizationParam"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
},
{
"$ref": "#/components/parameters/x-sandbox-scenario-Param"
}
],
"requestBody": {
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/SubmitForeignPaymentRequest"
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/SubmitForeignPaymentResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
}
},
"/authorizations/{authorizationId}": {
"get": {
"tags": [
"SEPA payments",
"Foreign payments"
],
"summary": "Get payment authorization (bundle)",
"operationId": "getAuthorization",
"parameters": [
{
"$ref": "#/components/parameters/authorizationId"
},
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/ClientCredAuthorizationParam"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/GetAuthorizationResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
},
"delete": {
"tags": [
"SEPA payments",
"Foreign payments"
],
"summary": "Revoke authorization (bundle)",
"description": "All the unauthorized payment transactions included in the bundle will be revoked. If bundle is authorized, each payment has to be cancelled via SCA individually.\n",
"operationId": "revokeAuthorization",
"parameters": [
{
"$ref": "#/components/parameters/authorizationId"
},
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/ClientCredAuthorizationParam"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/GetAuthorizationResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
}
},
"/authorizations/{authorizationId}/payments": {
"get": {
"tags": [
"SEPA payments",
"Foreign payments"
],
"summary": "Find payments by authorizationId",
"operationId": "findPaymentsByAuthorizationId",
"parameters": [
{
"$ref": "#/components/parameters/authorizationId"
},
{
"$ref": "#/components/parameters/x-api-key"
},
{
"$ref": "#/components/parameters/AuthorizationParam"
},
{
"$ref": "#/components/parameters/x-fapi-interaction-id-Param"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/GetPaymentsResponse"
},
"default": {
"$ref": "#/components/responses/ApiErrorResponse"
}
}
}
}
},
"components": {
"parameters": {
"x-api-key": {
"name": "x-api-key",
"in": "header",
"description": "API Key",
"required": false,
"schema": {
"type": "string"
}
},
"x-idempotency-key": {
"name": "x-idempotency-key",
"in": "header",
"description": "Every payment will be created only once per x-idempotency-key.",
"required": true,
"schema": {
"type": "string",
"maxLength": 40,
"pattern": "^(?!\\s)(.*)(\\S)$"
}
},
"x-fapi-customer-ip-address-Param": {
"in": "header",
"name": "x-fapi-customer-ip-address",
"required": false,
"description": "The PSU's IP address if the PSU is currently logged in with the TPP.",
"schema": {
"type": "string"
}
},
"x-fapi-interaction-id-Param": {
"in": "header",
"name": "x-fapi-interaction-id",
"required": false,
"description": "An RFC4122 UID used as a correlation ID.",
"schema": {
"type": "string"
}
},
"x-fapi-customer-last-logged-time-Param": {
"in": "header",
"name": "x-fapi-customer-last-logged-time",
"required": false,
"description": "The time when the PSU last logged in with the TPP.\nAll dates in the HTTP headers are represented as RFC 7231 full dates. An example: Sun, 10 Sep 2017 19:43:31 UTC",
"schema": {
"type": "string",
"pattern": "^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \\d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \\d{4} \\d{2}:\\d{2}:\\d{2} (GMT|UTC)$"
}
},
"x-sandbox-scenario-Param": {
"in": "header",
"name": "x-sandbox-scenario",
"required": false,
"description": "Sandbox-only parameter for simulating error conditions. Supported values are:\n* `InsufficientFunds`: Simulates condition where payer account has insufficient funds during submission of payment.\n* `PaymentSystemUnavailable`: Simulates error condition where payment submission ends up in SubmissionPending state.\n* `PaymentFail`: Simulates payment submission failure due to unspecified reason.\n* `PaymentFail=Reason`: Simulates payment submission failure due to one of following reasons:\n * `AccountClosed`: The payer account is closed and cannot be debited from.\n * `InvalidPayee`: The payee account is unusable and cannot be credited to.\n * `LimitExceeded`: Account withdrawal limit exceeded.\n* `PaymentRejected`: Simulates condition where accepted payment is later rejected. Payment status updates on GET payment.\n* `PaymentDebited`: Simulates condition where accepted payment is successfully processed and transitions to debited. Payment status updates on GET payment.\n* `PaymentCredited`: Simulates condition where payment is debited from payer account and credited to payee account. This simulates successful SEPA Instant Credit Transfer and immediately credited OP-OP transfer.\n* `PaymentAccepted`: Simulates condition where payment in SubmissionPending is verified to be processed and awaits confirmation of being debited from payer account.",
"schema": {
"type": "string"
}
},
"AuthorizationParam": {
"in": "header",
"name": "Authorization",
"required": false,
"description": "An authorization token as per the [OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750).",
"schema": {
"type": "string"
}
},
"ClientCredAuthorizationParam": {
"in": "header",
"name": "Authorization",
"schema": {
"type": "string"
},
"required": true,
"description": "An authorization token as per the [OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750). Represents the Client Application, obtained via Client Credentials Grant."
},
"x-jws-signature-Param": {
"in": "header",
"name": "x-jws-signature",
"required": true,
"description": "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.",
"schema": {
"type": "string"
}
},
"x-customer-user-agent-Param": {
"in": "header",
"name": "x-customer-user-agent",
"description": "Indicates the user-agent that the PSU is using.",
"required": true,
"schema": {
"type": "string"
}
},
"paymentId": {
"name": "paymentId",
"in": "path",
"description": "Payment ID",
"required": true,
"schema": {
"type": "string"
}
},
"dueDate": {
"name": "dueDate",
"in": "path",
"description": "Due date",
"required": true,
"schema": {
"type": "string",
"format": "date",
"example": "2022-12-01"
}
},
"authorizationId": {
"name": "authorizationId",
"in": "path",
"description": "Authorization ID",
"required": true,
"schema": {
"type": "string"
}
}
},
"responses": {
"CreateSepaPaymentResponse": {
"description": "Create SEPA payment response",
"headers": {
"x-fapi-interaction-id": {
"description": "An RFC4122 UID used as a correlation ID.",
"schema": {
"type": "string"
}
},
"x-jws-signature": {
"description": "Header containing a detached JWS signature of the body of the payload.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/SepaPaymentDetails"
}
}
}
},
"CreateScheduledSepaPaymentResponse": {
"description": "Create scheduled SEPA payment response",
"headers": {
"x-fapi-interaction-id": {
"description": "An RFC4122 UID used as a correlation ID.",
"schema": {
"type": "string"
}
},
"x-jws-signature": {
"description": "Header containing a detached JWS signature of the body of the payload.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/ScheduledSepaPaymentDetails"
}
}
}
},
"CreateRecurringSepaPaymentResponse": {
"description": "Create recurring SEPA payment response",
"headers": {
"x-fapi-interaction-id": {
"description": "An RFC4122 UID used as a correlation ID.",
"schema": {
"type": "string"
}
},
"x-jws-signature": {
"description": "Header containing a detached JWS signature of the body of the payload.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/RecurringSepaPaymentDetails"
}
}
}
},
"CreateForeignPaymentResponse": {
"description": "Create foreign payment response",
"headers": {
"x-fapi-interaction-id": {
"description": "An RFC4122 UID used as a correlation ID.",
"schema": {
"type": "string"
}
},
"x-jws-signature": {
"description": "Header containing a detached JWS signature of the body of the payload.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/ForeignPaymentDetails"
}
}
}
},
"GetSepaPaymentResponse": {
"description": "Get SEPA payment response",
"headers": {
"x-fapi-interaction-id": {
"description": "An RFC4122 UID used as a correlation ID.",
"schema": {
"type": "string"
}
},
"x-jws-signature": {
"description": "Header containing a detached JWS signature of the body of the payload.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/SepaPaymentDetails"
}
}
}
},
"GetScheduledSepaPaymentResponse": {
"description": "Get scheduled SEPA payment response",
"headers": {
"x-fapi-interaction-id": {
"description": "An RFC4122 UID used as a correlation ID.",
"schema": {
"type": "string"
}
},
"x-jws-signature": {
"description": "Header containing a detached JWS signature of the body of the payload.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/ScheduledSepaPaymentDetails"
}
}
}
},
"ConfirmScheduledSepaPaymentResponse": {
"description": "Confirm scheduled SEPA payment response",
"headers": {
"x-fapi-interaction-id": {
"description": "An RFC4122 UID used as a correlation ID.",
"schema": {
"type": "string"
}
},
"x-jws-signature": {
"description": "Header containing a detached JWS signature of the body of the payload.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/ScheduledSepaPaymentDetails"
}
}
}
},
"GetRecurringSepaPaymentResponse": {
"description": "Get recurring SEPA payment response",
"headers": {
"x-fapi-interaction-id": {
"description": "An RFC4122 UID used as a correlation ID.",
"schema": {
"type": "string"
}
},
"x-jws-signature": {
"description": "Header containing a detached JWS signature of the body of the payload.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/RecurringSepaPaymentDetails"
}
}
}
},
"GetRecurringSepaPaymentRecurrenceResponse": {
"description": "Get recurring SEPA payment recurrence response",
"headers": {
"x-fapi-interaction-id": {
"description": "An RFC4122 UID used as a correlation ID.",
"schema": {
"type": "string"
}
},
"x-jws-signature": {
"description": "Header containing a detached JWS signature of the body of the payload.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/RecurringPaymentRecurrenceDetails"
}
}
}
},
"ConfirmRecurringSepaPaymentResponse": {
"description": "Confirm recurring SEPA payment response",
"headers": {
"x-fapi-interaction-id": {
"description": "An RFC4122 UID used as a correlation ID.",
"schema": {
"type": "string"
}
},
"x-jws-signature": {
"description": "Header containing a detached JWS signature of the body of the payload.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/RecurringSepaPaymentDetails"
}
}
}
},
"GetForeignPaymentResponse": {
"description": "Get foreign payment response",
"headers": {
"x-fapi-interaction-id": {
"description": "An RFC4122 UID used as a correlation ID.",
"schema": {
"type": "string"
}
},
"x-jws-signature": {
"description": "Header containing a detached JWS signature of the body of the payload.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/ForeignPaymentDetails"
}
}
}
},
"SubmitSepaPaymentResponse": {
"description": "Submit SEPA payment response",
"headers": {
"x-fapi-interaction-id": {
"description": "An RFC4122 UID used as a correlation ID.",
"schema": {
"type": "string"
}
},
"x-jws-signature": {
"description": "Header containing a detached JWS signature of the body of the payload.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/SepaPaymentDetails"
}
}
}
},
"SubmitForeignPaymentResponse": {
"description": "Submit foreign payment response",
"headers": {
"x-fapi-interaction-id": {
"description": "An RFC4122 UID used as a correlation ID.",
"schema": {
"type": "string"
}
},
"x-jws-signature": {
"description": "Header containing a detached JWS signature of the body of the payload.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/ForeignPaymentDetails"
}
}
}
},
"GetAuthorizationResponse": {
"description": "Get payment authorization response",
"headers": {
"x-fapi-interaction-id": {
"description": "An RFC4122 UID used as a correlation ID.",
"schema": {
"type": "string"
}
},
"x-jws-signature": {
"description": "Header containing a detached JWS signature of the body of the payload.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/Authorization"
}
}
}
},
"GetPaymentsResponse": {
"description": "Get payment authorization response",
"headers": {
"x-fapi-interaction-id": {
"description": "An RFC4122 UID used as a correlation ID.",
"schema": {
"type": "string"
}
},
"x-jws-signature": {
"description": "Header containing a detached JWS signature of the body of the payload.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/AuthorizationPayments"
}
}
}
},
"ApiErrorResponse": {
"description": "Error response",
"headers": {
"x-fapi-interaction-id": {
"description": "An RFC4122 UID used as a correlation ID.",
"schema": {
"type": "string"
}
},
"x-jws-signature": {
"description": "Header containing a detached JWS signature of the body of the payload.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json; charset=utf-8": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
},
"schemas": {
"SepaPaymentRequest": {
"type": "object",
"properties": {
"authorizationId": {
"type": "string",
"description": "Authorization bundle ID. Used to bundle several payments to one authorization. Foreign payments cannot be bundled with SEPA payments."
},
"amountEUR": {
"type": "string",
"oneOf": [
{
"$ref": "#/components/schemas/MonetaryEuroAmount"
}
],
"description": "Amount of the payment, value 0,01 - 999 999 999,99 euros"
},
"payee": {
"$ref": "#/components/schemas/SepaPayee"
},
"payer": {
"type": "object",
"description": "Payer element is used to define the debit account. If the debit account is not given in the request,\nthen the PSU must choose the debit account from an account list presented by the ASPSP on the authentication and authorization.\nPSU always has the option to change the debit account during authorization flow.",
"properties": {
"iban": {
"$ref": "#/components/schemas/Iban"
}
},
"required": [
"iban"
]
},
"message": {
"type": "string",
"description": "Message for the payee and payer's account statement",
"maxLength": 140
},
"ownMessage": {
"type": "string",
"description": "Message for the payer's account statement. This is not transmitted to the payee.",
"maxLength": 20
},
"reference": {
"type": "string",
"anyOf": [
{
"$ref": "#/components/schemas/FinnishReference"
},
{
"$ref": "#/components/schemas/CrossBorderReference"
}
]
},
"payerReference": {
"type": "string",
"maxLength": 35,
"description": "Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain."
},
"payerIdentifier": {
"type": "object",
"description": "Payer identification such as Business ID (Y-tunnus).",
"properties": {
"type": {
"type": "string",
"enum": [
"BusinessId",
"Unstructured"
]
},
"id": {
"type": "string",
"maxLength": 35
}
}
},
"ultimatePayee": {
"type": "string",
"description": "Name of the ultimate payee, aka the ultimate creditor. Ultimate payee information is required when the PISP acts as PSP and the payee contains the PSP name and account number.",
"maxLength": 70
},
"originalPayer": {
"type": "string",
"description": "Name of the original payer, aka the ultimate debtor",
"maxLength": 70
}
},
"oneOf": [
{
"required": [
"reference",
"amountEUR",
"payee"
]
},
{
"required": [
"message",
"amountEUR",
"payee"
]
}
]
},
"ScheduledSepaPaymentRequest": {
"type": "object",
"properties": {
"authorizationId": {
"type": "string",
"description": "Authorization bundle ID. Used to bundle several payments to one authorization. Foreign payments cannot be bundled with SEPA payments."
},
"amountEUR": {
"type": "string",
"oneOf": [
{
"$ref": "#/components/schemas/MonetaryEuroAmount"
}
],
"description": "Amount of the payment, value 0,01 - 999 999 999,99 euros"
},
"payee": {
"$ref": "#/components/schemas/SepaPayee"
},
"payer": {
"type": "object",
"description": "Payer element is used to define the debit account. If the debit account is not given in the request,\nthen the PSU must choose the debit account from an account list presented by the ASPSP on the authentication and authorization.\nPSU always has the option to change the debit account during authorization flow.",
"properties": {
"iban": {
"$ref": "#/components/schemas/Iban"
}
},
"required": [
"iban"
]
},
"message": {
"type": "string",
"description": "Message for the payee and payer's account statement",
"maxLength": 140
},
"ownMessage": {
"type": "string",
"description": "Message for the payer's account statement. This is not transmitted to the payee.",
"maxLength": 20
},
"reference": {
"type": "string",
"anyOf": [
{
"$ref": "#/components/schemas/FinnishReference"
},
{
"$ref": "#/components/schemas/CrossBorderReference"
}
]
},
"payerReference": {
"type": "string",
"maxLength": 35,
"description": "Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain."
},
"payerIdentifier": {
"type": "object",
"description": "Payer identification such as Business ID (Y-tunnus).",
"properties": {
"type": {
"type": "string",
"enum": [
"BusinessId",
"Unstructured"
]
},
"id": {
"type": "string",
"maxLength": 35
}
}
},
"ultimatePayee": {
"type": "string",
"description": "Name of the ultimate payee, aka the ultimate creditor. Ultimate payee information is required when the PISP acts as PSP and the payee contains the PSP name and account number.",
"maxLength": 70
},
"originalPayer": {
"type": "string",
"description": "Name of the original payer, aka the ultimate debtor",
"maxLength": 70
},
"dueDate": {
"type": "string",
"format": "date",
"description": "Date when the payment should be executed. For recurring payment, this is the day from which recurrence starts if given."
}
},
"oneOf": [
{
"required": [
"reference",
"amountEUR",
"payee",
"dueDate"
]
},
{
"required": [
"message",
"amountEUR",
"payee",
"dueDate"
]
}
]
},
"RecurringSepaPaymentRequest": {
"type": "object",
"properties": {
"authorizationId": {
"type": "string",
"description": "Authorization bundle ID. Used to bundle several payments to one authorization. Foreign payments cannot be bundled with SEPA payments."
},
"amountEUR": {
"type": "string",
"oneOf": [
{
"$ref": "#/components/schemas/MonetaryEuroAmount"
}
],
"description": "Amount of the payment, value 0,01 - 999 999 999,99 euros"
},
"payee": {
"$ref": "#/components/schemas/SepaPayee"
},
"payer": {
"type": "object",
"description": "Payer element is used to define the debit account. If the debit account is not given in the request,\nthen the PSU must choose the debit account from an account list presented by the ASPSP on the authentication and authorization.\nPSU always has the option to change the debit account during authorization flow.",
"properties": {
"iban": {
"$ref": "#/components/schemas/Iban"
}
},
"required": [
"iban"
]
},
"message": {
"type": "string",
"description": "Message for the payee and payer's account statement",
"maxLength": 140
},
"ownMessage": {
"type": "string",
"description": "Message for the payer's account statement. This is not transmitted to the payee.",
"maxLength": 20
},
"reference": {
"type": "string",
"anyOf": [
{
"$ref": "#/components/schemas/FinnishReference"
},
{
"$ref": "#/components/schemas/CrossBorderReference"
}
]
},
"payerReference": {
"type": "string",
"maxLength": 35,
"description": "Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain."
},
"payerIdentifier": {
"type": "object",
"description": "Payer identification such as Business ID (Y-tunnus).",
"properties": {
"type": {
"type": "string",
"enum": [
"BusinessId",
"Unstructured"
]
},
"id": {
"type": "string",
"maxLength": 35
}
}
},
"ultimatePayee": {
"type": "string",
"description": "Name of the ultimate payee, aka the ultimate creditor. Ultimate payee information is required when the PISP acts as PSP and the payee contains the PSP name and account number.",
"maxLength": 70
},
"originalPayer": {
"type": "string",
"description": "Name of the original payer, aka the ultimate debtor",
"maxLength": 70
},
"dueDate": {
"type": "string",
"format": "date",
"description": "Date when the payment should be executed. For recurring payment, this is the day from which recurrence starts if given."
},
"recurrence": {
"type": "string",
"description": "How often the recurring payment should be executed",
"enum": [
"Weekly",
"Monthly",
"LastBankingDayOfTheMonth"
]
},
"recurrenceEndDate": {
"type": "string",
"format": "date",
"description": "Date when recurring payment should end"
}
},
"oneOf": [
{
"required": [
"reference",
"amountEUR",
"payee",
"dueDate",
"recurrence",
"recurrenceEndDate"
]
},
{
"required": [
"message",
"amountEUR",
"payee",
"dueDate",
"recurrence",
"recurrenceEndDate"
]
},
{
"required": [
"reference",
"amountEUR",
"payee",
"ultimatePayee",
"dueDate",
"recurrence",
"recurrenceEndDate"
]
},
{
"required": [
"message",
"amountEUR",
"payee",
"ultimatePayee",
"dueDate",
"recurrence",
"recurrenceEndDate"
]
}
]
},
"ForeignPaymentRequest": {
"type": "object",
"properties": {
"detailsOfCharges": {
"type": "string",
"description": "Charge bearer. If not given, then the default value of SHA will be used.\nSHA (default/recommended) = both parties pay their own banking fees OUR = payer pays all the banking fees",
"enum": [
"SHA",
"OUR"
]
},
"paymentOrder": {
"type": "string",
"description": "Foreign payment type code.\nNORM (default) = regular foreign payment HIGH = urgent foreign payment",
"enum": [
"NORM",
"HIGH"
]
},
"amount": {
"$ref": "#/components/schemas/MonetaryAmount"
},
"currency": {
"$ref": "#/components/schemas/Currency"
},
"payee": {
"$ref": "#/components/schemas/ForeignPayee"
},
"payer": {
"type": "object",
"properties": {
"iban": {
"$ref": "#/components/schemas/Iban"
}
},
"required": [
"iban"
]
},
"message": {
"type": "string",
"description": "Message for the payee and payer's account statement",
"maxLength": 140
},
"exchangeRateReference": {
"type": "string",
"description": "Reference number related to the foreign currency exchange deal (FX deal) for the payment amount. If given, then the exchange rate according to the FX deal is used. If not given, then the bank will use the daily exchange rates.",
"maxLength": 15
}
},
"required": [
"amount",
"currency",
"payee",
"message"
]
},
"SepaPayee": {
"type": "object",
"description": "Payee details. For non-domestic payments (i.e. IBAN not starting with `FI`) `address` and `country` are required.",
"properties": {
"iban": {
"$ref": "#/components/schemas/Iban"
},
"name": {
"type": "string",
"description": "Name of the payee",
"maximum": 70
},
"address": {
"oneOf": [
{
"$ref": "#/components/schemas/Address"
}
],
"description": "Payee's address, mandatory on cross-border SEPA payments."
},
"country": {
"type": "string",
"oneOf": [
{
"$ref": "#/components/schemas/Country"
}
],
"description": "Mandatory, if address lines given. Country code according to ISO 3166, Alpha-2 code"
}
},
"required": [
"iban",
"name"
]
},
"ForeignPayee": {
"type": "object",
"description": "Payee details for foreign payments.",
"properties": {
"bankAccount": {
"$ref": "#/components/schemas/ForeignBankAccount"
},
"name": {
"type": "string",
"description": "Name of the payee",
"maxLength": 35
},
"financialInstitution": {
"$ref": "#/components/schemas/ForeignFinancialInstitution"
},
"foreignAddress": {
"$ref": "#/components/schemas/ForeignAddress"
},
"leiCode": {
"type": "string",
"description": "Legal Entity Identifier (LEI) of the creditor. ISO 17442 format.",
"pattern": "^[A-Z0-9]{20}$",
"minLength": 20,
"maxLength": 20
}
},
"required": [
"name",
"bankAccount",
"financialInstitution",
"foreignAddress"
]
},
"AuthorizationStatus": {
"type": "string",
"enum": [
"Unauthorized",
"Authorizing",
"Authorized",
"Rejected",
"Completed",
"PartiallyRevoked",
"Revoked"
],
"description": "Unauthorized: Request is pending for authorization by the PSU. Authorizing: PSU is at present authorizing the request. New payments cannot be added to the authorization bundle. Authorized: PSU has authorized the request. Completed: Authorization has been consumed, i.e. payment has been submitted. Note: This does not mean the payments are \"paid\". Partially revoked: Unsubmitted payments have been revoked. Some of the payments may have already been submitted and therefore they cannot be revoked. Revoked: Whole bundle has been revoked before any payment has been submitted."
},
"Authorization": {
"type": "object",
"properties": {
"authorizationId": {
"type": "string",
"description": "Authorization bundle ID"
},
"created": {
"type": "string",
"format": "date-time"
},
"modified": {
"type": "string",
"format": "date-time"
},
"authorized": {
"type": "string",
"format": "date-time"
},
"status": {
"$ref": "#/components/schemas/AuthorizationStatus"
}
},
"required": [
"authorizationId",
"created",
"modified",
"status"
]
},
"AuthorizationPayments": {
"type": "object",
"properties": {
"authorizationId": {
"type": "string",
"description": "Authorization bundle ID"
},
"status": {
"$ref": "#/components/schemas/AuthorizationStatus"
},
"sepaPayments": {
"type": "array",
"description": "An array of authorization bundle immediate SEPA payments`.",
"items": {
"$ref": "#/components/schemas/SepaPaymentDetails"
}
},
"scheduledSepaPayments": {
"type": "array",
"description": "An array of authorization bundle scheduled SEPA payments`.",
"items": {
"$ref": "#/components/schemas/ScheduledSepaPaymentDetails"
}
},
"recurringSepaPayments": {
"type": "array",
"description": "An array of authorization bundle recurring SEPA payments`.",
"items": {
"$ref": "#/components/schemas/RecurringSepaPaymentDetails"
}
},
"foreignPayments": {
"type": "array",
"description": "An array of authorization bundle foreign payments`.",
"items": {
"$ref": "#/components/schemas/ForeignPaymentDetails"
}
}
}
},
"SepaPaymentDetails": {
"type": "object",
"properties": {
"authorizationId": {
"type": "string",
"description": "Authorization bundle ID. Used to bundle several payments to one authorization. Foreign payments cannot be bundled with SEPA payments."
},
"amountEUR": {
"type": "string",
"oneOf": [
{
"$ref": "#/components/schemas/MonetaryEuroAmount"
}
],
"description": "Amount of the payment, value 0,01 - 999 999 999,99 euros"
},
"payee": {
"$ref": "#/components/schemas/SepaPayee"
},
"payer": {
"type": "object",
"description": "Payer element is used to define the debit account. If the debit account is not given in the request,\nthen the PSU must choose the debit account from an account list presented by the ASPSP on the authentication and authorization.\nPSU always has the option to change the debit account during authorization flow.",
"properties": {
"iban": {
"$ref": "#/components/schemas/Iban"
},
"name": {
"type": "string",
"description": "The payer name is the name or names of the account owner(s) represented at account level, \nas displayed by the ASPSP's online channels. \nNote, the name is returned after the payment has been authorized."
}
}
},
"message": {
"type": "string",
"description": "Message for the payee and payer's account statement",
"maxLength": 140
},
"ownMessage": {
"type": "string",
"description": "Message for the payer's account statement. This is not transmitted to the payee.",
"maxLength": 20
},
"reference": {
"type": "string",
"anyOf": [
{
"$ref": "#/components/schemas/FinnishReference"
},
{
"$ref": "#/components/schemas/CrossBorderReference"
}
]
},
"payerReference": {
"type": "string",
"maxLength": 35,
"description": "Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain."
},
"payerIdentifier": {
"type": "object",
"description": "Payer identification such as Business ID (Y-tunnus).",
"properties": {
"type": {
"type": "string",
"enum": [
"BusinessId",
"Unstructured"
]
},
"id": {
"type": "string",
"maxLength": 35
}
}
},
"ultimatePayee": {
"type": "string",
"description": "Name of the ultimate payee, aka the ultimate creditor. Ultimate payee information is required when the PISP acts as PSP and the payee contains the PSP name and account number.",
"maxLength": 70
},
"originalPayer": {
"type": "string",
"description": "Name of the original payer, aka the ultimate debtor",
"maxLength": 70
},
"paymentId": {
"type": "string",
"description": "Unique identifier for the payment."
},
"created": {
"type": "string",
"format": "date-time"
},
"modified": {
"type": "string",
"format": "date-time"
},
"authorized": {
"type": "string",
"format": "date-time"
},
"submitted": {
"type": "string",
"format": "date-time"
},
"archiveId": {
"type": "string",
"description": "Archive ID of the payment submission"
},
"status": {
"type": "string",
"description": "* `Unauthorized`: Payment is pending authorization from PSU.\n* `Authorizing`: PSU has started authorizing payment. \n* `Authorized`: Payment has been authorized by PSU and is pending submission.\n* `Accepted`: Payment has been accepted for processing. It may still be rejected at a later stage if it cannot be processed.\n Resubmitting the payment will return the same result or updated status without actually making a duplicate payment.\n\n* `SubmissionPending`: Payment submission is pending. It has not been confirmed to be debited from the account. Payment may end up in this state due to technical error.\n Resubmission is possible until midnight (Europe/Helsinki timezone).\n\n* `Debited`: Payment has been debited from the payer's account. Resubmitting \n will return the same result without actually making a duplicate payment.\n\n* `Credited`: Payment has been submitted and credited successfully, i.e. debited from the payer's account and credited to the payee's account. This status is used with SEPA Instant Credit Transfers.\n* `Rejected`: Payment has been rejected and it cannot be processed further. The payer's account has not been debited.\n* `Revoked`: Payment has been revoked by TPP before it has been authorized.\n* `Cancelled`: Payment has been cancelled via SCA before it has been submitted.",
"enum": [
"Unauthorized",
"Authorizing",
"Authorized",
"Accepted",
"SubmissionPending",
"Debited",
"Credited",
"Rejected",
"Revoked",
"Cancelled"
]
},
"executionType": {
"type": "string",
"description": "Indicates how the SEPA payment is being processed currently. \n* `SCT_INST`: The payment is being processed as a SEPA Instant Credit Transfer (SCT Inst).\n* `SCT`: The payment is being processed as a standard SEPA Credit Transfer (SCT).\nThis value reflects the current processing mode, not necessarily the initial one. For example payment may be initially started processing as SCT_INST, but fallback to SCT if instant processing is not available. When executionType is SCT_INST expected successful status of the payment is Credited, where as with SCT the successful status is Debited.",
"enum": [
"SCT_INST",
"SCT"
]
},
"rejectionReasonCode": {
"type": "string",
"description": "Code indicating the reason for the payment rejection if the payment status is Rejected. Typical codes are:\n* `PaymentFail`: General payment failure, more details in message\n* `InsufficientFunds`: Insufficient funds on the account"
},
"rejectionReasonMessage": {
"type": "string",
"description": "More detailed message indicating the reason for the payment rejection if the payment status is Rejected."
}
}
},
"ScheduledSepaPaymentDetails": {
"type": "object",
"properties": {
"authorizationId": {
"type": "string",
"description": "Authorization bundle ID. Used to bundle several payments to one authorization. Foreign payments cannot be bundled with SEPA payments."
},
"amountEUR": {
"type": "string",
"oneOf": [
{
"$ref": "#/components/schemas/MonetaryEuroAmount"
}
],
"description": "Amount of the payment, value 0,01 - 999 999 999,99 euros"
},
"payee": {
"$ref": "#/components/schemas/SepaPayee"
},
"payer": {
"type": "object",
"description": "Payer element is used to define the debit account. If the debit account is not given in the request,\nthen the PSU must choose the debit account from an account list presented by the ASPSP on the authentication and authorization.\nPSU always has the option to change the debit account during authorization flow.",
"properties": {
"iban": {
"$ref": "#/components/schemas/Iban"
},
"name": {
"type": "string",
"description": "The payer name is the name or names of the account owner(s) represented at account level, \nas displayed by the ASPSP's online channels. \nNote, the name is returned after the payment has been authorized."
}
}
},
"message": {
"type": "string",
"description": "Message for the payee and payer's account statement",
"maxLength": 140
},
"ownMessage": {
"type": "string",
"description": "Message for the payer's account statement. This is not transmitted to the payee.",
"maxLength": 20
},
"reference": {
"type": "string",
"anyOf": [
{
"$ref": "#/components/schemas/FinnishReference"
},
{
"$ref": "#/components/schemas/CrossBorderReference"
}
]
},
"payerReference": {
"type": "string",
"maxLength": 35,
"description": "Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain."
},
"payerIdentifier": {
"type": "object",
"description": "Payer identification such as Business ID (Y-tunnus).",
"properties": {
"type": {
"type": "string",
"enum": [
"BusinessId",
"Unstructured"
]
},
"id": {
"type": "string",
"maxLength": 35
}
}
},
"ultimatePayee": {
"type": "string",
"description": "Name of the ultimate payee, aka the ultimate creditor. Ultimate payee information is required when the PISP acts as PSP and the payee contains the PSP name and account number.",
"maxLength": 70
},
"originalPayer": {
"type": "string",
"description": "Name of the original payer, aka the ultimate debtor",
"maxLength": 70
},
"dueDate": {
"type": "string",
"format": "date",
"description": "Date when the payment should be executed. For recurring payment, this is the day from which recurrence starts if given."
},
"paymentId": {
"type": "string",
"description": "Unique identifier for the payment."
},
"created": {
"type": "string",
"format": "date-time"
},
"modified": {
"type": "string",
"format": "date-time"
},
"authorized": {
"type": "string",
"format": "date-time"
},
"submitted": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string",
"description": "* `Unauthorized`: Payment is pending authorization from PSU.\n* `Authorizing`: PSU has started authorizing payment. \n* `Authorized`: Payment has been authorized by PSU and is pending submission.\n* `Accepted`: Payment has been accepted for processing. It may still be rejected at a later stage if it cannot be processed.\n Resubmitting the payment will return the same result or updated status without actually making a duplicate payment.\n\n* `SubmissionPending`: Payment submission is pending. It has not been confirmed to be accepted for processing. Payment may end up in this state due to technical error.\n Resubmission is possible until midnight (Europe/Helsinki timezone).\n\n* `Debited`: Payment has been debited from the payer's account. Resubmitting \n will return the same result without actually making a duplicate payment.\n\n* `Credited`: Payment has been submitted and credited successfully, i.e. debited from the payer's account and credited to the payee's account. This status is used with SEPA Instant Credit Transfers.\n* `AwaitingDueDate`: Payment is in processing waiting for the due date.\n* `AwaitingFunds`: Payment is being executed and awaiting funds due to insufficient funds on the account. \n* `Rejected`: Payment has been rejected and it cannot be processed further. The payer's account has not been debited.\n* `Revoked`: Payment has been revoked by TPP before it has been authorized.\n* `Cancelled`: Payment has been cancelled via SCA before it has been submitted.",
"enum": [
"Unauthorized",
"Authorizing",
"Authorized",
"Accepted",
"SubmissionPending",
"AwaitingDueDate",
"AwaitingFunds",
"Debited",
"Credited",
"Cancelled",
"Rejected",
"Revoked"
]
},
"executionType": {
"type": "string",
"description": "Indicates how the SEPA payment is being processed currently. \n* `SCT_INST`: The payment is being processed as a SEPA Instant Credit Transfer (SCT Inst).\n* `SCT`: The payment is being processed as a standard SEPA Credit Transfer (SCT).\nThis value reflects the current processing mode, not necessarily the initial one. For example payment may be initially started processing as SCT_INST, but fallback to SCT if instant processing is not available. When executionType is SCT_INST expected successful status of the payment is Credited, where as with SCT the successful status is Debited.",
"enum": [
"SCT_INST",
"SCT"
]
},
"rejectionReasonCode": {
"type": "string",
"description": "Code indicating the reason for the payment rejection if the payment status is Rejected. Typical codes are:\n* `PaymentFail`: General payment failure, more details in message\n* `InsufficientFunds`: Insufficient funds on the account"
},
"rejectionReasonMessage": {
"type": "string",
"description": "More detailed message indicating the reason for the payment rejection if the payment status is Rejected."
},
"archiveId": {
"description": "Archive ID (\"Arkistointitunnus\") of the payment which is formed after payment is confirmed.",
"pattern": "^\\d{9}[A-Z\\d]{7}\\d{4}$",
"type": "string"
}
}
},
"RecurringSepaPaymentDetails": {
"type": "object",
"properties": {
"authorizationId": {
"type": "string",
"description": "Authorization bundle ID. Used to bundle several payments to one authorization. Foreign payments cannot be bundled with SEPA payments."
},
"amountEUR": {
"type": "string",
"oneOf": [
{
"$ref": "#/components/schemas/MonetaryEuroAmount"
}
],
"description": "Amount of the payment, value 0,01 - 999 999 999,99 euros"
},
"payee": {
"$ref": "#/components/schemas/SepaPayee"
},
"payer": {
"type": "object",
"description": "Payer element is used to define the debit account. If the debit account is not given in the request,\nthen the PSU must choose the debit account from an account list presented by the ASPSP on the authentication and authorization.\nPSU always has the option to change the debit account during authorization flow.",
"properties": {
"iban": {
"$ref": "#/components/schemas/Iban"
},
"name": {
"type": "string",
"description": "The payer name is the name or names of the account owner(s) represented at account level, \nas displayed by the ASPSP's online channels. \nNote, the name is returned after the payment has been authorized."
}
}
},
"message": {
"type": "string",
"description": "Message for the payee and payer's account statement",
"maxLength": 140
},
"ownMessage": {
"type": "string",
"description": "Message for the payer's account statement. This is not transmitted to the payee.",
"maxLength": 20
},
"reference": {
"type": "string",
"anyOf": [
{
"$ref": "#/components/schemas/FinnishReference"
},
{
"$ref": "#/components/schemas/CrossBorderReference"
}
]
},
"payerReference": {
"type": "string",
"maxLength": 35,
"description": "Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain."
},
"payerIdentifier": {
"type": "object",
"description": "Payer identification such as Business ID (Y-tunnus).",
"properties": {
"type": {
"type": "string",
"enum": [
"BusinessId",
"Unstructured"
]
},
"id": {
"type": "string",
"maxLength": 35
}
}
},
"ultimatePayee": {
"type": "string",
"description": "Name of the ultimate payee, aka the ultimate creditor. Ultimate payee information is required when the PISP acts as PSP and the payee contains the PSP name and account number.",
"maxLength": 70
},
"originalPayer": {
"type": "string",
"description": "Name of the original payer, aka the ultimate debtor",
"maxLength": 70
},
"dueDate": {
"type": "string",
"format": "date",
"description": "Date when the payment should be executed. For recurring payment, this is the day from which recurrence starts if given."
},
"recurrence": {
"type": "string",
"description": "How often the recurring payment should be executed",
"enum": [
"Weekly",
"Monthly",
"LastBankingDayOfTheMonth"
]
},
"recurrenceEndDate": {
"type": "string",
"format": "date",
"description": "Date when recurring payment should end"
},
"paymentId": {
"type": "string",
"description": "Unique identifier for the payment."
},
"archiveId": {
"type": "string",
"description": "Archive ID of the payment"
},
"created": {
"type": "string",
"format": "date-time"
},
"modified": {
"type": "string",
"format": "date-time"
},
"authorized": {
"type": "string",
"format": "date-time"
},
"submitted": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string",
"description": "* `Unauthorized`: Payment is pending authorization from PSU.\n* `Authorizing`: PSU has started authorizing payment. \n* `Authorized`: Payment has been authorized by PSU and is pending submission.\n* `Accepted`: Payment has been accepted for processing. It may still be rejected at a later stage if it cannot be processed.\n Resubmitting the payment will return the same result or updated status without actually making a duplicate payment.\n\n* `SubmissionPending`: Payment submission is pending. It has not been confirmed to be accepted for processing. Payment may end up in this state due to technical error.\n Resubmission is possible until midnight (Europe/Helsinki timezone).\n\n* `Debited`: Payment has been debited from the payer's account. Resubmitting \n will return the same result without actually making a duplicate payment.\n\n* `Credited`: Payment has been submitted and credited successfully, i.e. debited from the payer's account and credited to the payee's account. This status is used with SEPA Instant Credit Transfers.\n* `AwaitingDueDate`: Payment is in processing waiting for the due date.\n* `AwaitingFunds`: Payment is being executed and awaiting funds due to insufficient funds on the account. \n* `Rejected`: Payment has been rejected and it cannot be processed further. The payer's account has not been debited.\n* `Revoked`: Payment has been revoked by TPP before it has been authorized.\n* `Cancelled`: Payment has been cancelled via SCA before it has been submitted.",
"enum": [
"Unauthorized",
"Authorizing",
"Authorized",
"Accepted",
"SubmissionPending",
"AwaitingDueDate",
"AwaitingFunds",
"Debited",
"Credited",
"Cancelled",
"Rejected",
"Revoked"
]
},
"executionType": {
"type": "string",
"description": "Indicates how the SEPA payment is being processed currently. \n* `SCT_INST`: The payment is being processed as a SEPA Instant Credit Transfer (SCT Inst).\n* `SCT`: The payment is being processed as a standard SEPA Credit Transfer (SCT).\nThis value reflects the current processing mode, not necessarily the initial one. For example payment may be initially started processing as SCT_INST, but fallback to SCT if instant processing is not available. When executionType is SCT_INST expected successful status of the payment is Credited, where as with SCT the successful status is Debited.",
"enum": [
"SCT_INST",
"SCT"
]
},
"rejectionReasonCode": {
"type": "string",
"description": "Code indicating the reason for the payment rejection if the payment status is Rejected. Typical codes are:\n* `PaymentFail`: General payment failure, more details in message\n* `InsufficientFunds`: Insufficient funds on the account"
},
"rejectionReasonMessage": {
"type": "string",
"description": "More detailed message indicating the reason for the payment rejection if the payment status is Rejected."
}
}
},
"ForeignPaymentDetails": {
"type": "object",
"properties": {
"detailsOfCharges": {
"type": "string",
"description": "Charge bearer. If not given, then the default value of SHA will be used.\nSHA (default/recommended) = both parties pay their own banking fees OUR = payer pays all the banking fees",
"enum": [
"SHA",
"OUR"
]
},
"paymentOrder": {
"type": "string",
"description": "Foreign payment type code.\nNORM (default) = regular foreign payment HIGH = urgent foreign payment",
"enum": [
"NORM",
"HIGH"
]
},
"amount": {
"$ref": "#/components/schemas/MonetaryAmount"
},
"currency": {
"$ref": "#/components/schemas/Currency"
},
"payee": {
"$ref": "#/components/schemas/ForeignPayee"
},
"payer": {
"type": "object",
"description": "Payer element is used to define the debit account. If the debit account is not given in the request,\nthen the PSU must choose the debit account from an account list presented by the ASPSP on the authentication and authorization.\nPSU always has the option to change the debit account during authorization flow.",
"properties": {
"iban": {
"$ref": "#/components/schemas/Iban"
},
"name": {
"type": "string",
"description": "The payer name is the name or names of the account owner(s) represented at account level, \nas displayed by the ASPSP's online channels. \nNote, the name is returned after the payment has been authorized."
}
}
},
"message": {
"type": "string",
"description": "Message for the payee and payer's account statement",
"maxLength": 140
},
"exchangeRateReference": {
"type": "string",
"description": "Reference number related to the foreign currency exchange deal (FX deal) for the payment amount. If given, then the exchange rate according to the FX deal is used. If not given, then the bank will use the daily exchange rates.",
"maxLength": 15
},
"authorizationId": {
"type": "string"
},
"paymentId": {
"type": "string",
"description": "Unique identifier for the payment."
},
"created": {
"type": "string",
"format": "date-time"
},
"modified": {
"type": "string",
"format": "date-time"
},
"authorized": {
"type": "string",
"format": "date-time"
},
"submitted": {
"type": "string",
"format": "date-time"
},
"archiveId": {
"type": "string",
"description": "Archive ID of the payment submission"
},
"status": {
"type": "string",
"description": "* `Unauthorized`: Payment is pending authorization from PSU.\n* `Authorizing`: PSU has started authorizing payment. \n* `Authorized`: Payment has been authorized by PSU and is pending submission.\n* `Accepted`: Payment has been accepted for processing. It may still be rejected at a later stage if it cannot be processed.\n Resubmitting the payment will return the same result or updated status without actually making a duplicate payment.\n\n* `SubmissionPending`: Payment is pending. It has not been confirmed to be debited from the account. Payment may end up in this state due to technical error.\n Resubmission is possible until midnight (Europe/Helsinki timezone).\n\n* `Debited`: Payment has been debited from the payer's account. Resubmitting \n will return the same result without actually making a duplicate payment.\n\n* `Rejected`: Payment has been rejected and it cannot be processed further. The payer's account has not been debited.\n* `Revoked`: Payment has been revoked by TPP before it has been authorized.\n* `Cancelled`: Payment has been cancelled via SCA before it has been submitted.",
"enum": [
"Unauthorized",
"Authorizing",
"Authorized",
"Accepted",
"SubmissionPending",
"Debited",
"Rejected",
"Revoked",
"Cancelled"
]
},
"executionType": {
"type": "string",
"description": "Indicates how the foreign payment is being processed currently. \n* `FOREIGN`: The payment is being processed as a foreign payment.",
"enum": [
"FOREIGN"
]
},
"rejectionReasonCode": {
"type": "string",
"description": "Code indicating the reason for the payment rejection if the payment status is Rejected. Typical codes are:\n* `PaymentFail`: General payment failure, more details in message\n* `InsufficientFunds`: Insufficient funds on the account"
},
"rejectionReasonMessage": {
"type": "string",
"description": "More detailed message indicating the reason for the payment rejection if the payment status is Rejected."
}
}
},
"RecurringPaymentRecurrenceDetails": {
"type": "object",
"properties": {
"modified": {
"type": "string",
"format": "date-time"
},
"archiveId": {
"type": "string",
"description": "Archive ID of the payment"
},
"dueDate": {
"type": "string",
"format": "date"
},
"status": {
"type": "string",
"description": "* `Debited`: Payment has been debited from the payer's account.\n* `Credited`: Payment has been submitted and credited successfully,\n i.e. debited from the payer's account and credited to the payee's\n account. This status is used with SEPA Instant Credit Transfers.\n\n* `AwaitingDueDate`: Payment is in processing waiting for due date.\n* `AwaitingFunds`: Payment is being executed and awaiting funds due to insufficient funds on the account. \n* `Rejected`: Payment has been rejected and it can't be processed further. Payer's account has not been debited.\n* `Cancelled`: Payment has been cancelled by PSU. Payer's account has not been debited.\n* `Processing`: Payment is being processed.",
"enum": [
"AwaitingDueDate",
"AwaitingFunds",
"Debited",
"Credited",
"Cancelled",
"Rejected",
"Processing"
]
},
"executionType": {
"type": "string",
"description": "Indicates how the SEPA payment is being processed currently. \n* `SCT_INST`: The payment is being processed as a SEPA Instant Credit Transfer (SCT Inst).\n* `SCT`: The payment is being processed as a standard SEPA Credit Transfer (SCT).\nThis value reflects the current processing mode, not necessarily the initial one. For example payment may be initially started processing as SCT_INST, but fallback to SCT if instant processing is not available. When executionType is SCT_INST expected successful status of the payment is Credited, where as with SCT the successful status is Debited.",
"enum": [
"SCT_INST",
"SCT"
]
},
"rejectionReasonCode": {
"type": "string",
"description": "Code indicating the reason for the payment rejection if the payment status is Rejected. Typical codes are:\n* `PaymentFail`: General payment failure, more details in message\n* `InsufficientFunds`: Insufficient funds on the account"
},
"rejectionReasonMessage": {
"type": "string",
"description": "More detailed message indicating the reason for the payment rejection if the payment status is Rejected."
}
}
},
"SubmitSepaPaymentRequest": {
"type": "object",
"description": "API guarantees that submission is processed and debited only once. Allows retry also in case of backend failure due to insufficient funds, for example."
},
"SubmitForeignPaymentRequest": {
"type": "object",
"description": "API guarantees that submission is processed and debited only once. Allows retry also in case of backend failure due to insufficient funds, for example."
},
"ConfirmScheduledSepaPaymentRequest": {
"type": "object",
"description": "Confirm scheduled SEPA payment"
},
"ConfirmRecurringSepaPaymentRequest": {
"type": "object",
"description": "Confirm recurring SEPA payment"
},
"ForeignFinancialInstitution": {
"type": "object",
"description": "Foreign bank account that can be in IBAN or BBAN format.",
"properties": {
"bic": {
"type": "string",
"description": "Payee's bank BIC code (highly recommended)"
},
"clearingSystemId": {
"type": "string",
"description": "Clearing system ID (recommended if BIC not present). Not to be used with BIC."
},
"name": {
"type": "string",
"description": "Name of the financial institution",
"maxLength": 140
},
"foreignBankAddress": {
"$ref": "#/components/schemas/ForeignBankAddress"
}
}
},
"ForeignBankAccount": {
"type": "object",
"description": "Foreign bank account that can be in IBAN or BBAN format.",
"properties": {
"id": {
"type": "string",
"maxLength": 34,
"description": "Account number without formatting spaces. For example, IBAN: FI9912345678901234 or BBAN: 12345678901234 IBAN format: [A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30} BBAN format: only numbers, max 35 char"
},
"schemeName": {
"type": "string",
"description": "IBAN or BBAN according to the account format",
"enum": [
"IBAN",
"BBAN"
]
},
"issuer": {
"type": "string",
"description": "BICFI, BIC code of the bank"
}
},
"required": [
"id",
"schemeName"
]
},
"ForeignBankAddress": {
"type": "object",
"description": "Address of the foreign bank. Address is mandatory if BICFI or Clearing System ID is not present.",
"properties": {
"address": {
"type": "string",
"maxLength": 70
},
"city": {
"type": "string",
"maxLength": 35
},
"country": {
"type": "string",
"description": "Country code according to ISO 3166, Alpha-2 code",
"maxLength": 2
}
}
},
"ForeignAddress": {
"type": "object",
"description": "Foreign address",
"properties": {
"addressLine1": {
"type": "string",
"minLength": 1,
"maxLength": 35
},
"addressLine2": {
"type": "string",
"minLength": 1,
"maxLength": 35
},
"country": {
"type": "string",
"description": "Country code according to ISO 3166, Alpha-2 code",
"maxLength": 2
}
},
"required": [
"addressLine1",
"addressLine2"
]
},
"Iban": {
"type": "string",
"description": "For SEPA payments, the payee's account number must always be in IBAN format without formatting spaces. For example, FI9912345678901234 IBAN pattern: [A-Z]{2,2}[0-9]{2,2}[A-Z0-9]{1,30}",
"example": "FI4950009420028730"
},
"FinnishReference": {
"type": "string",
"minLength": 4,
"maxLength": 24,
"description": "Either Finnish reference number or RF Creditor Reference. Finnish (domestic) reference: 4‒20 numbers where the last number is a check digit. RF creditor reference: max 24 char including Finnish reference [See specifications in Finance Finland's technical documents.](http://www.finanssiala.fi/en/payment-services/Pages/Technical-documentation.aspx)"
},
"CrossBorderReference": {
"type": "string",
"description": "RF creditor reference. Local format restrictions may apply, e.g. when paying to FI account FinnishReference rules apply. [See European Payments Council's guidelines.](https://www.europeanpaymentscouncil.eu/sites/default/files/KB/files/EPC142-08-EPC-Guidance-on-Creditor-Reference-ISO-Std.pdf)",
"minLength": 1,
"maxLength": 25
},
"Currency": {
"type": "string",
"description": "ISO 4127 currency code",
"pattern": "^[A-Z]{3}$"
},
"Country": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code",
"pattern": "^[A-Z]{2,2}$",
"maxLength": 2
},
"MonetaryAmount": {
"type": "string",
"format": "number",
"description": "Positive (greater than zero) monetary amount.",
"pattern": "^\\d{1,13}(?:\\.\\d\\d)?$"
},
"MonetaryEuroAmount": {
"type": "string",
"format": "number",
"description": "Positive (greater than zero) monetary amount. Currency is EUR.",
"pattern": "^\\d{1,13}(?:\\.\\d\\d)?$"
},
"Address": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 35
},
"description": "Information that locates and identifies a specific address, as defined by postal services, presented in free format text. Max 4 address lines, max length 35 per address line",
"minItems": 1,
"maxItems": 4
},
"ApiError": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"SECURITY",
"VALIDATION",
"TECHNICAL",
"BUSINESS"
]
},
"message": {
"type": "string"
},
"violations": {
"description": "Details of VALIDATION errors.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Violation"
}
},
"id": {
"type": "string",
"description": "ID of the error. Required on support requests."
}
},
"required": [
"type",
"message",
"id"
]
},
"Violation": {
"oneOf": [
{
"$ref": "#/components/schemas/Required"
},
{
"$ref": "#/components/schemas/UnrecognizedProperty"
},
{
"$ref": "#/components/schemas/Size"
},
{
"$ref": "#/components/schemas/ValidFinnishReference"
},
{
"$ref": "#/components/schemas/ValidCountryCode"
},
{
"$ref": "#/components/schemas/ValidIban"
},
{
"$ref": "#/components/schemas/FinnishIban"
},
{
"$ref": "#/components/schemas/SepaIban"
},
{
"$ref": "#/components/schemas/SepaAddress"
},
{
"$ref": "#/components/schemas/Max"
},
{
"$ref": "#/components/schemas/Min"
},
{
"$ref": "#/components/schemas/EuroCents"
},
{
"$ref": "#/components/schemas/MessageOrReference"
},
{
"$ref": "#/components/schemas/CreditorBicOrAddress"
},
{
"$ref": "#/components/schemas/ValidBic"
},
{
"$ref": "#/components/schemas/EuEtaValid"
},
{
"$ref": "#/components/schemas/Date"
},
{
"$ref": "#/components/schemas/DuplicatePayment"
},
{
"$ref": "#/components/schemas/InsufficientFunds"
},
{
"$ref": "#/components/schemas/PaymentFail"
},
{
"$ref": "#/components/schemas/IllegalState"
},
{
"$ref": "#/components/schemas/InvalidValue"
},
{
"$ref": "#/components/schemas/TypeMismatch"
},
{
"$ref": "#/components/schemas/ValidPaymentOrder"
},
{
"$ref": "#/components/schemas/PaymentOrder"
},
{
"$ref": "#/components/schemas/ValidDetailOfCharges"
},
{
"$ref": "#/components/schemas/ValidForeignPaymentRecurrence"
},
{
"$ref": "#/components/schemas/ValidPayerAccount"
},
{
"$ref": "#/components/schemas/Payee"
},
{
"$ref": "#/components/schemas/InvalidPaymentType"
}
]
},
"Required": {
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"description": "Error type.",
"enum": [
"Required"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"UnrecognizedProperty": {
"description": "Given property is not recognized and should be omitted from the request.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"UnrecognizedProperty"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"Size": {
"description": "Given property must be of size between `min` and `max`.",
"type": "object",
"required": [
"type",
"message",
"min",
"max"
],
"properties": {
"type": {
"type": "string",
"enum": [
"Size"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
},
"min": {
"type": "integer",
"format": "int32"
},
"max": {
"type": "integer",
"format": "int32"
}
}
},
"ValidFinnishReference": {
"description": "Given property must be either a valid RF Creditor Reference or Finnish domestic reference number.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"FinnishReference"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"ValidCountryCode": {
"description": "Given property must be a valid ISO 3166-1 alpha-2 country code",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"CountryCode"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"ValidIban": {
"description": "Given property must be a valid IBAN.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"Iban"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"FinnishIban": {
"description": "Given property must be a valid Finnish IBAN.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"FinnishIban"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"SepaIban": {
"description": "Given value must be a valid SEPA IBAN.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"SepaIban"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"SepaAddress": {
"description": "Given if address is set, may not contain blank or empty strings.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"SepaAddress"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"Max": {
"description": "Given property must be a) less-than `value` if `inclusive` is false or b) less-than-or-equal `value` if `inclusive` is true.",
"type": "object",
"required": [
"type",
"message",
"value",
"inclusive"
],
"properties": {
"type": {
"type": "string",
"enum": [
"Max"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
},
"value": {
"type": "string",
"format": "number"
},
"inclusive": {
"type": "boolean"
}
}
},
"Min": {
"description": "Given property must be a) greater-than `value` if `inclusive` is false or b) greater-than-or-equal `value` if `inclusive` is true.",
"type": "object",
"required": [
"type",
"message",
"value",
"inclusive"
],
"properties": {
"type": {
"type": "string",
"enum": [
"Min"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
},
"value": {
"type": "string",
"format": "number"
},
"inclusive": {
"type": "boolean"
}
}
},
"EuroCents": {
"description": "Given property must have none or exactly two decimals (i.e. cents).",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"EuroCents"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"MessageOrReference": {
"description": "Must specify either message or reference.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"MessageOrReference"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"CreditorBicOrAddress": {
"description": "Must specify either BIC, clearing code or creditor address.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"CreditorBicOrAddress"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"ValidBic": {
"description": "Given BIC must be in valid format.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"ValidBic"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"EuEtaValid": {
"description": "EU / ETA area payments must have valid BIC and IBAN.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"EuEtaValid"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"Date": {
"description": "Date restrictions",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"Date"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"DuplicatePayment": {
"description": "A payment with the same idempotency key, client and user ID is already created. If the request body is equal to the original request and the status of that payment has not advanced beyond the initial state, the original payment is returned instead of this error.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"DuplicatePayment"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"InsufficientFunds": {
"description": "Payer account has insufficient funds for payment.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"InsufficientFunds"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"PaymentFail": {
"description": "Payment submission has failed because of one business reason or another, e.g. withdrawal limits, non-existing or non-accessible payee account, account permissions. See message for details.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"PaymentFail"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"IllegalState": {
"description": "Action (i.e. state transition) is not allowed.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"IllegalState"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"InvalidValue": {
"description": "Property value is not valid.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"InvalidValue"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"TypeMismatch": {
"description": "Property cannot be parsed into valid type.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"TypeMismatch"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"PaymentOrder": {
"description": "Payment order value is invalid.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"PaymentOrder"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"ValidPaymentOrder": {
"description": "Payment order value is not valid for this type of payment.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"ValidPaymentOrder"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"ValidDetailOfCharges": {
"description": "SEPA payment details of charges must be SHA.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"ValidDetailOfCharges"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"ValidForeignPaymentRecurrence": {
"description": "Foreign payment cannot have recurrence. Only single payments are supported.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"ValidForeignPaymentRecurrence"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"ValidPayerAccount": {
"description": "Payer account must be a valid OP account and cannot be same as payee account",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"ValidPayerAccount"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"Payee": {
"description": "Check that the payee’s name and address are correct.",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"Payee"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
},
"InvalidPaymentType": {
"description": "Payment type does not match used endpoint, i.e. Euro-denominated SEPA payments cannot be sent as a foreign payment",
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"InvalidPaymentType"
]
},
"path": {
"type": "string",
"description": "Path of property in error."
},
"message": {
"type": "string"
}
}
}
}
}
}