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.

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