PIS API specific documentation Own Account Transfers
Changes from the previous version
This is the change log of the PIS API (own transfer), allowing PSD2-regulated TPPs to initiate own 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, own transfer 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 recurrency in FI Own Transfers
Version 4.1
Added support for recurrency in NO Own Transfers (sandbox only)
Version 4.0
Created
/v4/payments/domestic/owntransfer
/v4/payments/sepa/owntransfer
Note: We have implemented separate endpoint for FI Own Transfer due to separation of data model.
Overview
The PIS API for own transfers can be used to initiate and confirm account transfers for the same legal entity, i.e. the (co-)owner of both accounts has to be the same. This API supports POST HTTP method only. Check status of payments, deletions etc. can be done via the /payments/domestic
and /payments/sepa
endpoints, but own transfers have to be initiated via this service, else they will be treated as normal payments that have to be signed.
This API has similar request model as domestic or SEPA payments, but with limited set of properties dedicated to Own Transfer. Service comes with a set of deviations as these payments are for internal, account to account transfers only:
- no future dated payments in SE and NO
- no urgency property (own transfers get executed instantly at provided ‘requested execution date’)
Note: If the debtor and creditor account are not related to the same legal entity, the payment will not be accepted. Note: If debtor and creditor accounts are in different countries, it is not an own transfer, but a cross border payment even if they are the same legal entity.
In Sandbox: Note that sandbox accepts all creditor account numbers, i.e. we do not check the legal entity.
API endpoints
The PIS API contains the following endpoints:
Endpoint | Supported HTTP Methods |
---|---|
/payments/domestic/owntransfer | POST |
/payments/sepa/owntransfer | POST |
The /payments/domestic/{paymentId}
or /payments/sepa/{paymentId}
endpoints 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 |
---|---|---|---|---|
FI | /sepa/owntransfer | ”IBAN" | "IBAN" | "EUR” |
SE | /domestic/owntransfer | ”PGNR” or “BBAN_SE" | "PGNR” or “BBAN_SE" | "SEK” or foreign currency |
DK | /domestic/owntransfer | ”BBAN_DK” or “IBAN" | "BBAN_DK" | "DKK” or foreign currency |
NO | /domestic/owntransfer | ”BBAN_NO" | "BBAN_NO" | "NOK” |
Key Highlights
DK
- Support for future dated payment
- Creditor message is required
- Support for recurrency as in domestic payment. Recurrency is available only if currency (both debtor and creditor) is set as ‘DKK’
- 4eyes confirmation process is required if user is not permitted to confirm payments alone
SE
- Future dated payment is not supported
NO
- Future dated payment is not supported
FI
- Support for future dated payment
- Support for recurrency as in SEPA 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: DK, FI, 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 DK Own transfer examples section.
PIS API DK Own transfer examples
This example shows how to initiate Own Transfer (with recurrency) in DK.
This endpoint URL has the following form
https://api.nordeaopenbanking.com/business/v4/payments/domestic/owntransfer
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/owntransfer' -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":"123.45",
"currency":"DKK",
"debtor":{
"account":{
"_type":"BBAN_DK",
"currency":"DKK",
"value":"20001545768360"
},
"message":"Own message"
},
"creditor":{
"account":{
"_type":"BBAN_DK",
"currency":"DKK",
"value":"20001545785605"
},
"message":"Creditor msg"
},
"recurring":{
"count":5,
"recurrence_type":"WEEKLY"
},
"request_availability_of_funds": true
}
And the response looks like this:
{
"group_header":
{
"message_identification": "m3-1v7i7FiM",
"creation_date_time": "2022-10-09T10:11:12.134Z",
"http_code": 201
},
"response": {
"_id":"fab483a9-af20-4640-8372-1dac317ef994",
"entry_date_time":"2022-10-09T10:11:12.134Z",
"debtor":{
"account":{
"value":"20001545768360",
"_type":"BBAN_DK",
"currency":"DKK"
},
"message":"Own message"
},
"creditor":{
"account":{
"value":"20001545785605",
"_type":"BBAN_DK",
"currency":"DKK"
},
"message":"Creditor msg"
},
"amount":"123.45",
"currency":"DKK",
"payment_status":"Paid",
"tpp_messages":[
],
"_links":[
{
"rel":"self",
"href":"/business/v4/payments/domestic/owntransfer/fab483a9-af20-4640-8372-1dac317ef994"
}
],
"recurring":{
"count":5,
"recurrence_type":"WEEKLY"
},
"planned_execution_date":"2022-10-09",
"requested_execution_date":"2022-10-09",
"availability_of_funds": false
}
PIS API SE Own transfer examples
This example shows how to initiate Own Transfer in SE.
This endpoint URL has the following form
https://api.nordeaopenbanking.com/business/v4/payments/domestic/owntransfer
This endpoint supports POST HTTP Method only.
Note: Own Transfer in SE does not support future dated payments
Here is an example request:
$ curl 'https://api.nordeaopenbanking.com/business/v4/payments/domestic/owntransfer' -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": 1230.45,
"creditor": {
"account": {
"_type": "BBAN_SE",
"currency": "SEK",
"value": "13370233835"
}
},
"currency": "SEK",
"debtor": {
"account": {
"_type": "PGNR",
"currency": "SEK",
"value": "9637042"
},
"message": "Message for debtor"
},
"external_id": "some id"
}'
And the response looks like this:
{
"group_header":
{
"message_identification": "m3-1v7i7FiM",
"creation_date_time": "2022-10-09T10:11:12.134Z",
"http_code": 201
},
"response": {
"_id":"fab483a9-af20-4640-8372-1dac317ef994",
"entry_date_time":"2022-10-09T10:11:12.134Z",
"debtor":{
"account":{
"value":"9637042",
"_type":"PGNR",
"currency":"SEK"
},
"message":"Own message"
},
"creditor":{
"account":{
"value":"13370233835",
"_type":"BBAN_SE",
"currency":"SEK"
}
},
"amount":"1230.45",
"currency":"SEK",
"payment_status":"Paid",
"tpp_messages":[
],
"_links":[
{
"rel":"self",
"href":"/business/v4/payments/domestic/owntransfer/fab483a9-af20-4640-8372-1dac317ef994"
}
],
"planned_execution_date":"2022-10-09",
"requested_execution_date":"2022-10-09"
}
PIS API FI Own transfer examples
This example shows how to initiate Own Transfer in FI.
This endpoint URL has the following form
https://api.nordeaopenbanking.com/business/v4/payments/sepa/owntransfer
This endpoint supports POST HTTP Method only.
Note: Own Transfer in FI does not support cross-currency transfer
$ curl 'https://api.nordeaopenbanking.com/business/v4/payments/sepa/owntransfer' -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":"123.45",
"currency":"EUR",
"debtor":{
"account":{
"_type":"IBAN",
"currency":"EUR",
"value":"FI1350001520000081"
}
},
"creditor":{
"account":{
"_type":"IBAN",
"currency":"EUR",
"value":"FI3815903000105518"
},
"message":"Creditor msg"
}
}'
And the response looks like this:
{
"group_header":
{
"message_identification": "m3-1v7i7FiM",
"creation_date_time": "2022-10-09T10:11:12.134Z",
"http_code": 201
},
"response": {
"_id":"fab483a9-af20-4640-8372-1dac317ef994",
"entry_date_time":"2022-10-09T10:11:12.134Z",
"debtor":{
"account":{
"value":"FI1350001520000081",
"_type":"IBAN",
"currency":"EUR"
}
},
"creditor":{
"account":{
"value":"FI3815903000105518",
"_type":"IBAN",
"currency":"EUR"
},
"message":"Creditor msg"
},
"amount":"123.45",
"currency":"EUR",
"payment_status":"Paid",
"tpp_messages":[
],
"_links":[
{
"rel":"self",
"href":"/business/v4/payments/sepa/owntransfer/fab483a9-af20-4640-8372-1dac317ef994"
}
],
"planned_execution_date":"2022-10-09",
"requested_execution_date":"2022-10-09"
}
PIS API NO Own transfer examples
This example shows how to initiate Own Transfer (with recurrency) in NO.
This endpoint URL has the following form
https://api.nordeaopenbanking.com/business/v4/payments/domestic/owntransfer
This endpoint supports POST HTTP Method only.
Note: Own Transfer in NO does not support future dated and cross-currency transfers
$ curl 'https://api.nordeaopenbanking.com/business/v4/payments/domestic/owntransfer' -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": "2.09",
"currency": "NOK",
"creditor": {
"account": {
"_type": "BBAN_NO",
"currency": "NOK",
"value": "60010099902"
}
},
"debtor": {
"account": {
"_type": "BBAN_NO",
"currency": "NOK",
"value": "61735686908"
},
"message": "DBTR MESSAGE"
},
"external_id": "TPP Unique ID",
"recurring": {
"end_date": "2024-05-01",
"recurrence_type": "WEEKLY"
}
}'
And the response looks like this:
{
"group_header": {
"message_identification": "e30d0de6-d3e9-4ad0-9c8a-05e3845e1b53",
"creation_date_time": "2022-08-08T14:38:50.567324Z",
"http_code": 201
},
"response": {
"_id": "2d029823-0f82-487c-8e0a-611e2d351204",
"external_id": "TPP Unique ID",
"entry_date_time": "2022-08-08T14:38:50.562849Z",
"debtor": {
"account": {
"value": "61735686908",
"_type": "BBAN_NO",
"currency": "NOK"
}
},
"creditor": {
"account": {
"value": "60010099902",
"_type": "BBAN_NO",
"currency": "NOK"
}
},
"amount": "2.09",
"currency": "NOK",
"payment_status": "Confirmed",
"tpp_messages": [],
"_links": [
{
"rel": "self",
"href": "/v4/payments/domestic/2d029823-0f82-487c-8e0a-611e2d351204"
}
],
"planned_execution_date": "2022-08-08",
"recurring": {
"end_date": "2024-05-01",
"recurrence_type": "WEEKLY"
}
}
}