API Version 4 (EN)

Released: 24.07.2021

This article describes the new features and changes in API version 4 compared to API version 3.1.

A new major version is introduced when a change means that the backward compatibility of the API can no longer be ensured. Before switching to this API version, please check whether the changes have an impact on your system and make the necessary adjustments.

Specification of the UTC offset in date/time

The date and time values output by the konfipay API are in CEWT (Central European Winter Time) or CEST (Central European Summer Time). To enable an automatic conversion, date and time values from API version 4 contain the UTC offset. This represents the deviation from UTC time. In the following example, you can see that the date specification in the timestamp field receives the addition +02:00 with API version 4. This means that the specified date value is 2 hours ahead of UTC time. Converted to UTC time, the date would thus be 2021-07-15T15:54:27.

API-Version 3.1

API-Version 4

JSON

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "timestamp": "2021-07-15T17:54:27",
  "type": "pain",
  "paymentStatusItem": {
    "status": "KON_ACCEPTED_AND_QUEUED"
  }
}

JSON

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "timestamp": "2021-07-15T17:54:27+02:00",
  "type": "pain",
  "paymentStatusItem": {
    "status": "KON_ACCEPTED_AND_QUEUED"
  }
}

Date and time information of PayPal transactions also contain the UTC offset. In this case, however, the time zone depends on the country settings stored in PayPal for the respective PayPal account and thus may differ from the time zones used by konfipay (CEWT/CEST).

Correction of wrong namespaces for PayPal transactions

In API version 3.1, PayPal transactions were generated in XML format with the wrong namespace. This has been fixed with API version 4.

API-Version 3.1

API-Version 4

XML

<PayPalTransaction xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <RId>5d12c087-be1e-456c-a33f-4f8750fa7814</RId>
  <Timestamp>2021-07-15T18:02:28.341</Timestamp>
  <Details>
    <transaction_info>
      <paypal_account_id>TDZRPUF6Q6VL8</paypal_account_id>
      <transaction_id>transaction_id</transaction_id>
      <paypal_reference_id i:nil="true" />
      <paypal_reference_id_type i:nil="true" />
      <transaction_event_code>T0000</transaction_event_code>
      <transaction_type_description>General: received payment of a type not belonging to the other T00nn categories</transaction_type_description>
      <transaction_initiation_date>2020-05-05T14:02:05+0000</transaction_initiation_date>
      <transaction_updated_date i:nil="true" />
      <transaction_amount xmlns:d4p1="http://schemas.datacontract.org/2004/07/LibPayPalRestClient.Models.Transactions">
        <d4p1:currency_code>EUR</d4p1:currency_code>
        <d4p1:value>55</d4p1:value>
      </transaction_amount>
      <fee_amount xmlns:d4p1="http://schemas.datacontract.org/2004/07/LibPayPalRestClient.Models.Transactions" i:nil="true">
         <value>-13.79</value>
         <currency_code>EUR</currency_code>
      </fee_amount>
      ...
    </transaction_info>
  </Details>
</PayPalTransaction>

XML

<PayPalTransaction xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <RId>5d12c087-be1e-456c-a33f-4f8750fa7814</RId>
  <Timestamp>2021-07-15T17:54:28+02:00</Timestamp>
  <Details>
    <transaction_info>
      <paypal_account_id>TDZRPUF6Q6VL8</paypal_account_id>
      <transaction_id>transaction_id</transaction_id>
      <paypal_reference_id>Reference Id</paypal_reference_id>
      <paypal_reference_id_type>ODR</paypal_reference_id_type>
      <transaction_event_code>T0000</transaction_event_code>
      <transaction_type_description>General: received payment of a type not belonging to the other T00nn categories</transaction_type_description>
      <transaction_initiation_date>2020-05-05T14:02:05+0000</transaction_initiation_date>
      <transaction_updated_date>2014-07-11T04:03:52+0000</transaction_updated_date>
      <transaction_amount>
        <value>55</value>
        <currency_code>EUR</currency_code>
      </transaction_amount>
      <fee_amount>
        <value>-13.79</value>
        <currency_code>EUR</currency_code>
      </fee_amount>
      ...
    </transaction_info>
  </Details>
</PayPalTransaction>

File names for documents

The DocumentItem object is extended by the fileName field. The field contains the original file name. This varies with the source of the file:

Retrieval via EBICS/service data center: The file name is assigned by the bank data center.
Import via the portal: Name of the file at the time of upload.

Affected API endpoints:

Document - Camt
- /api/v4/Document/Camt
- /api/v4/Document/Camt/History
- /api/v4/Document/Camt/{rId}/Acknowledge
- /api/v4/Document/Camt/{rId}/Item
Document - Misc
- /api/v4/Document/Misc
- /api/v4/Document/Misc/History
- /api/v4/Document/Misc/{rId}/Acknowledge
- /api/v4/Document/Misc/{rId}/Item
Document - SWIFT MT
- /api/v4/Document/MT
- /api/v4/Document/MT/History
- /api/v4/Document/MT/{rId}/Acknowledge
- /api/v4/Document/MT/{rId}/Item

Example:

API-Version 3.1

API-Version 4

JSON

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "href": "api/v3.1/Document/Camt/5d12c087-be1e-456c-a33f-4f8750fa7814",
  "timestamp": "2021-07-19T20:04:29.451",
  "iban": "DE12345678901234567890",
  "isNew": true,
  "format": "camt.053"
}

JSON

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "href": "api/v4/Document/Camt/5d12c087-be1e-456c-a33f-4f8750fa7814",
  "timestamp": "2021-07-19T20:00:48+02:00",
  "iban": "DE12345678901234567890",
  "isNew": true,
  "format": "camt.053",
  "fileName": "2021-07-18_C53_DE12345678901234567890_EUR_21-00001.xml"
}

New status: FIN_CONFIRMED

Version 3.4.0 introduces the new FIN_CONFIRMED status for payment order files.

The retrieval and processing of bank-specific logs for the payment status in pain.002 format introduced with this version provides more detailed information on the status of a payment order file on the bank side. The logs are retrieved via the EBICS order types Z01, CRZ, CDZ, CIZ and XMF. In the previous process of processing payment orders, the FIN_ACCEPTED status was the last possible positive status of a payment order file. This is based on the feedback from the EBICS customer log (order type: HAC). The FIN_ACCEPTED status indicates that all steps relating to the EBICS procedure have been successfully completed, but this does not guarantee that the payment will be executed.

The new FIN_CONFIRMED status represents a clear, bank-side confirmation of the execution of the instructed payment orders. FIN_CONFIRMED thus replaces FIN_ACCEPTED as the final, positive status of a payment order file. For backward compatibility, the FIN_CONFIRMED status is returned as FIN_ACCEPTED status in API versions < 4.0.

The order types Z01, CRZ, CDZ and XML are optional and are not supported by every EBICS server. They must also be configured and released for the respective EBICS access by the bank. If these requirements are not met, FIN_ACCEPTED remains as the last possible positive status of a payment order file.

API-Version 3.1

API-Version 4

JSON

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "timestamp": "2021-07-21T15:35:20.662",
  "type": "pain",
  "paymentStatusItem": {
    "status": "FIN_ACCEPTED",
    "uploadTimestamp": "2021-07-21T16:47:33.662",
    "orderID": "A1BC",
    "reasonCode": "TS01",
    "reason": "The transfer of the file was successful",
    "additionalInformation": "Additional information 1"
  }
}

JSON

{
  "rId": "5d12c087-be1e-456c-a33f-4f8750fa7814",
  "timestamp": "2021-07-21T15:35:20.662",
  "type": "pain",
  "paymentStatusItem": {
    "status": "FIN_CONFIRMED",
    "uploadTimestamp": "2021-07-21T16:47:33.662",
    "orderID": "A1BC",
    "reasonCode": "TS01",
    "reason": "The transfer of the file was successful",
    "additionalInformation": "Additional information 1"
  }
}