Compliance APIsPersonalCardsCommercial Cards V1

API specific documentation

Changes from the previous version

This is the change log of the Commercial Cards API. The top most item is the latest change and the API changes described in it are relative to the version directly below. The current latest version of the API is 1.3.

NOTE: Commercial Cards API version 1.0 is initial version of API supporting First Card product.

Version 1.3

KEY CHANGE: Adding note for transactions date range validation rule.

  • Notification for Commercial Cards transactions validation, when optional date range fields are provided in input request.

Version 1.2

KEY CHANGE: Adding note.

  • Updated Overview

Version 1.1

KEY CHANGE: Adding notification for TPP that they can fetch limited transaction data up to last 90-days.

  • Notification for Commercial Cards transactions

Version 1.0

KEY CHANGE: Initial API supporting Commercial Cards for all countries (Sweden, Norway, Denmark, Finland).

  • Overview
  • Endpoints in details
  • Table containing Sandbox data - records with supported First Cards.
  • Example responses.

Overview

The Commercial Cards API provides real-time consolidated information on a Nordea customer’s Commercial Card(s) and transactions on those cards. For the time being debit card information will be available through the regular account services. The information and hence the operations that the API provides can be divided into the following categories:

  • Card-related
    • Card list
    • Card details
  • Transaction-related
    • Transaction history

The Commercial Cards API includes three endpoints. The API can be used only to query information, and it is read-only, therefore, supports only the GET HTTP method. The three endpoints provided by this API offer:

  • listing of users’ cards
  • details of each card and
  • transaction history for each card.

Note:

Please note that this API provides access to company data. When using this API, you need to ensure that you have received consent both from the company for which this card was issued and from the cardholder. The sole use of the API cannot ensure that you have collected company consent given that the cardholder through which you receive access is not necessarily entitled to give you consent on behalf of the company. We would therefore recommend that you use the API only in connection with an environment for which you can ensure that you have collected the necessary company consent or in any other way which secures that you have company consent for the data accessed.

Commercial Cards API endpoints

EndpointSupported HTTP Methods
/commercial-cardsGET
/commercial-cards/{CARD_ID}GET
/commercial-cards/{CARD_ID}/transactionsGET

As you can see from the table above, the API endpoints support GET methods.

Access authorization scopes

There are two authorization scopes applicable to the Card Accounts API. These are COMMERCIAL_CARDS_INFORMATION and COMMERCIAL_CARDS_TRANSACTIONS. The following table lists the scopes that are needed for each of the API endpoints.

EndpointRequired scopes
/commercial-cardsCOMMERCIAL_CARDS_INFORMATION
/commercial-cards/{CARD_ID}COMMERCIAL_CARDS_INFORMATION
/commercial-cards/{CARD_ID}/transactionsCOMMERCIAL_CARDS_INFORMATION+COMMERCIAL_CARDS_TRANSACTIONS

Scope COMMERCIAL_CARDS_TRANSACTIONS can only be requested in combination with scope COMMERCIAL_CARDS_INFORMATION+COMMERCIAL_CARDS_TRANSACTIONS.

You can use the first endpoint (called as ‘main endpoint’) to fetch the list of cards for given SSN and get a limited amount of information for all fetched cards to which the user has shared access. See examples section for the full response example.

You can use the second endpoint to query information about a specific given card (Card ID). The information provided contains more information than the one (main endpoint) provided through the /commercial-cards endpoint. Just to clarify, basically and technically to fetch card details you need to get unique card ID first, which is possible by using main endpoint /commercial-cards. Please see section on data model field relevance below to check the scope of attributes. See the examples section for a full response example.

You can use the third endpoint to query the transaction history for a specific given card. The response is a transaction listing. The GET method lists the transactions relevant for the particular given card. In all cases this includes the transactions made using the card. There is no discrepancies between countries, so regardless to the country, the user will get the same scope of data, but different cards. Like in previous endpoints, see the examples section for the full response example.

In addition to these endpoints, card IDs can be queried by using the assets endpoint from the Access Authorization API. This endpoint returns a list of card IDs for which the user has authorized access among other things. This endpoint is described in the Access Authorization documentation with examples on how to use it, and it also contains response examples.

Data model field relevance

Commercial Cards - card list

Field nameFirst Card (SE,NO,DK,FI)
idY
masked_credit_card_numberY
product_nameY
cardholder_nameY

*NOTE: No financial information (i.e. credit_limit, credit_available_balance) is available for First Card

Commercial Cards - card details

Field nameFirst Card (SE,NO,DK,FI)
idY
masked_credit_card_numberY
product_nameY
cardholder_nameY

*NOTE: No financial information (i.e. credit_limit, credit_available_balance) is available for First Card

Commercial Cards - card transactions list

Field nameFirst Card (SE,NO,DK,FI)Comments
idY
transaction_typeY
masked_credit_card_numberY
beneficiaryY
amountY
currencyY
original_amountYOnly available in case the transaction occurred in a currency different from the card currency
original_currencyYOnly available in case the transaction occurred in a currency different from the card currency
transaction_dateY

*NOTE: You will receive an access token from Nordea for a period defined by you up to 180 days. You are only entitled to access the payment transactions executed in the last 90 days when using this access token, unless strong customer authentication is performed.

*NOTE: When optional fields filtering the transaction date range are provided in request, then the following validation rule is applied: if end_date is given then start_date must also be given and start_date cannot be later then end_date.

 

Commercial Cards API examples

Here you can find examples on how to use the Commercial Cards API endpoints.

Note that in all the examples’ cURL commands, you must change the X-IBM-Client-Id, X-IBM-Client-Secret and Authorization: Bearer header values to the correct ones.

You can find the Client ID, and Client Secret from your app console and the Bearer is generated when you log in.

All of these examples can also be tried out in the API portals’ API Console easily, here we show cURL examples how to make the same API calls which can be performed by the API Console.

Remember to replace the {CARD_ID} URL parameter by correct values in the cURL examples below.

You can get a list of available CARD_IDs along with basic information about the cards by issuing the list cards example below. Please note that the CARD_IDs is not the same thing as a cardNumber. The latter cannot be used as a unique identifier and cannot be communicated though the API in full unmasked form due to Payment Card Industry Data Security Standard (PCI DSS) compliance regulations.

cURL examples

Example: list cards

Following cURL command can be used to fetch the card list after correct Application ID, Client Secret and Access Token are substituted in it:

This endpoint URL has the following form:

GET /v1/commercial-cards 

This endpoint supports GET HTTP method.

The following cURL can be used to fetch card list from this endpoint.

$ curl -X GET \
  {{API_URL}}/v1/commercial-cards/ \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -H 'X-IBM-Client-ID: {{CLIENT_ID}}' \
  -H 'X-IBM-Client-Secret: {{CLIENT_SECRET}}' \
  -H 'cache-control: no-cache'

Here are the responses for the query above:

For Finland:

{
    "group_header": {
        "message_identification": "O2SW1VMWx7d_etVT",
        "creation_date_time": "2023-03-10T09:16:19.331496083Z",
        "http_code": 200
    },
    "response": {
        "cards": [
            {
                "id": "CS3-d927c5cc-e790-43a7-a249-842663b6f5f8",
                "masked_credit_card_number": "5218 **** **** 7468",
                "product_name": "First Card Purchasing Card",
                "cardholder_name": "MAJA JENSEN"
            },
            {
                "id": "CS3-0a797fa1-368b-4979-a9e2-7faebb2445c6",
                "masked_credit_card_number": "5218 **** **** 0580",
                "product_name": "First Card Purchasing Card",
                "cardholder_name": "MAJA JENSEN"
            },
            {
                "id": "CS3-5db1d364-2f05-40bb-b239-438801dcd0bf",
                "masked_credit_card_number": "5218 **** **** 7279",
                "product_name": "First Card Private",
                "cardholder_name": "MAJA JENSEN"
            }
        ]
    }
}

For Norway:

{
    "group_header": {
        "message_identification": "O2SW1VMWx7d_etVT",
        "creation_date_time": "2023-03-10T09:16:19.331496083Z",
        "http_code": 200
    },
    "response": {
        "cards": [
            {
                "id": "CS3-d927c5cc-e790-43a7-a249-842663b6f5f8",
                "masked_credit_card_number": "5218 **** **** 7468",
                "product_name": "First Card Purchasing Card",
                "cardholder_name": "MAJA JENSEN"
            },
            {
                "id": "CS3-0a797fa1-368b-4979-a9e2-7faebb2445c6",
                "masked_credit_card_number": "5218 **** **** 0580",
                "product_name": "First Card Purchasing Card",
                "cardholder_name": "MAJA JENSEN"
            },
            {
                "id": "CS3-5db1d364-2f05-40bb-b239-438801dcd0bf",
                "masked_credit_card_number": "5218 **** **** 7279",
                "product_name": "First Card Private",
                "cardholder_name": "MAJA JENSEN"
            }
        ]
    }
}

For Denmark:

{
    "group_header": {
        "message_identification": "X7V4SGpxBhxopJaP",
        "creation_date_time": "2023-03-10T09:21:16.650591806Z",
        "http_code": 200
    },
    "response": {
        "cards": [
            {
                "id": "CS3-b6cd4999-e4b9-4822-8c66-1468a4fda24b",
                "masked_credit_card_number": "5218 **** **** 7468",
                "product_name": "First Card Corporate",
                "cardholder_name": "JAKOB SVENDSEN"
            },
            {
                "id": "CS3-1c98fabe-e48f-47c3-9fa5-e3aeec22d0a4",
                "masked_credit_card_number": "5218 **** **** 7279",
                "product_name": "First Card Visa",
                "cardholder_name": "JAKOB SVENDSEN"
            },
            {
                "id": "CS3-2c2e6c7e-88ec-4742-b848-77b287032bf6",
                "masked_credit_card_number": "5429 **** **** 9302",
                "product_name": "First Card Corporate",
                "cardholder_name": "JAKOB SVENDSEN"
            }
        ]
    }
}

For Sweden:

{
    "group_header": {
        "message_identification": "H5dujbvSUe98jzHu",
        "creation_date_time": "2023-03-10T09:32:07.927765869Z",
        "http_code": 200
    },
    "response": {
        "cards": [
            {
                "id": "CS3-a62de472-4524-4bd3-b369-3c42ab273dc0",
                "masked_credit_card_number": "5451 **** **** 9591",
                "product_name": "First Card Executive",
                "cardholder_name": "JOEL SÖDERGREN"
            },
            {
                "id": "CS3-24092d1e-9260-46d4-9217-f25651081008",
                "masked_credit_card_number": "5209 **** **** 8788",
                "product_name": "First Card Private",
                "cardholder_name": "JOEL SÖDERGREN"
            },
            {
                "id": "CS3-4a761e0d-c847-4cc8-9811-80ca251ff7d4",
                "masked_credit_card_number": "5520 **** **** 7227",
                "product_name": "First Card Executive",
                "cardholder_name": "JOEL SÖDERGREN"
            }
        ]
    }
}

Example: fetch card details

In this example, we fetch card details by CARD_ID which can be found by listing the cards. The endpoint URL has the following form:

GET /v1/commercial-cards/{CARD_ID} HTTP/1.1

This endpoint supports GET HTTP method.

Here is cURL command to fetch the card details information:

$ curl -X GET \
  {{API_URL}}/v1/commercial-cards/CS3-81a30a4f-67df-43d1-9279-24bf9774acc4 \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -H 'X-IBM-Client-ID: {{CLIENT_ID}}' \
  -H 'X-IBM-Client-Secret: {{CLIENT_SECRET}}' \
  -H 'cache-control: no-cache'

Response: For Finland

{
    "group_header": {
        "message_identification": "DaORmNiNfHNddK07",
        "creation_date_time": "2023-03-10T09:04:30.366684829Z",
        "http_code": 200
    },
    "response": {
        "id": "CS3-81a30a4f-67df-43d1-9279-24bf9774acc4",
        "masked_credit_card_number": "5521 **** **** 3409",
        "product_name": "First Card Visa",
        "cardholder_name": "PEKKA VIRTANEN"
    }
}

For Norway

{
    "group_header": {
        "message_identification": "QmfxyxtpZnkak0t2",
        "creation_date_time": "2023-03-10T09:16:34.371266081Z",
        "http_code": 200
    },
    "response": {
        "id": "CS3-d927c5cc-e790-43a7-a249-842663b6f5f8",
        "masked_credit_card_number": "5218 **** **** 7468",
        "product_name": "First Card Purchasing Card",
        "cardholder_name": "MAJA JENSEN"
    }
}

For Denmark

{
    "group_header": {
        "message_identification": "ayxpL33ODKjnykYq",
        "creation_date_time": "2023-03-10T09:21:45.033584055Z",
        "http_code": 200
    },
    "response": {
        "id": "CS3-b6cd4999-e4b9-4822-8c66-1468a4fda24b",
        "masked_credit_card_number": "5218 **** **** 7468",
        "product_name": "First Card Corporate",
        "cardholder_name": "JAKOB SVENDSEN"
    }
}

For Sweden

{
    "group_header": {
        "message_identification": "CyAOuyaWRT8A5mHr",
        "creation_date_time": "2023-03-10T09:32:23.641711194Z",
        "http_code": 200
    },
    "response": {
        "id": "CS3-a62de472-4524-4bd3-b369-3c42ab273dc0",
        "masked_credit_card_number": "5451 **** **** 9591",
        "product_name": "First Card Executive",
        "cardholder_name": "JOEL SÖDERGREN"
    }
}

Example: fetch transaction list

In this example, we fetch card transaction list by CARD_ID which can be found by listing the cards. The endpoint URL has the following form:

GET /v1/commercial-cards/{CARD_ID}/transactions HTTP/1.1

This endpoint supports GET HTTP method.

Here is cURL command to fetch the transaction list information:

For Finland

$ curl -X GET \
  {{API_URL}}/v1/commercial-cards/CS3-81a30a4f-67df-43d1-9279-24bf9774acc4/transactions \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -H 'X-IBM-Client-ID: {{CLIENT_ID}}' \
  -H 'X-IBM-Client-Secret: {{CLIENT_SECRET}}' \
  -H 'cache-control: no-cache'

Response:

{
    "group_header": {
        "message_identification": "kZ8OCsP__q2JjpFK",
        "creation_date_time": "2023-03-10T09:04:52.245899007Z",
        "http_code": 200
    },
    "response": {
        "transactions": [
            {
                "id": "bbc3af2f-750c-4932-8082-c8968694f588",
                "transaction_type": "Card purchases",
                "beneficiary": "BENEFICIARY 2",
                "amount": "-0.77",
                "currency": "SEK",
                "transaction_date": "2023-03-10"
            }
        ]
    }
}

For Norway

$ curl -X GET \
  {{API_URL}}/v1/commercial-cards/CS3-d927c5cc-e790-43a7-a249-842663b6f5f8/transactions \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -H 'X-IBM-Client-ID: {{CLIENT_ID}}' \
  -H 'X-IBM-Client-Secret: {{CLIENT_SECRET}}' \
  -H 'cache-control: no-cache'

Response:

{
    "group_header": {
        "message_identification": "lcsjU9SmL-HLDNBM",
        "creation_date_time": "2023-03-10T09:16:50.784552625Z",
        "http_code": 200
    },
    "response": {
        "transactions": [
            {
                "id": "73f6d4aa-a518-4d2d-9edb-08eeae370161",
                "transaction_type": "Card purchases",
                "beneficiary": "BENEFICIARY 6",
                "amount": "-0.45",
                "currency": "NOK",
                "transaction_date": "2023-03-10"
            }
        ]
    }
}

For Denmark

$ curl -X GET \
  {{API_URL}}/v1/commercial-cards/CS3-b6cd4999-e4b9-4822-8c66-1468a4fda24b/transactions \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -H 'X-IBM-Client-ID: {{CLIENT_ID}}' \
  -H 'X-IBM-Client-Secret: {{CLIENT_SECRET}}' \
  -H 'cache-control: no-cache'

Response:

{
    "group_header": {
        "message_identification": "lglnEf5QF9EbZYzH",
        "creation_date_time": "2023-03-10T09:21:57.863584225Z",
        "http_code": 200
    },
    "response": {
        "transactions": [
            {
                "id": "3f7119e6-0d0e-4783-a98f-a753790ac754",
                "transaction_type": "Card purchases",
                "beneficiary": "BENEFICIARY 16",
                "amount": "-1.95",
                "currency": "EUR",
                "transaction_date": "2023-03-10"
            }
        ]
    }
}

For Sweden

$ curl -X GET \
  {{API_URL}}/v1/commercial-cards/CS3-b6cd4999-e4b9-4822-8c66-1468a4fda24b/transactions \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -H 'X-IBM-Client-ID: {{CLIENT_ID}}' \
  -H 'X-IBM-Client-Secret: {{CLIENT_SECRET}}' \
  -H 'cache-control: no-cache'

Response:

{
    "group_header": {
        "message_identification": "lglnEf5QF9EbZYzH",
        "creation_date_time": "2023-03-10T09:21:57.863584225Z",
        "http_code": 200
    },
    "response": {
        "transactions": [
            {
                "id": "3f7119e6-0d0e-4783-a98f-a753790ac754",
                "transaction_type": "Card purchases",
                "beneficiary": "BENEFICIARY 16",
                "amount": "-1.95",
                "currency": "EUR",
                "transaction_date": "2023-03-10"
            }
        ]
    }
}

Additional information: fetch transaction list with continuation key

In the Commercial Cards, we do not support any pagination mechanism incl. continuation key.



### Sandbox data
Cards sandbox only supports a single end user’s view. The cards of that special end user are as listed in the following table.
The end user, and respectively, the credit cards (as product), are the same for Finland, Sweden, Norway and Denmark.

|Country|Card ID|Product Type|Product Name|Masked card number|Payment day of month|
|---|---|---|---|---|---|
|FI|CS3-9BF5B541A40D4626B090E6FAA7037596|CORPORATE|First Card Corporate|5228 **** **** 8434|1|
|FI|CS3-3283515E8EF14399A782A330AEAD6053|CORPORATE|First Card Corporate|5228 **** **** 6176|1|
|FI|CS3-1CED82BDCB3646E0AF91CD1894811F99|CORPORATE|First Card Corporate|5228 **** **** 8447|1|
|FI|CS3-5D680D3C8B3F460CB2243F6E720E3F7c|CORPORATE|First Card Corporate|5228 **** **** 9322|1|
|FI|CS3-9433E3F4A3674544A54BC02EA0115D1d|EXECUTIVE|First Card Executive|5228 **** **** 5509|15|
|FI|CS3-99F1A25072C54D28B2F777B5C246E7Ea|CORPORATE|First Card Corporate|5430 **** **** 1840|14|
|FI|CS3-E181CD280C1245DBAE2592F725F0B5Be|EXECUTIVE|First Card Executive|5430 **** **** 0871|14|
|FI|CS3-C9AF1C76359D4C5E99F90DDBBDB8F088|EXECUTIVE|First Card Executive|5396 **** **** 2099|14|
|FI|CS3-A52917B4C1CA4BF5B7904E1B538542B9|EXECUTIVE|First Card Executive|5396 **** **** 1110|14|
|FI|CS3-A1A16C306E4841369645D1E96BCA2D18|EXECUTIVE|First Card Executive|5396 **** **** 7878|14|
|FI|CS3-63A26B6C34404FB39D8F5740BA58C3A1|EXECUTIVE|First Card Executive|5430 **** **** 3766|1|
|FI|CS3-B3FF3EA3FEA742198E5EC7D5E15A3F03|EXECUTIVE|First Card Executive|5430 **** **** 2213|1|
|FI|CS3-1C04A694ED5B4CCCBB00551608CA31CA|PRIVATE|First Card Private|5430 **** **** 9906|5|
|FI|CS3-21E51003BB5143F28D93C1460967E62F|PRIVATE|First Card Private|5430 **** **** 5720|15|
|FI|CS3-398DBD109A5046E986FB2EA4F117CE80|PURCHASING|First Card Purchasing|5521 **** **** 8911|30|
|FI|CS3-53D53072697647088A9B368485FF2C91|PURCHASING|First Card Purchasing|5430 **** **** 2194|15|
|FI|CS3-E397C918FF1244F79DE23D3DA38D243E|PURCHASING|First Card Purchasing|5430 **** **** 7340|15|
|FI|CS3-5B53E99160E64FF3BEAD00AD25D3B4A9|CORPORATE_VISA|First Card Visa|5430 **** **** 2189|14|
|FI|CS3-6D1F67F038BB4A54B23FB59DFB17A8F4|CORPORATE_VISA|First Card Visa|5430 **** **** 2231|14|
|FI|CS3-7C7F4B6D5E204BFDB5B185F0FC3443E9|CORPORATE_VISA|First Card Visa|5430 **** **** 9453|14|
|FI|CS3-2B3C04B3A4E64B488F6C2C048A6F82BE|CORPORATE_VISA|First Card Visa|5430 **** **** 6765|1|
|FI|CS3-E2B12DAE70A3407CA8C99136D56091E9|CORPORATE_VISA|First Card Visa|5430 **** **** 8371|10|
|FI|CS3-C2A5C660AF1C4EB3AC9E447DFDBBE8C7|CORPORATE_VISA|First Card Visa|5225 **** **** 0734|20|
|FI|CS3-B141EDF1046F4FEEB5447E9C93DA8514|CORPORATE_VISA|First Card Visa|5430 **** **** 4176|25|
|FI|CS3-81A30A4F67DF43D1927924BF9774ACC4|CORPORATE_VISA|First Card Visa|5521 **** **** 3409|30|
|DK|CS3-4A761E0DC8474CC8981180CA251FF7D4|EXECUTIVE|First Card Executive|5520 **** **** 7227|25|
|DK|CS3-A62DE47245244BD3B3693C42AB273DC0|EXECUTIVE|First Card Executive|5451 **** **** 9591|4|
|DK|CS3-B8E11080E50844C08B254D5FE2B99887|EXECUTIVE|First Card Executive|5451 **** **** 8745|4|
|DK|CS3-11FF5C257BBE4F0D83F08C728f971963|CORPORATE|First Card Corporate|5209 **** **** 8777|17|
|DK|CS3-24092D1E926046D49217F25651081008|PRIVATE|First Card Private|5209 **** **** 8788|17|
|NO|CS3-0A797FA1368B4979A9E27FAEBB2445C6|PURCHASING|First Card Purchasing|5218 **** **** 0580|25|
|NO|CS3-D927C5CCE79043A7A249842663B6F5F8|PURCHASING|First Card Purchasing|5218 **** **** 7468|4|
|NO|CS3-77BACC3315B049BB9FF85A0BA47B9F05|PURCHASING|First Card Purchasing|5218 **** **** 9964|4|
|NO|CS3-2C8CD5D46FA34625BA74EC6471FC6161|PRIVATE|First Card Private|5218 **** **** 7381|17|
|NO|CS3-5DB1D3642F0540BBB239438801DCD0BF|PRIVATE|First Card Private|5218 **** **** 7279|17|
|SE|CS3-4A761E0DC8474CC8981180CA251FF7D4|EXECUTIVE|First Card Executive|5520 **** **** 7227|25|
|SE|CS3-A62DE47245244BD3B3693C42AB273DC0|EXECUTIVE|First Card Executive|5451 **** **** 9591|4|
|SE|CS3-B8E11080E50844C08B254D5FE2B99887|EXECUTIVE|First Card Executive|5451 **** **** 8745|4|
|SE|CS3-11FF5C257BBE4F0D83F08C728f971963|CORPORATE|First Card Corporate|5209 **** **** 8777|17|
|SE|CS3-24092D1E926046D49217F25651081008|PRIVATE|First Card Private|5209 **** **** 8788|17|

Going though the sandbox workflow, access authorization is automatically applied to the respective country-relevant subset of the above cards.

#### Sandbox transactions
Querying the transactions on a card would generate a new transaction on the card roughly on every fifth call to the operation. In other words, there are 20% chance that a new transaction would be generated on the card on every call to retrieve that card’s transactions.

To better simulate production behavior where transactions become inaccessible after a certain cut-off period, sandbox is only going to serve transactions from the last month. A month is defined as the period from the same date of the previous month up to the present moment.