Version

1.0.1

PaymentItem

gefahr

Die Bezahldienst-bezogenen Parameter dürfen ggf. nur in revisionssicheren Systemen und/oder unter Einhaltung eines Vier-Augen-Prinzips oder anderen Regelungen gepflegt werden. Eine Prüfung, ob diese Restriktionen bestehen und wenn ja, für welche Parameter sie gelten, steht noch aus.

Die Standardisierung dieser Parameter steht bis zur Klärung dieser Frage noch aus.

Fachliche Kategorie	Technische Kategorie
Bezahldienst-bezogener Parameter	XZuFi-basierte Standard-Parameter mit direktem Onlinedienst-Bezug

Fachliche Bedeutung

Um einen Bezahlvorgang korrekt im HKR-System verbuchen lassen zu können, übermittelt der Onlinedienst dem Bezahldienst im PaymentRequest u.a. ein oder mehrere Datenstrukturen, die als "PaymentItems" bezeichnet werden. Diese entsprechen den Rechnungspositionen einer Rechnung.

Jedes "PaymentItem" enthält u.a. ein Element "Reference". Dieses entspricht quasi einer Artikelnummer, unter der der Bezahldienst einen Teilbetrag im HKR-System verbuchen lässt. Falls es nur ein "PaymentItem" in einer Transaktion gibt, wird der Gesamtbetrag verbucht.

Jedes "PaymentItem" enthält weiterhin ein optionales Element "BookingData". Die Bezahldienste brauchen teilweise detaillierte Informationen über Titel, Kapitel, Kostenstellen oder sonstige Daten. Diese Informationen werden als Schlüssel/Wert-Paare in "BookingData" zusammengefasst.

In Szenarien mit "gemischtem Warenkorb" muss der Onlinedienst mehrere "PaymentItems" im PaymentRequest an den Bezahldienst aufbauen. Dazu liefert der Parametrisierungs-Mechanismus dem Onlinedienst eine Menge von PaymentItem Paramter-Werten. Damit er diese PaymentItem Paramter-Werte den verschiedenen "Artikel"-Arten seiner Geschäftslogik zuordnen kann, tragen sie einen Identifikator, die PaymentItemID. Da der Identifikator für die Zuordnung nur im Szenario "gemischter Warenkorb" benötigt wird, ist er ansonsten optional.

Die "Reference"/Artikelnummern und "BookingData" sind typischerweise bei jedem Nachnutzenden individuell festgelegt, auch wenn die Verwaltungsleistung - z.B. die Ausstellung einer bestimmten Bescheinigung - überall dieselbe ist. Daher müssen sie parametrisierbar sein.

Wertemenge

Der Wert des Parameters muss ein JSON-Objekt sein, das das folgende JSON-Schema erfüllt:

efa.payment.paymentitem V1.0.1

{
    "$schema": "https://json-schema.org/draft/2019-09/schema",
    "title": "efa.payment.paymentitem V1.0.1",
    "description": "Parameter values for standard EfA parameters that use code `efa.payment.paymentitem` V 1.0.1",
    "type": "object",

    "properties": {
        "paymentItemID": {
            "description": "An identifier that allows the online service to identify this set of paymentItem parameter values.",
            "type": "string",
            "minLength": 1,
            "maxLength": 36,
            "pattern": "^[\\w\\d-]+$"
        },
        "paymentItemReference": {
            "description": "Payment services may require detailed information on the specific service concerned. The payment service can identify the type of service using a type of article number. This information (e.g. international birth certificate) can be transmitted to the payment service by the online service as a parameter for the booking. The content of the character string is determined by the payment service.",
            "type": "string",
            "minLength": 1,
            "maxLength": 36,
            "pattern": "^[\\w\\d-]+$"
        },
        "bookingData": {
            "type": "object",
            "description": "Payment services require detailed information for posting the incoming payment, e.g. title, chapter, cost centre, budget centre, budget manager number or other data. The designations/names of the required posting information are defined by the payment service. The values/contents depend on the authority and the service and are usually determined by the authority. The names and values must be transmitted to the payment service by the online service for the booking (e.g. {title: 123} {manager: 12345}).",
            "additionalProperties": {
                "minItems": 0,
                "maxItems": 99,
                "type": "string",
                "minLength": 0,
                "maxLength": 250,
                "pattern": "^[\\w\\s\\-,.\u00C0-\u017F]+$"
            }
        }
    },
    "required": ["paymentItemReference"] 
}

Ein Beispiel für einen Parameter-Wert ist:

{
    "paymentItemID": "PASSIERSCHEIN_A38",
    "paymentItemReference": "XYZ22113",
    "bookingData": {
        "haushaltstelle": "1234", 
        "objektnummer": "0815", 
        "href": "AlphaBetaGamma"
    }
}

Ein weiteres Beispiel für einen Parameter-Wert ist:

{
    "paymentItemReference": "ABC98765"
}

Verortung im Datenmodell

Siehe Abschnitt Verortung von generischen XZuFi-basierten Standard-Parametern mit direktem Onlinedienst-Bezug im PVOG Datenmodell. Der Namens-Schlüssel ist "efa.payment.paymentitem".

info

Stand Dezember 2024 ist der Code efa.payment.paymentitem noch nicht in der Code-Liste urn:xoev-de:fim:codeliste:xzufi.efaparameter enthalten, was für XZuFi 2.3 relevant wird. Der XZuFi Änderungsbeirat hat aber bereits einer Erweiterung der Code-Liste zugestimmt.

In einem Szenario, in dem ein Onlinedienst mehrere verschiedene Elemente der Dienstleistung bezahlen lassen muss ("gemischter Warenkorb"), müssen auch mehrere Parameter PaymentItem angegeben werden. Es ist daher vorgesehen, dass es mehrere Elemente mit demselben Namens-Schlüssel gibt.

Codebeispiel XZuFi 2.2

<xzufi:onlinedienst xmlns:p3="http://www.w3.org/2001/XMLSchema-instance"
    p3:type="xzufi:OnlinedienstErweitert">
    
      <xzufi:parameter>
        <xzufi:parameterName>efa.payment.paymentitem</xzufi:parameterName>
        <xzufi:parameterWert>{"paymentItemID": "PASSIERSCHEIN_A38", "paymentItemReference": "XYZ22113", "bookingData": {"haushaltstelle": "1234", "objektnummer": "0815", "href": "AlphaBetaGamma"}}</xzufi:parameterWert>
      </xzufi:parameter>
      <xzufi:parameter>
        <xzufi:parameterName>efa.payment.paymentitem</xzufi:parameterName>
        <xzufi:parameterWert>{"paymentItemID": "BESCHEINIGUNG_XYZ", "paymentItemReference": "ABC99887", "bookingData": {"haushaltstelle": "5678", "objektnummer": "4711", "href": "DeltaEpsilonZeta"}}</xzufi:parameterWert>
      </xzufi:parameter>

</xzufi:onlinedienst>

Ermittlungsmöglichkeit PVOG API

Siehe Abschnitt Ermittlung von generischen XZuFi-basierten Standard-Parametern mit direktem Onlinedienst-Bezug mit Hilfe der PVOG-API. Der Namens-Schlüssel ist "efa.payment.paymentitem".

Ermittlungsmöglichkeit FIT-Connect Routing API

(Der Parameter kann nicht über die FIT-Connect Routing-API ermittelt werden.)

Ermittlungsmöglichkeit DVDV API

(Der Parameter kann nicht über das DVDV-API ermittelt werden.)

Best Practices

Der Bezahldienst erwartet in seinem PaymentRequest in jedem "PaymentItem" eine ID, die vom Onlinedienst relativ frei vergeben werden kann. Es ist nicht zwingend notwendig, aber Best Practice, in den Nachrichten zwischen Onlinedienst und Bezahldienst für die "PaymentItems" dieselben IDs zu verwenden, wie sie auch in den PaymentItem Parametern zur Identifikation angegeben sind. Daher enthält das JSON-Schema für die Parameter-Werte auch dieselben syntaktischen Restriktionen für das Element paymentItemID, die sich auch für das Element items[].id im Schema der PaymentRequest-Nachrichten der XBezahldienste-API finden.

Hersteller von Redaktionssystemen sollten komfortable Editoren vorsehen, mit denen die JSON-Objekte "zusammengeklickt" werden können. Diese Editoren müssen dann nur noch elementare Eingabefelder für PaymentItemID, PaymentItemReference und jeweils Schlüssel und Wert der BookingData-Elemente anbieten. Die Hersteller sollten dabei aber auch immer erlauben, den Parameter-Wert als einen Freitext zu erstellen, der nicht nach dem oben genannten JSON-Schema valide ist. Dies ist notwendig, wenn ein Onlinedienst das hier dargestellte Standard-Vorgehen nicht unterstützt.