API Version 6 (EN)

This article describes the new features and changes in API version 6 compared to API version 5

A new version is introduced if the downward compatibility of the API is compromised by a change. Please check whether the changes affect your system before switching to this API version and make the necessary adjustments.

Goals

With the publication of API version 6 we have deliberately decided to make far-reaching structural changes. This version contains significantly more adjustments than a standard API version change. Instead of spreading incremental changes over many smaller updates, we have taken the opportunity to bring together as many innovations as possible in a single major step.

Our aim was to make the API more scalable, more efficient and more future-proof. As our platform continues to grow, the demands on our infrastructure and the expectations of our users are also increasing. To meet these challenges, we have implemented central functions that improve performance, reliability and flexibility.

We only publish new API versions when we consider it absolutely necessary. In doing so, we aim to bundle as many changes as possible in one such step. This way, we ensure that our customers are not burdened by frequent migration efforts and that an API version can be used over a long period of time without becoming outdated.

Important innovations

1. Paging: To shorten response times and optimize data transfer, we are introducing paging in our API. Instead of returning all data at once, API version 6 delivers the information in smaller, manageable packets of 100 entries per page. This allows for more efficient data processing on both the server and client side, resulting in faster load times and improved overall performance. Further information on this can be found in the section on Paging.

2. Rate Limiting: To ensure fair and reliable use for all users, we are introducing a rate limiting system. This system protects our infrastructure from overload and at the same time ensures that all users can benefit from consistent performance. You can find more information on this in the section on Rate limiting.

3. Focus on JSON: As of API version 6, we no longer support XML (application/xml, text/xml). In the future, our API will process and deliver data exclusively in JSON format (application/json). This decision was made because JSON has established itself as the standard for REST APIs and the focus on a standardized format enables more efficient maintenance and faster further developments. Further information on this can be found in the section on Data formats.

Why these changes are important

Our aim with version 6 is to develop an API that can be scaled seamlessly while both data volume and user throughput increase. These improvements ensure that the API provides a reliable, fast and efficient service even as data volumes and user activity increase. By aligning our API with industry principles we offer developers a consistent and stable basis for future developments.

In summary, API version 6 is a step towards a more robust platform that meets the changing needs of our users and can handle larger data volumes and increased traffic without compromising performance. We are convinced that these changes will not only improve the current user experience, but also set the course for further growth and success in the future.

All changes at a glance

General changes

Paging

With the new version of our API, paging for all API endpoints has been introduced. We now return a list of elements to make querying large amounts of data more efficient. By default, when a request is made, 100 entries per page are returned, whereby this number is determined by the parameter pageSize and can be increased to up to 1000 entries. The parameter pageNumber can be used to specify which page of the results is to be retrieved. The returned content is now provided in a wrapper element, whereby the actual data is stored in the results. The wrapper element itself provides additional information such as the number of entries per page, the current page, the total number of pages and the total number of all elements across all pages. The following example shows the structure of the new paging response:

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalItems": 2,
  "links": [
    {
      "href": "https://portal.konfipay.de/api/v6/Example?pageNumber=1&pageSize=100",
      "rel": "self",
      "method": "GET"
    }
  ],
  "results": [
    . . .
  ]

Previously, lists were returned in a nested structure and were contained in a parent element.

Example (superordinate element: documentItems)

{
  "documentItems": [
    {
      "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
      "href": "api/v5.0/Document/Camt/5d12c087-be1e-456c-a33f-4f8750fa7814",
      "timestamp": "2025-02-27T09:33:43+01:00",
      "iban": "DE12345678901234567890",
      "isNew": true,
      "format": "camt.053",
      "fileName": "2025-02-26_C53_DE12345678901234567890_EUR_21-00001.xml"
    },
    {
      "rId": "fa727310-3072-4abc-a982-b511b8b81108",
      "href": "api/v5.0/Document/Camt/fa727310-3072-4abc-a982-b511b8b81108",
      "timestamp": "2025-02-27T10:45:56+01:00",
      "iban": "DE12345678901234567890",
      "isNew": true,
      "format": "camt.053",
      "fileName": "2025-02-27_C53_DE12345678901234567890_EUR_21-00002.xml"
    }
  ]
}

With the introduction of paging, this additional level is removed. In this case, lists are created directly in the results element. This change applies to all places in the API.

Rate limiting

To ensure a balanced distribution of resources, we have implemented standard rate limiting values in our API:

• Public endpoints (e.g. authentication): 100 requests per minute

• Authenticated endpoints: 1000 requests per minute

These limits prevent resource overload and ensure stable API performance. If your requirements exceed these standard limits, we offer you the option of increasing the rate limits individually on request. Please send a corresponding request to support@konfipay.de.

Based on current API usage, we are already raising some customers to higher limits at the time of the update to ensure uninterrupted use.

Important: This adjustment applies API-wide and affects not only API version 6, but all versions of the API. The introduction of rate limiting coincides with the release of API version 6, but is independent of the API version used.

If a limit is exceeded, the server responds with the HTTP status code 429 - Too Many Requestswhich means that the maximum number of requests per minute has been reached. The client can make requests again after one minute at the latest, as the API requests are measured per minute.

Data formats

As of API version 6, our API only supports JSON (application/json). The previous XML formats (application/xml, text/xml) are no longer supported from this version onwards - neither for requests nor for responses.

The decision to no longer support XML is based on a trade-off between development effort and actual usage. JSON has established itself as the standard format for REST APIs and is preferred by most modern applications. This focus allows us to use our resources specifically for the further development and optimization of the API.

If your application previously used XML, you will need to switch to JSON. This affects both the requests sent and the processing of API responses.

Renaming field names and elements

In this API version, some field names have been adapted to improve readability and comprehensibility. The word "Item" for example, has been removed from all field names and elements as it is redundant and does not add any additional meaning. The changes relate exclusively to the names of the fields or elements, without changing the underlying structure or data formats.

Example of changes to elements:

• relatedPaymentItems ➡️relatedPayments

• errorItems ➡️ errors

• paymentInfoItems ➡️ paymentInfos

In addition, all occurrences of paymentStatusItem and documentStatusItem through the uniform element status has been replaced. To avoid naming conflicts, the original status Field in statusValuerenamed.

Example API version 5:

{
  "status": "KON_REJECTED",
  "uploadTimestamp": "2025-01-08T13:55:50+01:00",
  "orderID": "A1BC",
  "reasonCode": "TD02",
  "reason": "The file cannot be read (unknown format)",
  "additionalInformation": "Additional information 1",
  "errorItem": {
    "errorCode": "ERR-00-0000",
    "errorMessage": "ErrorMessage1",
    "errorDetails": "ErrorDetails1",
    "timestamp": "2025-01-08T13:55:50+01:00"
  }

Example API version 6:

{
  "statusValue": "KON_REJECTED",
  "uploadTimestamp": "2025-01-08T13:55:50+01:00",
  "orderID": "A1BC",
  "reasonCode": "TD02",
  "reason": "The file cannot be read (unknown format)",
  "additionalInformation": "Additional information 1",
  "error": {
    "errorCode": "ERR-00-0000",
    "errorMessage": "ErrorMessage1",
    "errorDetails": "ErrorDetails1",
    "timestamp": "2025-01-08T13:55:50+01:00"
  }

API endpoints: Standardization & restructuring

With the introduction of API version 6, we have made various adjustments to the endpoints to improve the structure and readability of the API. The changes are based on general REST API standards and improve the uniformity and consistency of the API.

1. Removal of the "item" suffix

In previous API versions, the addition "item" is used (e.g. paymentItem). To make the API clearer and more uniform, we have removed this addition. Individual resources are now clearly recognizable by their name.

Example:

• Before: api/v5/Document/Camt/{rid}/item

• Now: api/v6/transaction-files/{rid}

This change ensures a leaner and more intuitive API without superfluous terms in the URLs.

2. Pluralization of resources

In order to better comply with the general REST standards, all resources have been pluralized. A resource represents a collection of objects, which is why we now use plural forms for resource names throughout.

Example:

• Before: api/v5/payment

• Now: api/v6/payments

This change improves the consistency and ensures uniform naming within the API.

3. Uniform lowercase letters & hyphens in URLs

We have all end points in lower case and hyphens (-) have been introduced as a separator to improve readability.

Example:

• Before: api/v5/ExchangeRates

• Now: api/v6/exchange-rates

These changes are in line with modern REST API best practices and ensure a easier handling especially for developers who work with different APIs.

Standardization of query parameters

In the course of standardizing the URLs, the query parameters were also adapted accordingly. These adjustments include the consistent use of lowercase letters and the use of hyphens in the query parameters.

Example:

• Before: api/v5/PayPal/Transaction/{rId}?forceUpdate=true

• Now: api/v6/paypal/transactions/{rid}?force-update=true

The consistent application of these rules improves the readability of API requests and promotes a clean, easy-to-understand API structure.

In addition, frequently used query parameters have been standardized across different endpoints. This change mainly affects the retrieval of historical data. Instead of the previous parameters start and end must now min-date and max-date can be specified. The consistent use of standardized terms throughout the API simplifies working with different endpoints. In addition, the terms min-date and max-date are more precise and clearly define the limits of a date range.

Change to the acknowledgement logic from API version 6

Up to API version 5, a status was automatically set each time data was retrieved (e.g. PayPal transactions, account transactions), which marked the respective data record as "retrieved". In addition, API endpoints existed that only returned data records that had not yet been marked as retrieved. This meant that clients did not have to keep track of which records had already been processed - this information was stored directly in konfipay.

In addition, it was possible to deactivate automatic acknowledgement by setting the optional parameter ack=false. In this case, acknowledgement could take place via a separate API endpoint. The problem here was that in the standard case, the acknowledgement happened automatically with the API call. If an error occurred on the client side during processing, the data record in konfipay was nevertheless marked as retrieved - regardless of whether it has been successfully processed or not.

From API version 6 the acknowledgement is no longer set automatically with an API call. The new standard procedure requires two-stage processing:

1. Retrieval of the data record: The data record remains marked as not retrieved.

2. Explicit acknowledgement: A separate API request for acknowledgement must be made after successful processing.

This change represents a fundamental adjustment of the existing workflow. If this is not taken into account during the change to API version 6, all data records remain marked as not retrieved and are returned with every query.

Clients must therefore ensure that they explicitly perform the acknowledgement after successful processing of a data record in order to ensure correct status management in konfipay.

Filter and search

Until the API version 5 the API was structured in such a way that there were always two separate endpoints for retrieving data (e.g. PayPal transactions or account transaction files):

• Retrieval of new data: Only returns data records that have not yet been marked as retrieved.

• Retrieval of historical data: Enables the retrieval of all data records within a specified time period (e.g. 01.01.2023 - 01.01.2024), regardless of the acknowledgement status.

With API version 6 this separation has been abolished. Instead, there is now a single API endpoint for retrieving data in list form, which can be controlled via flexible Filter parameters.

The previous filters for "new" data records or for the historical retrieval by period must (or can, as they are optional) now be explicitly marked as filter parameters. This also makes new combinations possible, e.g:

• Retrieval of all new transactions within a certain period of time

• Retrieval of all transactions already acknowledged in a defined time period

This change offers more flexibility and allows clients to continue to emulate the previous behavior of the API by using the filter parameters accordingly.

In this context, a number of new options for filtering and searching have generally been added. These parameters include (among others):

• Amounts (minimum amount / maximum amount)

• Account details (name, Iban, account holder)

• Banking information (purpose of use, customer reference, payment type)

A complete list of the respective parameters can be found in the API documentation.

In particular, it is possible to combine several parameters with each other. When combining parameters, however, it should be noted that they may be mutually exclusive. In this case, the query will not produce a result (204 - No Content).

Changes to existing API endpoints

Authentication

Mandatory specification of the client

In the new API version, the element clientwhich contains information about the name and version of the client software sending the authentication request, is now mandatory.

This element was previously optional. The mandatory specification of this information makes it possible to provide better support with problems or API integrations. In addition to identifying version-specific errors more quickly, we can also use this information to analyze general trends, usage patterns or problems with the various client versions. This helps us to optimize new features specifically for the most frequently used versions. It also allows better documentation of versions and compatibilities, which can significantly simplify future migration processes for customers.

Example of an authentication request:

{
  "apiKey": "JGtjzzFfDoU5UWFl14yalcpj2pwtd0kXHGfBDDBELMPbwcqLyRKBeuiYZ7BxTHi5",
  "client": {
    "name": "ClientApplicationName",
    "version": "1.0.0.0"
  }
}

End of support for cookie authentication

As part of the modernization of our API, we have decided to remove support for cookie authentication. This decision is based on increased security requirements, as cookies are vulnerable to attacks such as cross-site scripting (XSS) and cross-site request forgery (CSRF). Instead, we rely on the more secure and flexible bearer token authentication, which has established itself as a modern standard in practice. Bearer tokens not only offer better protection, but are also independent of the browser environment and thus enable broader applicability in modern applications such as mobile apps or server-side services.

Restructuring of the API endpoints

Due to the no longer supported cookie authentication from API version 6 (Auth/Login), the API endpoints for authentication have been restructured. The previous endpoints under Auth/* have been replaced by a new, clearer and more consistent naming convention that is more closely aligned with RESTful principles.

Adaptation of the scopes

Due to the adjustment of the API endpoints, the introduction of new endpoints and the removal of endpoints that are no longer required, the API scopes were updated.

Special features:

• When creating a new API key via API version 5 or older:

  • The scope "PaymentStatus" is discarded and translated into "Payments".

  • The "Document" scope is automatically divided into "Documents" and "Transactions".

• When retrieving scopes for existing API keys:

  • For API versions ≤ 5, the API continues to return the old scope names.

  • From version 6, only the new scopes are used.

Bank accounts

New field: Currency

In API version 6, the functionality for creating and updating bank accounts will be extended so that the currency can be specified as an additional parameter in the future. This extension facilitates the implementation of "multi-currency functionalities" and ensures a clear definition and assignment during account creation or updating.

Asynchronous deletion of bank accounts

In previous API versions, bank accounts could be deleted synchronously. Due to the increasing dependencies in the system, the growing data volumes and the resulting longer waiting times and higher system load, the process has been optimized so that bank accounts are now deleted asynchronously. This change increases scalability, reduces timeouts and ensures better system stability and an optimized user experience. After successful initiation of the deletion process, the API endpoint returns a tracking identifier of the process along with the initial status.

Example answer:

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "statusCode": 1,
  "statusName": "Scheduled",
  "details": "Additional information 1",
  "operationStatusUrl": "https://portal.konfipay.de/api/v6.0/delete/status/5d12c087-be1e-456c-a33f-4f8750fa7814",
  "operationStatusMethod": "GET"
}

Status query of the deletion process

Due to the introduction of the asynchronous deletion process, a new API endpoint is also provided, which makes it possible to check the current status of a pending deletion of a bank account. This endpoint provides status information on whether the deletion is being processed, completed or whether an error has occurred.

Example answer:

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "statusCode": 3,
  "statusName": "Finished",
  "details": "Additional information 1"
}

Further information on this new API interface can be found in the API documentation.

Activating/deactivating bank accounts

In this API version, it is possible to activate or deactivate bank accounts when creating or updating them. If a bank account is to be activated, the field isActive must be set to true. If the field is set to false, the bank account is deactivated.

Inactive bank accounts are not taken into account in any automatic processes (e.g. when retrieving account transactions). No payment orders can be created or submitted for inactive accounts.

Documents and transactions

New endpoints

With API version 6, two new API endpoints were introduced to ensure a clear separation between banking files and the extracted transaction data (= bookings):

• Transactions API: Enables the direct retrieval of bookings in structured form as JSON. This eliminates the need to evaluate account transaction files yourself.

• Transaction Files API: Provides access to the original account transaction files (e.g. camt.053) and earmarked items if required.

Previously, when using the Documents API, it was necessary to retrieve and manually evaluate account transaction files. The new Transactions API takes over this step by konfipay extracting the contained transactions and saving them directly as well as providing them as JSON. This means that you no longer need to process your own banking files.

The Transaction Files API assumes the function of the Documents API for account transaction files and memo items and replaces them in this area. Other banking documents remain available via the Documents API available.

In addition, the previous separation of the end points for MT94X and camt has been discontinued. Both formats are now available via the Transaction Files API. If necessary, the format distinction can be made using the Filter parameters in the Transaction Files API.

Acknowledgenebt of account transaction data

In order to minimize the potentially large amount of account transaction data and the associated high number of API requests, this API version does not require a separate acknowledgement per transaction for the time being.

Instead, this version provides the option of adding an acknowledgement to complete lists of retrieved results.

To do this, when retrieving account transaction data from the list of account transactions (transactions) one temporary ID (acknowledgementID) is assigned. This ID remains valid for one hour or is deleted after confirmation. The ID summarizes the account transactions that were grouped on one page of the query and can be used to confirm the transactions on this page. In this case, the status of the transactions changes from isNew=true to isNew=false.

Example:

{
  "pageNumber": 1,
  "pageSize": 1000,
  "totalPages": 1,
  "totalItems": 2,
  "links": [
    {
      "href": "https://portal.konfipay.de/api/v6/Example?pageNumber=1&pageSize=1000",
      "rel": "self",
      "method": "GET"
    }
  ],
  "results": {
    "acknowledgementId": "a231fcd1-4fef-4f38-8f49-5ea4e7bfd47f",
    "transactions": [
      {
        "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
        "timestamp": "2025-02-18T08:53:51+01:00",
        "amount": 10.99,
        "currency": "EUR",
        "creditDebitIndicator": "CRDT",
        "electronicSequenceNumber": "74",
        "name": "Alice Mayer",
        "iban": "DE12345678901234567890",
        "bic": "ABCDEFG1CBA",
        "bookingText": "SAMMELÜBERWEISUNG",
        "bookingDate": "2025-02-18T10:06:04+01:00",
        "valueDate": "2025-02-18T10:06:04+01:00",
        "isNew": false,
        "bankReference": "bankRefernceNumber",
        "paymentIdentificationId": "konfipay-1-11111",
        "primaNota": "9301",
        "document": {
          "rId": "b32e7cd2-d9d4-44d4-878e-18a5c971c97b",
          "timestamp": "2025-02-18",
          "isNew": true,
          "format": "camt.052"
        },
        "bankAccount": {
          "rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
          "iban": "DE09876543210987654321",
          "currency": "EUR"
        }
      },
      {
        "rId": "fa727310-3072-4abc-a982-b511b8b81108",
        "timestamp": "2025-02-18T08:53:51+01:00",
        "amount": 500,
        "currency": "EUR",
        "creditDebitIndicator": "DBIT",
        "electronicSequenceNumber": "82",
        "name": "Alice Mayer",
        "iban": "DE12345678901234567890",
        "bic": "ABCDEFG1CBA",
        "bookingText": "GUTSCHRIFT ÜBERWEISUNG",
        "bookingDate": "2025-02-18T10:06:04+01:00",
        "valueDate": "2025-02-18T10:06:04+01:00",
        "isNew": true,
        "bankReference": "bankRefernceNumber",
        "paymentIdentificationId": "konfipay-1-11112",
        "primaNota": "9301",
        "document": {
          "rId": "a231fcd1-4fef-4f38-8f49-5ea4e7bfd47f",
          "timestamp": "2025-02-18",
          "isNew": true,
          "format": "camt.053"
        },
        "bankAccount": {
          "rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
          "iban": "DE09876543210987654321",
          "currency": "EUR"
        }
      }
    ]
  }
}

New fields: Statement number and electronic statement number for Camt and MT940

Two new fields have been added to the response when retrieving banking account transaction documents (camt and MT94X): the Statement number (legalSequenceNumber) and the Electronic statement number (electronicSequenceNumber). Both fields are optional and reflect the information contained in the documents provided by the respective bank.

New element: Information about the account holder for Camt and MT940

In the older API versions, the IBAN could be used to retrieve account transaction documents. However, as the IBAN is no longer unique, the transactions from two different accounts may be delivered when retrieved. For this reason, this API version adds a new element to the response from banking account transaction documents (camt and MT940): the information about the underlying bank account (bankAccount). This new element includes important information such as RID, IBAN and currency (currency) of the bank account. It ensures a more transparent and accurate allocation to an existing bank account, even when using different currencies.

Example:

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "href": "api/v6.0/transaction-files/5d12c087-be1e-456c-a33f-4f8750fa7814",
  "timestamp": "2025-02-26T11:14:25+01:00",
  "isNew": false,
  "format": "camt.053",
  "fileName": "2025-02-25_C53_DE12345678901234567890_EUR_21-00001.xml",
  "electronicSequenceNumber": 1,
  "legalSequenceNumber": 1,
  "bankAccount": {
    "rId": "b32e7cd2-d9d4-44d4-878e-18a5c971c97b",
    "iban": "DE12345678901234567890",
    "currency": "EUR"
  }
}

Payments and payment files

Retrieval of the payment overview

API version 6 introduces an extension in the payment area that enables a list of existing payment files. Various parameters can be used in the query to filter the results list according to different criteria. For example, payments can be filtered by payment type (purpose), payment type (payment-type) (e.g. transfers, direct debits, etc.), payment status (status), creation date (min-date/max-date) or execution date (min-execution-date/max-execution-date) filter. Further information on this new API interface can be found in the API documentation.

Summarizing the API endpoints of payments

The restructuring of the endpoints for payments includes the consolidation of various API interfaces for the transmission and retrieval of payment files. The following endpoints have been combined:

By default, konfipay automatically recognizes the format of submitted payment orders. Automatic recognition can be deactivated via the scope parameter.

Submission without transfer

With this API version, the option has been added to not immediately transfer payment files to the bank when importing them into konfipay, but to initially only save them in the system. A new API endpoint has been introduced to enable this flexible processing: POST /api/v6/payment-files/{rid}/submit.

This endpoint enables the manual transfer of a previously created payment file to the bank server. If a file has already been transmitted, it will not be transmitted again. However, a retransmission can be forced by setting the query parameter force=true.

Resending payment files that have already been sent is only recommended if they have been rejected by the bank. In such cases, the force parameter allows to try again without having to create a new payment file.

Further information on this new API interface can be found in the API documentation.

Extract individual payments from payment files into the open orders

API version 6 offers the option of transferring payment orders from a payment file directly to the open orders without transferring a file to the bank or saving the payment file ( POST/api/v6/payment-files/extract). Once the payments have been extracted from the payment file, they can be processed and combined into new payment files. In addition, the jointly imported orders are provided with a unique batch RID to ensure that they can also be subsequently assigned to the original payment file.

Example answer:

[
  {
    "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
    "timestamp": "2025-02-18T08:53:48+01:00",
    "batch": {
      "rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
      "numberOfElements": 2
    },
    ...
  },
  {
    "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
    "timestamp": "2025-02-18T08:53:48+01:00",
    "batch": {
      "rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
      "numberOfElements": 2
    },
    ...
  }
]

Submission of payment orders as (formerly "ccft")

In API version 6, the previous endpoint /api/v5/Payment/Custom/Windata/Ccft has been replaced by /api/v6/payments. At the same time, the workflow for transferring payments to the bank has been revised.

Previously, submitted payments were converted directly into SEPA files and sent directly to the bank. From API version 6, this now takes place in two separate steps:

1. Submit payments:

   • Payments are made via POST /api/v6/payments and initially saved in the system.

   • Payments can still be processed via the API or the web portal before they are transferred.

2. Manual transfer to the bank:

   • Using the new API endpoint POST /api/v6/payments/submit selected payments can be transmitted to the bank based on their RID.

   • konfipay automatically creates the required SEPA pain files and transfers them.

This change allows more flexibility and prevents payments from being transferred immediately after submission before they have been finally checked or processed.

If the creation of the payment file is not successful during the transfer, the process is canceled and the payments remain as Pendingin the payment orders. If the payment file is created successfully, the payments are assigned to this file and cannot be edited or deleted - regardless of whether the file transfer is successful or not. In this case, the status of the payments changes from Open to Pending.

Further information on this new API interface can be found in the API documentation.

Request example:

{
  "batchBooking": true,
  "paymentRids": [
    "5d12c087-be1e-456c-a33f-4f8750fa7814",
    "fa727310-3072-4abc-a982-b511b8b81108"
  ],
  "failOnSubmittedPayments": false
}

Retrieval of payment orders

This API version introduces the functionality to process payment orders using the optional batch RID (batch-rid) or their status (status). When querying the payment orders, a list of orders is returned that were either imported in a batch or have a certain status (Processed/Pending). If no filter parameter is specified, the complete list of all payment orders is returned. A payment order is considered open if neither a payment file has been created nor a file transfer to the bank has been carried out.

Retrieving payments

The new API interface GET /api/v6/payments/{rid} enables the retrieval of payment information. This endpoint provides both batch data (batch) as well as detailed information on payment (transaction). In addition, the account details of the client (initPartyBankAccount) and the recipient (otherPartyBankAccount) can be viewed. If a payment file exists, this is also available (paymentFile).

A comprehensive description of the elements and fields included is available in the associated API documentation.

Example:

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "timestamp": "2025-02-18T08:53:48+01:00",
  "batch": {
    "rId": "522743d3-778c-4f2f-9f0b-3133c671f4a2",
    "numberOfElements": 5
  },
  "transaction": {
    "type": "TRF",
    "amount": 10055,
    "currency": "EUR",
    "country": "DE",
    "executionDate": "2025-02-17",
    "endToEndId": "NOTPROVIDED",
    "purposeCode": "SALA",
    "chargeBearer": "SLEV",
    "instrId": "ABC123456789",
    "rmtInfoUStrd": "Reference from the payer to the bank"
  },
  "initPartyBankAccount": {
    "rId": "fa727310-3072-4abc-a982-b511b8b81108",
    "iban": "DE12345678901234567890",
    "description": "Alice Mayer"
  },
  "otherPartyBankAccount": {
    "rId": "b32e7cd2-d9d4-44d4-878e-18a5c971c97b",
    "iban": "DE09876543210987654321",
    "description": "Bob Mayer"
  },
  "paymentFile": {
    "rId": "a231fcd1-4fef-4f38-8f49-5ea4e7bfd47f",
    "timestamp": "2025-02-18T08:53:48+01:00",
    "format": "pain.001",
    "executionDate": "2025-02-18",
    "paymentType": "CBTRF",
    "status": {
      "statusValue": "FIN_CONFIRMED",
      "uploadTimestamp": "2025-02-18T10:06:01+01:00",
      "orderID": "A1BC",
      "reasonCode": "TS01",
      "reason": "The transfer of the file was successful",
      "additionalInformation": "Additional information 1"
    }
  }
}

Deleting payments

The new API endpoint DELETE /api/v6/payments/{rid} allows you to delete payments. Only payments that have not been processed can be deleted. Once a payment has been processed and converted into a SEPA file, deletion is no longer possible.

Exact specification of the formats

In the previous API versions, only the general format such as "pain" or "container" was returned for the payment files. From API version 6, the specific format, such as "pain.001" or "pain.008", is transmitted in the response.

Response up to API version 5:

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "timestamp": "2024-10-18T13:30:48+02:00",
  "type": "pain",
  "paymentStatusItem": {
    "status": "FIN_CONFIRMED",
    "uploadTimestamp": "2024-10-18T14:43:01+02:00",
    "orderID": "A1BC",
    "reasonCode": "TS01",
    "reason": "The transfer of the file was successful",
    "additionalInformation": "Additional information 1"
  }
}

Response from API version 6:

{
  "paymentInfo": {
    "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
    "timestamp": "2025-01-09T14:36:50+01:00",
    "format": "pain.001",
    "executionDate": "2025-01-09",
    "paymentType": "TRF",
    "status": {
      "statusValue": "FIN_CONFIRMED",
      "uploadTimestamp": "2025-01-09T15:49:03+01:00",
      "orderID": "A1BC",
      "reasonCode": "TS01",
      "reason": "The transfer of the file was successful",
      "additionalInformation": "Additional information 1"
    }
  }
}

Rejection of files with multiple SEPA batch bookings

As of API version 6, the submission of files containing more than one SEPA batch booking (Element: <PmtInf>) is no longer permitted. This adjustment serves to ensure consistent and reliable processing across all testing, display and processing steps.

PayPal

Support for sandbox accounts

In this API version, the use of PayPal sandbox accounts is possible. Via the field isSandbox you can specify whether the PayPal account is operated in the sandbox environment when creating or updating it. By default, this value is set to false. If the value is set to true, the account can be used flexibly for testing and development purposes.

Example request:

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "description": "Description1",
  "clientId": "Adsf-sdffgghghjhklkj_xOFZDwIjP-qeryuioplkjhgfdcvbnu2SfHM0_mnbvcx",
  "clientSecret": "akcvkfriooi$^&dfd=dsfdsf=-dsfsdljllerejjlgl;r",
  "isActive": true,
  "startFetchDate": "2025-01-18T08:53:51+01:00",
  "isSandbox": false
}

Example answer:

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "description": "Description1",
  "clientId": "Ysnf-tQW8usdfsdfsdf_xOFZDwIjP-qsfsdfdfreerkuyiu2SfHM0_ghjghjghD",
  "isActive": true,
  "timestamp": "2025-02-18T08:53:51+01:00",
  "startFetchDate": "2025-01-18T08:53:51+01:00",
  "payPalBalances": [
    ...
  ],
  "isSandbox": false
}

Dropped API endpoints

Up to API version 5, all payment formats were mapped via a separate API endpoint, so that the status of a payment could be called up centrally across all formats. The PaymentStatus API was provided up to API version 5 ( GET /api/{version}/PaymentStatus/{rid}). Combining the API endpoints for payments into a common endpoint (/api/{version}/payment-files) eliminates the need to provide a separate API endpoint. From API version 6, the status of a payment can be checked via the endpoint GET /api/v6/payment-files/{rid}.