API-Version 4

Veröffentlicht: 24.07.2021

Dieser Artikel beschreibt die Neuerungen und Änderungen der API-Version 4 im Vergleich zur API-Version 3.1. Die technische API-Dokumentation finden Sie hier.

Eine Einführung einer neuen Version erfolgt, wenn durch eine Änderung die Abwärtskompatibilität der API nicht mehr sichergestellt werden kann. Bitte prüfen Sie vor dem Wechsel auf diese API-Version ob die Änderungen Auswirkungen auf Ihr System haben und führen Sie die notwendigen Anpassungen durch.

Angabe des UTC offset in Datum/Uhrzeit

Die Angabe von der konfipay API ausgegebenen Datums- und Uhrzeitwerten erfolgt in CEWT (Central European Winter Time) bzw. CEST (Central European Summer Time). Um eine automatische Umrechnung zu ermöglichen, enthalten Datums- und Uhrzeitangaben ab API-Version 4 den UTC offset. Dieser repräsentiert die Abweichung zur UTC-Zeit. Im nachfolgenden Beispiel ist zu sehen, dass die Datumsangabe im Feld timestamp mit der API-Version 4 den Zusatz +02:00 erhält. Dies bedeutet, dass der angegebene Datumswert 2 Stunden vor der UTC Zeit liegt. In UTC-Zeit umgerechnet wäre das Datum somit 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"
  }
}

Datums- und Uhrzeitangaben von PayPal-Transaktionen enthalten ebenfalls den UTC offset. Die Zeitzone richtet sich in diesem Fall aber nach den in PayPal hinterlegten Ländereinstellungen für das jeweilige PayPal-Konto und weicht somit gegebenenfalls von den von konfipay verwendeten Zeitzonen (CEWT/CEST) ab.

Korrektur falscher Namespaces für PayPal-Transaktionen

In API-Version 3.1 wurden PayPal-Transaktionen im XML-Format mit dem falschen Namespace erzeugt. Dies wurde mit API-Version 4 behoben.

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>

Dateinamen für Dokumente

Das DocumentItem-Objekt wird um das Feld fileName erweitert. Dieses enthält den original Dateinamen. Dieser variiert je nach Quelle der Datei:

Abruf über EBICS/Servicerechenzentrum: Der Dateiname wird vom Bankrechenzentrum vergeben.
Import über das Portal: Bezeichnung der Datei zum Zeitpunkt des Uploads.

Betroffene API-Endpunkte:

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

Beispiel:

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"
}

Neuer Status: FIN_CONFIRMED

Mit Version 3.4.0 erfolgt die Einführung des neuen Status FIN_CONFIRMED für Zahlungsauftragsdateien.

Durch den mit dieser Version eingeführten Abruf und die Auswertung bankfachlicher Protokolle für den Zahlungsstatus im pain.002-Format stehen detailliertere Informationen zum bankseitigen Status einer Zahlungsauftragsdatei zur Verfügung. Der Abruf der Protokolle erfolgt über die EBICS-Auftragsarten Z01, CRZ, CDZ, CIZ und XMF. Im bisherigen Prozess der Verarbeitung von Zahlungsaufträgen war der Status FIN_ACCEPTED der letztmögliche, positive Status einer Zahlungsauftragsdatei. Dieser basiert auf der Rückmeldung aus dem EBICS-Kundenprotokoll (Auftragsart: HAC). Dem Status FIN_ACCEPTED kann entnommen werden, dass alle, das EBICS-Verfahren betreffenden Schritte erfolgreich abgeschlossen wurden, was aber noch kein Garant für die Ausführung der Zahlung ist.

Der neue Status FIN_CONFIRMED repräsentiert eine eindeutige, bankseitige Bestätigung zur Ausführung der angewiesenen Zahlungsaufträge. FIN_CONFIRMED löst somit FIN_ACCEPTED als finaler, positiven Status einer Zahlungsauftragsdatei ab. Aus Gründen der Abwärtskompatibilität wird der Status FIN_CONFIRMED in den API-Versionen < 4.0 als Status FIN_ACCEPTED zurückgegeben.

Die Auftragsarten Z01, CRZ, CDZ und XML sind optional und werden nicht von jedem EBICS-Server unterstützt. Die müssen zudem für den jeweiligen EBICS-Zugang bankseitig konfiguriert und freigegeben werden. Sind diese Voraussetzungen nicht gegeben, verbleibt FIN_ACCEPTED als letztmöglicher positiver Status einer Zahlungsauftragsdatei.

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"
  }
}