Payment Collection API

Getting Started

Sandbox URLs

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

Collection Service API: https://sandbox-api.danskebank.com/sandbox-corporate/api/v1/collection-service

Production URLs

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

Collection Service API: https://api.danskebank.com/corporate/api/v1/collection-service

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 Collection Service API, it MUST contain the “payments” 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=payments'

Example Response:

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

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>

Supported Endpoints

For detailed information on the endpoint request and response structure, please refer to the API reference documentation (read more).

Webhooks Setup

To receive push notifications about both uploaded document statuses and newly received documents, you will need to configure a webhook.

Create an Endpoint

First, create an endpoint capable of processing POST HTTP requests. As requests use HTTPS, your server must have a valid TLS or SSL certificate configured and installed.

Ensure your endpoint:

• Handles POST requests with a JSON payload described in the Request Structure.

• Quickly returns 200 status code before executing any complex logic or long-lasting operation that could cause a timeout.

Security

A mutual TLS (mTLS) connection is required for enhanced security:

• Notification Sender (Danske Bank): Acts as the client, providing a client-side certificate that must be validated by the server.

• Notification Consumer (Customer): Acts as the server, supplying a server-side certificate to secure the connection.

Request Structure

Ensure your system can parse the JSON structure sent in the POST body:

{
   "id":"034cfa8b-4965-4ee0-8f91-82aed221627a",
   "content":{
      "documentId":"034cfa8b-4965-4ee0-8f91-82aed221627a",
      "ackDocumentId":null,
      "cancellationDocumentId":null,
      "code":"Processed",
      "text":"Forwarded to another bank",
      "date":"2025-01-01T18:50:03.403908"
   }
}

Response Structure

The webhook endpoint should respond with a 200 status code, which will indicate successful receipt of the notification and prevent any further attempts at delivery.

Other HTTP status codes are considered unsuccessful, and the push notification will be resent.

Register an Endpoint in Danske Bank

After setting up and testing your webhook endpoint, register it by contacting support.

Note: Currently, registration requires manual actions from our side, so direct self-service is not yet available.

Endpoint Format Example:

https://example.com/danske_bank_webhook

If you are using a non-standard HTTPS port, provide it like:

https://example.com:1245/danske_bank_webhook

Document Types and Statuses

Document Type

Sending Documents

When sending documents following document types are supported:

• FILL - Finvoice e-invoice

• FISL - Finvoice SenderInfo

• FIPL - Finvoice ReceiverProposal

• FINVOACK - Finvoice Acknowledgement

• FINVOATT - Finvoice Attachment

Receiving Documents

When receiving documents, following document types are supported:

• FILN - Finvoice e-invoice

• FIVN - Finvoice Acknowledgement

• FIATFI - Finvoice Attachment

• FIRN - Finvoice ReceiverInfo

Document Status

Overview

Below are the document statuses and their meanings:

• Accepted: Indicates the document has passed initial validations and is ready to be processed.

Example:

{
    "documentId": "d7a3e323-0f00-4333-b921-b9297cc97120",
    "ackDocumentId": null,
    "cancellationDocumentId": null,
    "text": "Accepted by Danske Bank",
    "code": "Accepted",
    "date": "2025-01-01T09:47:54.8506314"
}

• Processed: Indicates the document has been processed within Danske Bank or forwarded to a third party (operator, another bank).

Example:

{
    "documentId": "d7a3e323-0f00-4333-b921-b9297cc97120",
    "ackDocumentId": null,
    "cancellationDocumentId": null,
    "text": "Forwarded to another bank",
    "code": "Processed",
    "date": "2025-01-01T11:51:58.3158218"
}

• Rejected: Indicates the document has been rejected due to validation errors from the Collection Service or when acknowledgment was received from third parties. The payload will contain AckDocumentId. The acknowledgement can be downloaded using this identifier.

Example:

{
    "documentId": "d7a3e323-0f00-4333-b921-b9297cc97120",
    "ackDocumentId": "9d854ed7-304b-4d69-a4e0-a0552ca2711e",
    "cancellationDocumentId": null,
    "text": "Invalid sender e-invoice address",
    "code": "Rejected",
    "date": "2025-01-01T11:49:19.1504746"
}

• Cancelled: Indicates the document has been cancelled by the sender. The payload will contain CancellationDocumentId. The cancellation can be downloaded using this identifier.

Example:

{
    "documentId": "d7a3e323-0f00-4333-b921-b9297cc97120",
    "ackDocumentId": null,
    "cancellationDocumentId": "9dbced66-a552-4591-9a16-7a87b8554421",
    "text": "Document cancelled",
    "code": "Cancelled",
    "date": "2025-01-01T12:00:36.6551707"
}

• Received: Indicates a new document has been received. The payload will contain DocumentId. The document can be downloaded using this identifier.

Example:

{
    "documentId": "d7a3e323-0f00-4333-b921-b9297cc97120",
    "ackDocumentId": null,
    "cancellationDocumentId": null,
    "text": "New document received",
    "code": "Received",
    "date": "2025-01-01T12:00:36.6551707"
}

Sending Documents

When sending a document, you can specify NotificationStatuses. This determines which push notifications will be sent. It is recommended to include all statuses initially to avoid missing important notifications:

"NotificationStatuses": ["Accepted", "Processed", "Rejected", "Cancelled"]

Receiving Documents

During this scenario, no configuration is required. All incoming documents will be forwarded to you with the status Received, allowing you to download them later.

Potential Scenarios

Legend

Scenario: Processed Document

This common scenario occurs when a customer uploads a document which then gets processed.

Document statuses (example):

[
  {
    "text": "Forwarded directly to customer",
    "code": "Processed",
    "date": "2025-01-01T14:24:13.3744146"
  },
  {
    "text": "Accepted by Danske Bank",
    "code": "Accepted",
    "date": "2025-01-01T14:24:12.9330298"
  }
]

Scenario: Document Rejected by Danske Bank

This scenario occurs when a customer uploads a document, but it is rejected by Danske Bank due to schema or business validation errors.

Document statuses (example):

[
  {
    "text": "Invalid sender e-invoice address",
    "code": "Rejected",
    "date": "2025-01-01T11:49:19.1504746",
    "ackDocumentId": "89f393e8-481b-442b-8b36-6be133c46b03"
  }
]

Scenario: Document Rejected by Third-Party

In this scenario, a customer uploads a document which is processed by Danske Bank but later rejected by a third party (another bank or operator).

Document statuses (example):

[
  {
    "text": "Rejected by external party",
    "code": "Rejected",
    "date": "2025-01-01T12:33:50.3184301",
    "ackDocumentId": "c049c25d-0cce-4ca8-9d5d-eea4f365969b"
  },
  {
    "text": "Forwarded to another bank",
    "code": "Processed",
    "date": "2025-01-01T11:50:54.1718174"
  },
  {
    "text": "Accepted by Danske Bank",
    "code": "Accepted",
    "date": "2025-01-01T11:05:43.7047457"
  }
]

Scenario: Cancelled Document

In this scenario, a customer uploads a document and later sends cancellation which gets successfully processed cancelling original document.

Document statuses (example):

[
  {
    "text": "Document cancelled",
    "code": "Cancelled",
    "date": "2025-02-24T19:04:30.7910072",
    "cancellationDocumentId": "86fbda85-4c4c-4201-9afa-08b5af0666b5"
  },
  {
    "text": "Forwarded to another bank",
    "code": "Processed",
    "date": "2025-02-24T08:52:56.9449815"
  },
  {
    "text": "Accepted by Danske Bank",
    "code": "Accepted",
    "date": "2025-02-24T07:50:54.5651909"
  }
]

Cancellation statuses (example)

[
  {
    "text": "Forwarded to another bank",
    "code": "Processed",
    "date": "2025-02-24T19:04:30.7910072"
  },
  {
    "text": "Accepted by Danske Bank",
    "code": "Accepted",
    "date": "2025-02-24T13:30:57.8215244"
  }
]

Scenario: Document Restored as Processed

This scenario occurs when a customer uploads a document and later sends a cancellation, which is rejected.

Document statuses (example):

[
  {
    "text": "Restored as processed due to rejected cancellation",
    "code": "Processed",
    "date": "2025-02-24T12:39:09.0254548"
  },
  {
    "text": "Document cancelled",
    "code": "Cancelled",
    "date": "2025-02-24T12:00:36.6551707",
    "cancellationDocumentId": "d3a64a86-be56-4339-98b4-5ac3ab7b5af1"
  },
  {
    "text": "Forwarded to another bank",
    "code": "Processed",
    "date": "2025-02-21T11:51:58.3158218"
  },
  {
    "text": "Accepted by Danske Bank",
    "code": "Accepted",
    "date": "2025-02-21T09:47:54.8506314"
  }
]

Cancellation statuses (example):

[
  {
    "text": "Rejected by external party",
    "code": "Rejected",
    "date": "2025-01-01T12:39:09.79897",
    "ackDocumentId": "fd90ba7c-fb05-42d1-b2b5-c3a8b8df9420"
  },
  {
    "text": "Forwarded to another bank",
    "code": "Processed",
    "date": "2025-01-01T12:00:36.6551707"
  },
  {
    "text": "Accepted by Danske Bank",
    "code": "Accepted",
    "date": "2025-01-01T08:53:25.3539896"
  }
]

Scenario: New Document

This scenario describes when a customer receives a new document.

Document statuses (example):

[
  {
    "text": "New document received",
    "code": "Received",
    "date": "2025-01-01T11:49:19.1504746"
  }
]

Changelog

February 2025 - Initial release of the Collection Service API.

Endpoints:

• POST Upload Document: Uploads a new document into the system.

• GET Document Content: Retrieves content for a specific document.

• GET Document: Retrieves document metadata.

• GET Statuses: Retrieves all status entries for a document.

• GET Current Status: Retrieves the current status of a document.

Supported Document Types:

• FILL - Finvoice e-invoice

• FISL - Finvoice SenderInfo

• FIPL - Finvoice ReceiverProposal

• FINVOACK - Finvoice Acknowledgement

• FINVOATT - Finvoice Attachment

Webhook Support: Introduced real-time push notifications regarding document statuses.