Payment-Objekt "payments" – RetailForce Software GmbH

Dieser Artikel behandelt das Payment-Objekt ("payments") innerhalb des Dokumenten-Objekts (Document object).

Eine vollständige Beschreibung des RetailForce DOM (Document Object Model), sowie eine Beschreibung der einzelnen Elemente, finden sie im Downloads-Bereich der RetailForce Website (Object model documentation.pdf) im jeweilige Versions-Verzeichnis.

Im Payment-Objekt können natürlich mehrere unterschiedliche Zahlungen (= unterschiedliche Zahlungsmittel - PaymentType) zu einem einzelnen Beleg enthalten sein.

payments-Objekt

Das nachfolgende payment-Objekt enthält Beispieldaten.

"payments": [
    {
      "amount": 120.00,
      "currencyIsoCode": "EUR",
      "caption": "BAR",
      "uniqueReadablePaymentIdentifier": "BARZAHLUNG",
      "foreignAmount": 0,
      "foreignAmountExchangeRate": 0,
      "additionalFields": {
        "voucherId": "string",
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "paymentType": "cash",
      "createDate": "2023-04-25T15:08:11.57+01:00",
      "vatIdentification": 1,
      "vatPercent": 20,
      "taxValue": 20.00,
      "externalIdentifier": [
        "string"
      ],
      "user": {
        "id": "user01",
        "caption": "user01",
        "firstName": "Manuela",
        "lastName": "Musterfrau",
        "taxNumber": "123456789"
      },
      "salesPerson": {
        "id": "VK01",
        "caption": "Franz",
        "firstName": "Franz",
        "lastName": "Österreicher",
        "taxNumber": "234567890"
      },
      "paymentTerminalReferenceId": "string",
      "cardData": {
        "receiptCopyCount": 0,
        "receipt": [
          "string"
        ],
        "cardNumberMasked": "string",
        "identificationToken": "string",
        "merchantCopyCount": 0,
        "merchantReceipt": [
          "string"
        ]
      }
    }
  ],

Das Payment-Objekt beinhaltet nachfolgende Angaben.

Informationen in der Spalte "Typ":

M ... erforderlich ("mandatory)
M* ... erforderlich in bestimmten Ländern, oder unter bestimmten Voraussetzungen
R ... empfohlen ("recommended")
O ... optional

Element		Typ	Beschreibung
amount		M	Summe der Zahlungsposition
currencyIsoCode		M	ISO 4217 Währungs-Kurzzeichen
caption		M	Bezeichnung der Zahlungsart / des Zahlungsmittels
uniqueReadablePaymentIdentifier		M	Eindeutiger, (beliebiger) Identifier dieser Zahlungsart. Beispiele: "cash", "Barzahlung", "VISA", "BAR-EUR",... Achtung: es ist nicht möglich, 2 verschiedene Währungs-Kurzzeichen für denselben uniqueReadablePaymentIdentifier innerhalb eines Tagesabschlusses (Z-Bericht) zu verwenden! Werden mehrere Währungen verwendet, muss je Währung ein uniqueReadablePaymentIdentifier verwendet werden. Z.B. "BarEUR", "BarUSD", "BarDKK", "Barzahlung-EUR",...
foreignAmount		O	Summe, wenn Zahlung in einer Fremdwährung erfolgt
foreignAmountExchangeRate		O	Wechselkurz der Fremdwährung
additionalFields		M*
	voucherId	M*	Typen: MultiPurposeVoucher, SinglePurposeVoucher. Achtung: `VoucherId` muss im `AdditionalFields`-Objekt platziert werden.
	additionalProp1-x	O
paymentType		M	Zahlungsart / Zahlungsmittel
~~isCash~~		-	das Element "isCash" wird seit dem 01. März 2023 nicht mehr unterstützt. Art der Barzahlung wird durch das Element paymentType definiert. Achtung: Eigenschaft "IsCash" wurde ab Fiskal Client Version 1.7.6 entfernt!
createDate		O	Datum, wann die Zahlungsart angelegt wurde (falls verfügbar)
vatIdentification		M*	ID der MwSt.-Klasse (lt. RF-Zuordnung), siehe: GET /api/v1/information/client/ {clientId}/getVatIdentification Achtung: Bei bestimmten Zahlungsarten müssen Angaben zur MwSt. verpflichtend gemacht werden. Etwa bei Anzahlungen (deposit), Gutscheinen,... Wir empfehlen, Angaben zur MwSt. immer zu inkludieren.
vatPercent		M*	MwSt.-Prozentsatz
taxValue		M*	MwSt.-Betrag
externalIdentifier		O
user		O/M*	Angaben zum Kassenbenutzer (kann angegeben werden, sofern dieser von den Angaben im Dokumenten-Kopf, bzw. bei den Einzelpositionen abweicht)
	id	O/M*	ID Kennzeichen des Kassenbenutzers
	caption	O/M*	Bezeichnung des Kassenbenutzers
	firstName	O	Vorname des Kassenbenutzers
	lastName	O	Nachname des Kassenbenutzers
	taxNumber	M*	Steuernummer des Kassenbenutzers Länderinformation: in bestimmten Ländern (z.B. Slowenien), muss die Steuernummer des Kassenbedieners verpflichtend angegeben werden.
salesPerson		O/M*	Angaben zur Verkäuferin / zum Verkäufer (kann angegeben werden, sofern dieser von den Angaben im Dokumenten-Kopf, bzw. bei den Einzelpositionen abweicht)
	id	O/M*	ID Kennzeichen der Verkäuferin / des Verkäufers
	caption	O/M*	Bezeichnung der Verkäuferin / des Verkäufers
	firstName	O	Vorname der Verkäuferin / des Verkäufers
	lastName	O	Nachnameder Verkäuferin / des Verkäufers
	taxNumber	O/M*	Steuernummerder Verkäuferin / des Verkäufers Länderinforamtion: in bestimmten Ländern (z.B. Slowenien), muss die Steuernummer des Kassenbedieners verpflichtend angegeben werden.
paymentTerminalReferenceId		O/M*	vom Bezahl-Terminal retournierte Transaktions-ID (sofern Bezahl-Terminal mit dem Kassensystem integriert ist und die Transaktions-ID auf dem Dokument angedruckt werden soll). Länderinformation: Dänemark: die paymentTerminalReferenceId muss im Falle von Kartenzahlungen verpflichtend übergeben werden. Weitere Informationen dazu unter Punkt 7. der Anforderungen für Registrierkassen in Dänemark.
cardData		O	Über cardData können Belege von Kreditkarten-Terminal (ohne eigene Druckfunktion) in einen Beleg integriert werden. In Ländern in welchen "Fiskaldrucker" zum Einsatz kommen (= das RetailForce System den Ausdruck von Dokumenten steuert), werden die in cardData-Bereich übergebenen Informationen als Freitextzeilen, anschließend an den Fiskalbeleg, angedruckt. Es erfolgt kein Trennschnitt zw. den beiden Teilen.
	receiptCopyCount	O
	receipt	O
	cardNumberMasked	O
	identificationToken	O
	merchantCopyCount	O
	merchantReceipt	O

Hinweis: mit 01. März 2023 wurde das Feld "IsCash" aus dem Objekt Modell entfernt. Es kann weiterhin übermittelt werden, löst jedoch keine Funktion mehr aus. Zahlungsarten werden über das Feld "PaymentType" gesteuert.

payments-Objekt

Verwandte Beiträge