Payment Initiation API

Introduction

The Premium Payment Initiation API provides you access to payment initiation from your Danske Bank corporate accounts. Ideal for any party who wants to integrate the creation of payments to any of their flows.

Markets

The API is being developed for all Danske Bank markets, but currently supports payments in these markets:

• Denmark
• Norway
• Finland
• Ireland
• Foreign transfers

Use cases and features

• Real-time payment creation - Create and process payments in real time.
• Supports instant payments - Supports instant payments in Denmark, Finland, Ireland and SEPA cross border.
• Integration to your own system - No need to login to the bank to create a payment, you can integrate this API in any of your applications.

Getting Started

External API Platform

To get started with the Premium Payment Initiation API, it is necessary to onboard to the Premium API Platform first. After onboarding to the platform, you will have access to all the Premium APIs that Danske Bank offers.

Link to External API Platform onboarding guidelines: Danske Bank Open Banking Developer Portal

Environment Description

As described in the API Platform onboarding guidelines, the Premium Payment Initiation API will be available in two environments:

• Sandbox: This environment will be used for initial integration tests and will provide mocked data. The mocked data includes three accounts. Each account will have transactions with either NOK, SEK or DKK currencies.

• Production will provide you access to create real payments.

Sandbox URLs

Token Endpoint: https://sandbox-api.danskebank.com/sandbox-corporate/api/dk/business/oauth2/token

Premium Payment Initiation endpoint: https://sandbox-api.danskebank.com/sandbox-corporate/api/v1/corporate-paymentorders

Premium Payment Status endpoint: https://sandbox-api.danskebank.com/sandbox-corporate/api/v1/corporate-paymentorders/{paymentorderid}/state

Production URLs

Token Endpoint: https://api.danskebank.com/corporate/api/dk/business/oauth2/token

Premium Payment Initiation endpoint: https://api.danskebank.com/corporate/api/v1/corporate-paymentorders

Premium Payment Status endpoint: https://api.danskebank.com/corporate/api/v1/corporate-paymentorders/{paymentorderid}/state

Authentication

To access a resource, the client must first request a Client Credentials Grant token by calling the token endpoint specified in the OpenId configuration (token_endpoint). The request should be an x-www-form-urlencoded POST with the following parameters:

• grant_type - client_credentials (read more).

• scope - should include a scope the client has access to; for the Account Transaction & Balance API, it MUST contain the “accounts” keyword (read more).

• client_id - the ID received after onboarding (read more).

Example Request:

curl --location --request POST 'https://example.com/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=1233456' \
--data-urlencode 'scope=accounts'

Example Response:

{
  "token_type":"Bearer",
  "access_token":"A****",
  "metadata":"m:",
  "expires_in":3600,
  "consented_on":1588933990,
  "scope":"accounts"
}

Using the Access Token:

The access_token received is valid for 1 hour and must be included in the request header on all subsequent API requests:

Authorization: Bearer <access_token>

Implementation details

The payment type needs to be part of the url when calling POST. The following payment products are supported:

• dk-domestic-credit-transfer
• no-domestic-credit-transfer
• fi-domestic-credit-transfer
• ie-domestic-credit-transfer
• cross-border-credit-transfer
• cross-border-cheque
• request-for-transfer
• (Request for transfer from an account in a foreign bank. It requires a “MT101-agreement” with the account holding bank and might be subject to additional fees)

Later the following will be implemented:

• se-domestic-credit-transfer
• uk-domestic-credit-transfer
• pl-domestic-credit-transfer

Each individual country has specific credit transfer types which is described in detail below.

Payload documentation Danish payment types

payment product:

• dk-domestic-credit-transfer

Payload documentation - Finnish payment types

payment product:

• fi-domestic-credit-transfer

Payload documentation - Foreign payment types

payment product:

• cross-border-credit-transfer
• cross-border-cheque
• request-for-transfer

Payload documentation - Irish payment types

payment product:

• ie-domestic-credit-transfer

Payload documentation - Norwegian payment types

payment product:

• no-domestic-credit-transfer

Responses

The immediate response received when initiating a payment of the Corporate Payment API will follow the structure below:

List of State codes used in the immediate response and in the response to the payment Status Endpoint (GET State)::

Error Codes

Our API uses standardized HTTP status codes to indicate the success or failure of API requests. Below is a summary of the error codes you may encounter

Code 201 - Created

Example Response:

{
  "stateCode": "pendingApproval",
  "transactionStatus": "PDNG",
  "paymentId": "urn:ttid:corporate:v1:cpr:43cc372a-ca6b-4f76-a33e-0bac4005e03a",
  "error": null,
  "secondaryPaymentId": "1021739698"

}

Code 400 - Bad request

Schema validation errors

This type of bad request happens if the caller of the APIpayment initiator is not providing a correct payload. These errors cannot be shown to the payment initiator since there is no errorKCode or errorIsoCode.

Example Response:

{
  "stateCode": "rejected",
  "transactionStatus": "RJCT",
  "paymentId": "",
  "error": {
    "errorKCode": "",
    "errorIsoCode": "",
    "errorText": "'Currency' must be equal to 'SEK'."
  }
}

In some cases the response structure can also be:

Example Response:

{
  "errorMessage": "creditTransferTransactionInformation.Amount.EquivalentAmount.Currency: [EquivalentAmount.Currency must be 3 characters in the range [A-Z].]",
  "errorCode": "ERROR"
}

Functional validation errors

Example of an immediate response with Danske Bank detailed error codes and error text.

Example Response:

{
  "stateCode": "rejected",
  "transactionStatus": "RJCT",
  "paymentId": "",
  "error": {
    "errorKCode": "K0589",
    "errorIsoCode": "DT04",
    "errorText": "Express payments can only be executed on today's date."
  }
}

Code 401 - Unauthorized

If tokens are not valid this will be returned:

Example Response:

{
  "error": "unauthorized"
}

Get Payment status

Endpoint: GET https://api.danskebank.com/corporate/api/v1/corporate-paymentorders/{paymentorderid}/state

Description

In order to get payment status information after receiving the immediate response of the Payment Initiation request, it is possible to get the real time status of a payment as it is in Danske Bank’s system. The unique paymentId received in the immediate response must be utilized to get the status of a payment.

Example : Immediate response after initiating the Payment:

{
  "stateCode": "pendingApproval",
  "transactionStatus": "PDNG",
  "paymentId": "urn:ttid:corporate:v1:cpr:43cc372a-ca6b-4f76-a33e-0bac4005e03a",
  "error": null,
  "secondaryPaymentId": "1021739698"
}

GET https://api.danskebank.com/corporate/api/v1/corporate-paymentorders/urn:ttid:corporate:v1:cpr:43cc372a-ca6b-4f76-a33e-0bac4005e03a/state

The response of the “GET state” will have the below structure:

Examples of responses from the GET State endpoint:

• Payment waiting for execution:

{
    "stateCode": "sentForExecution",
    "transactionStatus": "PDNG",
    "error": null
}

• Rejected payment inititation:

{
    "stateCode": "rejected",
    "transactionStatus": "RJCT",
    "error": {
        "errorKCode": "K0051",
        "errorIsoCode": "NARR",
        "errorText": "'To-account' cannot be credited"
    }
}