API Market documentation

PIS API specific documentation Salary and Pension Payments

Changes from the previous version

This is the change log of the PIS API (Salary and Pension), allowing PSD2-regulated TPPs to initiate salary and pension transfers on behalf of the PSU, in this case the Nordea Business customer. The top most item is the latest change and the API changes described in it are relative to the version directly below. The current version of the API is 4.7.

Note: In order to keep integrity with domestic and SEPA payments, salary and pension starting service version is 4.0

Version 4.7

New status reason has been added: “RequiresSinglePaymentSigning” in the payments model for Sweden.

Version 4.6

New ENUM value has been added to the parameter “payment_status_reason” in the payments model.

Version 4.5

Support for the Confirmation of availability of funds has been added. Please refer to the Confirmation of availability of funds section.

Version 4.4

Swagger definition updated for account types.

Version 4.3

The parameter “auto_start_token” has been removed from the payment details.

Version 4.2

Added support for second channel confirmation for Norway. Salary payments for Norway that was only in Sandbox in version 4.1, is now in production.

Version 4.1

Added Salary payments for Norway (Sandbox).

Version 4.0

Created

POST /v4/payments/domestic/salarypension

Edited

GET ‘/v4/payments/domestic’
GET ‘/v4/payments/domestic/{paymentId}’

Note: We have implemented new endpoint for Salary and Pension payments due to separation of data model.

Overview

The PIS API for salary and pension can be used to initiate and confirm account transfers for salary and pension purposes.
This API supports POST HTTP method only. Check status of payments, deletions etc. can be done via the /payments/domestic endpoint, but salary and payment transfers have to be initiated via this service, else they will be treated as normal payments.

This API has similar request model as domestic, but with limited set of properties dedicated to Salary and Pension. Service comes with a set of deviations as these payments are for internal, account to account transfers only:

no recurrency support
no urgency property (get executed instantly at provided ‘requested execution date’)

Note: For Swedish Salary and Pension PlusGiro and BankGiro account types as beneficiary are not accepted. Note: Salary and Pension payments are can be initiated only from domestic currency (SEK for Sweden, NOK for Norway).

sandbox only

In Sandbox: Note that sandbox accepts all creditor account numbers, i.e. payments might be initiated to not existing, but valid account numbers.

Second Channel Confirmation

Based on certain parameters, a payment may become eligible for a second channel confirmation. In such cases, when a customer confirms and signs a payment, Nordea will prompt the customer for a second channel (SMS) confirmation. A SMS will be sent to the registered phone number of the user, where the customer can confirm or reject the payment by replying to the SMS.

The payment model has been enhanced with additional attribute “requires_second_channel_confirmation” in the payment details. With the combination of the “Status” and “requires_second_channel_confirmation” values, the customer can identify the next steps as described below,

Status	requires_second_channel_confirmation	Remarks
OnHold	true	The payment has been put on hold as it requires second channel confirmation. The customer should have received a SMS to confirm or reject the payment.
OnHold	false	The payment has been put on hold. The customer need to call the bank to proceed further.

Key Notes:

If the response is not received for a SMS notification within a configured time period (say 2 weeks), then the bank will no longer accept the response for that specific SMS notification. In such case, the customer needs to call the bank to release the payment.
A limit has been set on the number of payments that can wait in the queue until it is confirmed. If there has been a configured number of SMS notifications (say 5 SMS notifications) sent per user with the registered phone number and not responded by the user, then no SMS notifications will be sent to that user until at least one payment in the queue is released i.e. if one OnHold payment is confirmed, then it opens up the queue for one more SMS notification.
If the customer has utilized the full queue length (say 5) and has not responded to any of those during the configured time period (say 2 weeks), then the customer needs to call the bank to release the payments.

API endpoints

The PIS API contains the following endpoint:

Endpoint	Supported HTTP Methods
`/payments/domestic/salarypension`	POST

The /payments/domestic/{paymentId} endpoint can be used to query payment details by payment id, and it supports only GET HTTP method. The payment id is returned when payment is initiated successfully, and it can be found from the response JSON by the name _id. Moreover, the payment status can be seen in the response by the name payment_status. Full response example of this endpoint can be seen on examples section below.

Nordea payment type field combinations

Country	Endpoint	debtor.account_type	creditor.account_type	.currency
SE	/domestic/salarypension	”PGNR” or “BGNR"	"BBAN_SE"	"SEK”
NO	/domestic/salarypension	”BBAN_NO"	"BBAN_NO"	"NOK”

Note: For Sweden payment must be confirmed at least two banking days before and execution date must be one day before the money is to arrive in the recipient’s account. Cut-off time for Salary/Pension is 23.59 two banking days before pay-out day.

Data models

Below you can find fields that can or must be provided for Salary or Pension payment initiation (POST payments/domestic/salarypension)

Field	Supported countries	Mandatory	Example	Comment
debtor.account.value	SE, NO	X	SE 9637042, NO - 60391641245
debtor.account.type	SE, NO	X	SE -PGNR, NO - BBAN_NO
debtor.account.currency	SE, NO	X	SEK, NOK	Only domestic accounts supported
creditor.account.value	SE, NO	X	13370233835
creditor.account._type	SE, NO	X	BBAN_SE, BBAN_NO	Creditor account must not be PlusGiro/BankGiro
creditor.account.currency	NO	Mandatory only for NO	NOK
creditor.name	NO	Mandatory only for NO	Mark Twain
amount	SE, NO	X	21.37
currency	SE, NO	X	SEK, NOK
requested_execution_date	SE, NO	-	2022-10-14	For Sweden date must be at least +1D
paymentType	SE, NO	X	SALARY	Enum field [SALARY, PENSION], for Norway “PENSION” is not supported
message	NO	-	Salary Oct 2022
own_message	SE, NO	-	Payment to Mikel

Also note, that single Payment model (PaymentV4) has been expanded. Field “paymentType” is added. Due to GET payments/domestic and GET payments/domestic/{paymentId} is used for fetching domestic, own transfer, salary and pension, “paymentType” helps to indicate of which type is returned payment.

Confirmation of availability of funds

The given functionality gives TPP the possibility to confirm the availability of funds - so that TPP can decide to either further process, cancel and/or sign the payment or not.

Two new optional parameters have been added:

“request_availability_of_funds” (request)
“availability_of_funds” (response)

Countries in scope: SE, NO.

Payment initiation

Sandbox:

If 2SCA payment initiation endpoint is available and the request contains the new field: “request_availability_of_funds” set to “true” and Sandbox scenario is not being specified in request header - when the endpoint is invoked, then the payment initiation response will be returned with new field: “availability_of_funds” that is set based on the actual check that verifies the payment amount against the available balance on the account.
If 2SCA payment initiation endpoint is available and the request contains the new field: “request_availability_of_funds” set to “true” and Sandbox scenario is specified as: “FundsAvailable” in request header - when the endpoint is invoked, then the payment initiation response will be returned with new field: “availability_of_funds” that is set to “true”.
If 2SCA payment initiation endpoint is available and the request contains the new field: “request_availability_of_funds” set to “true” and Sandbox scenario is specified as: “FundsNotAvailable” in request header - when the endpoint is invoked, then the payment initiation response will be returned with new field: “availability_of_funds” that is set to “false”.

Production:

If 2SCA payment initiation endpoint is available and the request contains the new field: “request_availability_of_funds” set to “true” - when the endpoint is invoked, then the payment initiation response will be returned with new field: “availability_of_funds” that is set based on the actual check that verifies the payment amount against the available balance on the account.

Get payment details

Sandbox:

If 2SCA get payment details endpoint is available and the request contains the new field: “request_availability_of_funds” set to “true” and Sandbox scenario is not being specified in request header and payment status is not: “InsufficientFunds”, “Rejected”, “Paid” or “Unknown” - when the endpoint is invoked, then the get payment details response will be returned with new field: “availability_of_funds” that is set based on the actual check that verifies the payment amount against the available balance on the account.
If 2SCA get payment details endpoint is available and the request contains the new field: “request_availability_of_funds” set to “true” and Sandbox scenario is specified as: “FundsAvailable” in request header and payment status is not: “InsufficientFunds”, “Rejected”, “Paid” or “Unknown” - when the endpoint is invoked, then the get payment details response will be returned with new field: “availability_of_funds” that is set to “true”.
If 2SCA get payment details endpoint is available and the request contains the new field: “request_availability_of_funds” set to “true” and Sandbox scenario is specified as: “FundsNotAvailable” in request header and payment status is not: “InsufficientFunds”, “Rejected”, “Paid” or “Unknown” - when the endpoint is invoked, then the get payment details response will be returned with new field: “availability_of_funds” that is set to “false”.

Production:

If 2SCA get payment details endpoint is available and the request contains the new field: “request_availability_of_funds” set to “true” and payment status is not: “InsufficientFunds”, “Rejected”, “Paid” or “Unknown” - when the endpoint is invoked, then the get payment details response will be returned with new field: “availability_of_funds” that is set based on the actual check that verifies the payment amount against the available balance on the account.

The examples of Confirmation of availability of funds can be found in this documentation under: PIS API Sweden examples section.

PIS API Sweden Salary examples

Payment initiation for Salary

This example shows how to initiate Salary in SE

This endpoint URL has the following form

https://api.nordeaopenbanking.com/business/v4/payments/domestic/salarypension

This endpoint supports POST HTTP Method only.

Here is an example request. The example contains Confirmation of availability of funds:

$ curl 'https://api.nordeaopenbanking.com/business/v4/payments/domestic/salarypension' -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 '{
    "amount": "1.49",
    "currency": "SEK",
    "creditor": {
        "account": {
            "_type": "BBAN_SE",
            "value": "13370233835"
        }
    },
    "debtor": {
        "account": {
            "_type": "PGNR",
            "currency": "SEK",
            "value": "9637042"
        },
        "message": "Message"
    },
    "externalId": "string",
    "payment_type": "SALARY",
    "requested_execution_date": "2022-10-13",
    "request_availability_of_funds": true
}

And the response looks like this:

{
    "group_header": {
        "message_identification": "2c84b406-8f69-49ac-982c-b29dba4484f5",
        "creation_date_time": "2022-10-11T11:46:18.7245074Z",
        "http_code": 201
    },
    "response": {
        "_id": "1b129cb7-b2fc-4529-88e8-65305f84e09e",
        "entry_date_time": "2022-10-11T13:46:18.717509Z",
        "debtor": {
            "account": {
                "value": "9637042",
                "_type": "PGNR",
                "currency": "SEK"
            }
        },
        "creditor": {
            "account": {
                "value": "13370233835",
                "_type": "BBAN_SE",
                "currency": "SEK"
            }
        },
        "amount": "1.49",
        "currency": "SEK",
        "payment_status": "PendingConfirmation",
        "tpp_messages": [],
        "_links": [{
                "rel": "self",
                "href": "/v4/payments/domestic/1b129cb7-b2fc-4529-88e8-65305f84e09e"
            }, {
                "rel": "confirm",
                "href": "/v4/payments/domestic/confirm"
            }
        ],
        "planned_execution_date": "2022-10-13",
        "requested_execution_date": "2022-10-13",
        "payment_type": "SALARY",
        "availability_of_funds": false
    }
}

Payment initiation for Pension

This example shows how to initiate Pension payment in SE

This endpoint URL has the following form

https://api.nordeaopenbanking.com/business/v4/payments/domestic/salarypension

This endpoint supports POST HTTP Method only.

Here is an example request:

$ curl 'https://api.nordeaopenbanking.com/business/v4/payments/domestic/salarypension' -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 '{
    "amount": "1.49",
    "currency": "SEK",
    "creditor": {
        "account": {
            "_type": "BBAN_SE",
            "value": "13370233835"
        }
    },
    "debtor": {
        "account": {
            "_type": "PGNR",
            "currency": "SEK",
            "value": "9637042"
        },
        "message": "Message"
    },
    "externalId": "string",
    "payment_type": "PENSION",
    "requested_execution_date": "2022-10-13"
}

And the response looks like this:

{
    "group_header": {
        "message_identification": "2c84b406-8f69-49ac-982c-b29dba4484f5",
        "creation_date_time": "2022-10-11T11:46:18.7245074Z",
        "http_code": 201
    },
    "response": {
        "_id": "1b129cb7-b2fc-4529-88e8-65305f84e09e",
        "entry_date_time": "2022-10-11T13:46:18.717509Z",
        "debtor": {
            "account": {
                "value": "9637042",
                "_type": "PGNR",
                "currency": "SEK"
            }
        },
        "creditor": {
            "account": {
                "value": "13370233835",
                "_type": "BBAN_SE",
                "currency": "SEK"
            }
        },
        "amount": "1.49",
        "currency": "SEK",
        "payment_status": "PendingConfirmation",
        "tpp_messages": [],
        "_links": [{
                "rel": "self",
                "href": "/v4/payments/domestic/1b129cb7-b2fc-4529-88e8-65305f84e09e"
            }, {
                "rel": "confirm",
                "href": "/v4/payments/domestic/confirm"
            }
        ],
        "planned_execution_date": "2022-10-13",
        "requested_execution_date": "2022-10-13",
        "payment_type": "PENSION"
    }
}

Payment list

This example shows how to fetch payment list including Salary and Pension in SE

This endpoint URL has the following form

https://api.nordeaopenbanking.com/business/v4/payments/domestic

This endpoint supports GET HTTP Method only.

Here is an example response:

{ 
"response": {
     "payments": [{
             "_id": "1b129cb7-b2fc-4529-88e8-65305f84e09e",
             "entry_date_time": "2022-10-11T13:46:18.717509Z",
             "debtor": {
                 "account": {
                     "value": "9637042",
                     "_type": "PGNR",
                     "currency": "SEK"
                 }
             },
             "creditor": {
                 "account": {
                     "value": "13370233835",
                     "_type": "BBAN_SE",
                     "currency": "SEK"
                 }
             },
             "amount": "1.49",
             "currency": "SEK",
             "payment_status": "PendingConfirmation",
             "tpp_messages": [],
             "_links": [{
                     "rel": "self",
                     "href": "/v4/payments/domestic/1b129cb7-b2fc-4529-88e8-65305f84e09e"
                 }, {
                     "rel": "confirm",
                     "href": "/v4/payments/domestic/confirm"
                 }
             ],
             "planned_execution_date": "2022-10-13",
             "requested_execution_date": "2022-10-13",
             "payment_type": "SALARY"
         }
     ]
 }
 }

PIS API Norway Salary examples

Payment initiation for Salary

This example shows how to initiate Salary in NO

This endpoint URL has the following form

https://api.nordeaopenbanking.com/business/v4/payments/domestic/salarypension

This endpoint supports POST HTTP Method only.

Here is an example request:

$ curl 'https://api.nordeaopenbanking.com/business/v4/payments/domestic/salarypension' -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 '{
    "amount": "1.00",
    "creditor": {
        "account": {
            "_type": "BBAN_NO",
            "currency": "NOK",
            "value": "60010503178"
        },
        "name": "Beneficiary name"
    },
    "currency": "NOK",
    "debtor": {
        "account": {
            "_type": "BBAN_NO",
            "currency": "NOK",
            "value": "61735686908"
        },
        "message": "Message for debtor"
    },
    "external_id": "some id",
    "payment_type": "SALARY"
}

And the response looks like this:

{
    "group_header": {
        "message_identification": "654c61bf-31ce-4a40-8f6b-f04b6cfce67e",
        "creation_date_time": "2022-11-29T10:21:48.762581Z",
        "http_code": 201
    },
    "response": {
        "_id": "170bc57d-8d13-4c95-a907-7c625a0eeeaa",
        "external_id": "some id",
        "entry_date_time": "2022-11-29T10:21:48.762111Z",
        "debtor": {
            "account": {
                "value": "61735686908",
                "_type": "BBAN_NO",
                "currency": "NOK"
            }
        },
        "creditor": {
            "account": {
                "value": "60010503178",
                "_type": "BBAN_NO",
                "currency": "NOK"
            }
        },
        "amount": "1",
        "currency": "NOK",
        "payment_status": "PendingConfirmation",
        "tpp_messages": [],
        "_links": [
            {
                "rel": "self",
                "href": "/v4/payments/domestic/170bc57d-8d13-4c95-a907-7c625a0eeeaa"
            },
            {
                "rel": "confirm",
                "href": "/v4/payments/domestic/confirm"
            }
        ],
        "planned_execution_date": "2022-11-29",
        "payment_type": "SALARY"
    }
}

Payment list

This example shows how to fetch payment list for Salary in NO.

This endpoint URL has the following form

https://api.nordeaopenbanking.com/business/v4/payments/domestic

This endpoint supports GET HTTP Method only.

Here is an example response:

{
    "group_header": {
        "message_identification": "3b0e2fb6-003e-4fbd-8c7d-5c5f3aaafca6",
        "creation_date_time": "2022-11-29T10:22:46.859985Z",
        "http_code": 200
    },
    "errors": [],
    "_links": [],
    "response": {
        "payments": [
            {
                "_id": "170bc57d-8d13-4c95-a907-7c625a0eeeaa",
                "external_id": "some id",
                "entry_date_time": "2022-11-29T10:21:48.762111Z",
                "debtor": {
                    "account": {
                        "value": "61735686908",
                        "_type": "BBAN_NO",
                        "currency": "NOK"
                    }
                },
                "creditor": {
                    "account": {
                        "value": "60010503178",
                        "_type": "BBAN_NO",
                        "currency": "NOK"
                    }
                },
                "amount": "1",
                "currency": "NOK",
                "payment_status": "PendingConfirmation",
                "tpp_messages": [],
                "_links": [
                    {
                        "rel": "self",
                        "href": "/v4/payments/domestic/170bc57d-8d13-4c95-a907-7c625a0eeeaa"
                    },
                    {
                        "rel": "confirm",
                        "href": "/v4/payments/domestic/confirm"
                    }
                ],
                "planned_execution_date": "2022-11-29",
                "payment_type": "SALARY"
            },
            {
                "_id": "a6ad52a7-f6d2-44ad-a863-f49f01e5bb88",
                "external_id": "some id",
                "entry_date_time": "2022-11-29T10:21:29.966157Z",
                "debtor": {
                    "account": {
                        "value": "61735686908",
                        "_type": "BBAN_NO",
                        "currency": "NOK"
                    }
                },
                "creditor": {
                    "account": {
                        "value": "60010503178",
                        "_type": "BBAN_NO",
                        "currency": "NOK"
                    }
                },
                "amount": "1",
                "currency": "NOK",
                "payment_status": "PendingConfirmation",
                "tpp_messages": [],
                "_links": [
                    {
                        "rel": "self",
                        "href": "/v4/payments/domestic/a6ad52a7-f6d2-44ad-a863-f49f01e5bb88"
                    },
                    {
                        "rel": "confirm",
                        "href": "/v4/payments/domestic/confirm"
                    }
                ],
                "planned_execution_date": "2022-11-29",
                "payment_type": "SALARY"
            }
        ]
    }
}

Single payment details

This example shows how to fetch details of a single payment in NO.

This endpoint URL has the following form

https://api.nordeaopenbanking.com/business/v4/payments/domestic/{payment_id}

This endpoint supports GET HTTP Method only.

Here is an example response when the payment requires second channel confirmation:


{
   "group_header": {
       "message_identification": "c0d2f884-b846-4dcf-b9fd-829cf7aff6ed",
       "creation_date_time": "2023-02-03T11:08:38.981056Z",
       "http_code": 200
   },
   "response": {
       "_id": "a585f376-5271-4ab0-ad8c-c0b062cce842",
       "entry_date_time": "2023-02-03T11:07:06.217589Z",
       "debtor": {
           "account": {
               "value": "60391641245",
               "_type": "BBAN_NO",
               "currency": "NOK"
           },
           "message": "NO 2ND CC PKK 2"
       },
       "creditor": {
           "account": {
               "value": "60011809106",
               "_type": "BBAN_NO",
               "currency": "NOK"
           }
       },
       "amount": "50.99",
       "currency": "NOK",
       "payment_status": "OnHold",
       "tpp_messages": [],
       "_links": [
           {
               "rel": "self",
               "href": "/v4/payments/domestic/a585f376-5271-4ab0-ad8c-c0b062cce842"
           }
       ],
       "planned_execution_date": "2023-02-03",
       "urgency": "standard",
       "requested_execution_date": "2023-02-03",
       "payment_type": "SALARY",
       "requires_second_channel_confirmation": true
   }
}

Business Payments Own Transfer API v4 Business Payments SEPA Credit Transfer API v4