API Market documentation

PIS API specific documentation Finland

Changes from the previous version

Version 6.1

New version

Overview

The /payments/domestic-credit-transfers can be used to initiate a SEPA payment. The response contains the payment details which include, for example, payment amount and creditor details among other things.

Please note that it is not possible to confirm payments to non-Finnish accounts using code calculator or Nordea ID app offline mode. Please use the Nordea ID app in online mode to confirm such payments.

It is not allowed to use both Creditor reference and Creditor message when initiating a Sepa credit transfer. If both are used, the payment is rejected.

API Endpoints

The PIS API contains the following endpoints:

Endpoint	Supported HTTP Methods
`/payments/sepa-credit-transfers`	POST

Here is an example of the JSON payload format which can be posted to this endpoint, “_type” is an internal defined representation of the account. Only supports IBAN in case of SEPA credit transfers.

{
    "instructed_amount": {
        "amount": 5,
        "currency": "EUR"
    },
    "creditor": {
        "account": {
            "_type": "IBAN",
            "currency": "EUR",
            "value": "FI1450000120236228"
        },
        "message": "crd msg",
        "name": "Beneficiary name"
    },
    "debtor": {
        "account": {
            "_type": "IBAN",
            "currency": "EUR",
            "value": "FI7473834510057469"
        },
        "message": "Message for debtor"
    },
    "external_id": "some id",
    "urgency": "standard"
}
'

PIS API Scenarios

The scenarios are implemented on PIS API to allow for easier testing of the applications. Developers can request a specific scenario (or list of scenarios) for certain API calls, for example, when confirming a transfer of funds the developer can request that the transaction processing to fail due to missing funds and the corresponding payment status will be represented in the payment details.

There are three scenarios available in PIS API related to payment signing and execution.

PaymentSigningExpires
PaymentMissingFunds
PaymentOnHold

PaymentSigningExpires scenario means that the user never signs the payment by MTA (Nordea code app). PaymentMissingFunds in this scenario payment is signed, but there are no funds available. PaymentOnHold in this scenario payment is signed, but the payment is put on hold by Nordea for some reason (for example, fraud).

There are the following scenarios available for adding a mock UI signing flow to the payment confirmation. Adding any of the UI scenarios to the confirmation flow, then calling /confirm is no longer adequate to sign the payment, The mock UI flow has to be followed.

AuthenticationWithUI
SigningWithUI

AuthenticationWithUI mimics the 2SCA flow and includes authentication before signing. SigningWithUI shows the mock signing screen only and mimics the 1SCA flow. The signing screen also has built in functionality to check a few scenarios whilst mock signing the payment.

There is additionally a scenario available for mocking the date being rolled.

ExecutionDateRolling

ExecutionDateRolling rolls the planned_execution_date compared to the requested_execution_date to mimic that the payment cannot be processed the requested date.

Any scenario is specified either as part of request header or as a query parameter.

sandbox only

Note that the scenarios are available only in the sandbox APIs. They will never be available in the production APIs.
Use `X-Response-Scenarios` for header parameter or query parameter to request scenarios to be applied.

Further details

For further details on payment type field combinations and status codes, recurring payments etc., please refer to the domestic API documentation as well. Also, have a look at the Help Center contents.

PIS API examples SEPA

SEPA: initiate a new payment

In this example, we initiate a new payment.

This endpoint URL has the following form:

https://api.nordeaopenbanking.com/personal/v5/payments/sepa-credit-transfers

Here is an example request.

$ curl 'https://api.nordeaopenbanking.com/personal/v5/payments/sepa-credit-transfers' -i -X POST \
    -H 'X-Nordea-Originating-Host: <host>' \
    -H 'X-Nordea-Originating-Date: <now>' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -H 'digest: <generated_digest>' \
    -H 'signature: keyId=\"<your_clientapp_keyid>\",algorithm=\"rsa-sha256\",headers=\"(request-target) x-nordea-originating-host x-nordea-originating-date\",signature=\"<generated_signature>"' \ 
    -H 'X-IBM-Client-Id: <your_client_id>' \
    -H 'X-IBM-Client-Secret: <your_client_secret>' \
    -H 'Content-Type: application/json; charset=UTF-8' \
    -d '{
    "instructed_amount": {
        "amount": 5,
        "currency": "EUR"
    },
    "creditor": {
        "account": {
            "_type": "IBAN",
            "currency": "EUR",
            "value": "FI1450000120236228"
        },
        "message": "crd msg",
        "name": "Beneficiary name"
    },
    "debtor": {
        "account": {
            "_type": "IBAN",
            "currency": "EUR",
            "value": "FI7473834510057469"
        },
        "message": "Message for debtor"
    },
    "external_id": "some id",
    "urgency": "standard"
}
'

And the response looks like this:

    "group_header": {
        "message_identification": "1e52b308845e976b705e5b80de4b2682",
        "creation_date_time": "2025-12-02T06:59:10.582713414Z",
        "http_code": 201
    },
    "response": {
        "_id": "a0e456ab-e324-4112-9adb-617751f7da26",
        "external_id": "some id",
        "entry_date_time": "2025-12-02T06:59:10.581675594Z",
        "debtor": {
            "account": {
                "currency": "EUR",
                "value": "FI7473834510057469",
                "_type": "IBAN"
            }
        },
        "creditor": {
            "account": {
                "currency": "EUR",
                "value": "FI1450000120236228",
                "_type": "IBAN"
            },
            "name": "Beneficiary name",
            "message": "crd msg"
        },
        "instructed_amount": {
            "amount": "5",
            "currency": "EUR"
        },
        "payment_status": "PendingConfirmation",
        "urgency": "standard",
        "requested_execution_date": "2025-12-02",
        "planned_execution_date": "2025-12-02",
        "tpp_messages": [],
        "_links": [
            {
                "rel": "self",
                "href": "/v5/payments/a0e456ab-e324-4112-9adb-617751f7da26"
            }
        ]
    }
}
'

Note that the ‘payment_status’ is ‘PendingConfirmation’, it means the payment confirming(signing) process has to be started by you the TPP.

Domestic transfer Cross Border transfer