Payment-Objekt "payments" – RetailForce

Dieser Artikel betrifft das Payment-Objekt ("payments") innerhalb des Document-Objekts.

Eine vollständige Beschreibung des RetailForce DOM (Document Object Model) sowie eine Beschreibung der einzelnen Elemente finden Sie im Download-Bereich der RetailForce-Website (Object model documentation.pdf) im jeweiligen Versionsverzeichnis.

Das Payment-Objekt kann natürlich mehrere verschiedene Zahlungen (= verschiedene Zahlungsmittel - PaymentType) für einen einzelnen Beleg enthalten.

payments-Objekt

Das folgende Payment-Objekt enthält Beispieldaten.

"payments": [
    {
      "amount": 120.00,
      "currencyIsoCode": "EUR",
      "caption": "BAR",
      "uniqueReadablePaymentIdentifier": "BARZAHLUNG",
      "foreignAmount": 0,
      "foreignAmountExchangeRate": 0,
      "additionalFields": {
        "voucherId": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "paymentType": "cash",
      "createDate": "2023-04-25T15:08:11.57+01:00",
      "vatIdentification": 1,
      "vatPercent": 20,
      "vatPercent2": 10,
      "taxValue": 20.00,
      "taxValue2": 10.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": 2,
        "receipt": ["line1", "line2"],
        "cardNumberMasked": "****1234",
        "identificationToken": "token123",
        "merchantCopyCount": 1,
        "merchantReceipt": ["merchant line1"],
        "cardType": "VISA",
        "authorizationCode": "AUTH123",
        "terminalId": "TERM001",
        "merchantId": "MERCH001",
        "transactionId": "TRX123456",
        "providerSignature": "signature_string",
        "providerTransactionId": "PROV_TRX_001",
        "providerSignatureMessage": "signature_message",
        "transactionDate": "2023-04-25T15:08:11.57+01:00",
        "transactionNumber": "12345"
      }
    }
  ],

Das folgende Payment-Objekt enthält Beispieldaten.

Information in der Spalte "Typ":

M ... obligatorisch / erforderlich
M* ... obligatorisch / erforderlich in bestimmten Ländern oder unter bestimmten Bedingungen
R ... empfohlen
O... optional

Elemente		Typ	Beschreibung
amount		M	Gesamtbetrag der Zahlungsposition
currencyIsoCode		M	ISO 4217 Währungscode
caption		O	Bezeichnung der Zahlungsart / des Zahlungsmittels
uniqueReadablePaymentIdentifier		O	(beliebiger) eindeutiger Identifier der Zahlungsart. Beispiele: "cash", "Barzahlung", "VISA", "cash-EUR",... Achtung: Es ist nicht möglich, 2 verschiedene Währungsabkürzungen für denselben uniqueReadablePaymentIdentifier innerhalb eines Tagesabschlusses (Z-Bericht) zu verwenden! Wenn mehrere Währungen verwendet werden, muss für jede Währung ein uniqueReadablePaymentIdentifier verwendet werden. Z.B. "CashEUR", "CashUSD", "CashDKK", "Barzahlung EUR",...
foreignAmount		O	Gesamtbetrag bei Zahlung in einer Fremdwährung
foreignAmountExchangeRate		O	Fremdwährungsumrechnungskurs
additionalFields		M*
	voucherId	M*	Typen: MultiPurposeVoucher, SinglePurposeVoucher. Achtung: `VoucherId` muss unter dem `AdditionalFields` Objekt verschachtelt sein.
	additionalProp1-x	M*
paymentType		M	Zahlungsart / Zahlungsmittel
~~isCash~~		-	Das Element "isCash" wird ab dem 01. März 2023 nicht mehr unterstützt. Die Zahlungsart wird durch das Element paymentType definiert. Achtung: Die Eigenschaft "IsCash" wurde ab Fiscal Client Version 1.7.6 entfernt!
createDate		O	Datum, an dem die Zahlungsart erstellt wurde (falls verfügbar)
vatIdentification		M*	MwSt.-Klassen-ID (gemäß RF-Zuordnung), siehe: GET /api/v1/information/client/ {clientId}/getVatIdentification Achtung: Bei bestimmten Zahlungsarten müssen Angaben zur Mehrwertsteuer gemacht werden. Zum Beispiel bei Anzahlungen (Kaution), Gutscheinen,... Wir empfehlen, immer MwSt.-Details anzugeben.
vatPercent		M*	MwSt.-Prozentsatz / Satz
vatPercent2		O	Zweiter MwSt.-Prozentsatz / Satz (für Zahlungen mit gemischten MwSt.-Sätzen)
taxValue		M*	MwSt.-Betrag
taxValue2		O	Zweiter MwSt.-Betrag (für Zahlungen mit gemischten MwSt.-Sätzen)
externalIdentifier		O
user		O/M*	Details des Kassenbenutzers (kann angegeben werden, wenn diese sich von den Angaben im Dokumentenkopf oder in den Positionen unterscheiden).
	id	O/M*	ID-Code des Kassenbenutzers
	caption	O/M*	Bezeichnung des Kassenbenutzers
	firstName	O	Vorname des Kassenbenutzers
	lastName	O	Nachname des Kassenbenutzers
	taxNumber	O/M*	Steuernummer des Kassenbenutzers Länderdetails: In bestimmten Ländern (z.B. Slowenien) muss die Steuernummer des Kassierers angegeben werden.
salesPerson		O/M*	Details des Verkäufers (kann angegeben werden, wenn diese sich von den Angaben im Dokumentenkopf oder in den einzelnen Positionen unterscheiden)
	id	O/M*	ID-Nummer des Verkäufers
	caption	O/M*	Bezeichnung des Verkäufers
	firstName	O	Vorname des Verkäufers
	lastName	O	Nachname des Verkäufers
	taxNumber	O/M*	Steuernummer des Verkäufers Länderdetails: In bestimmten Ländern (z.B. Slowenien) muss die Steuernummer des Kassierers angegeben werden.
paymentTerminalReferenceId		O/M*	Transaktions-ID, die vom Zahlungsterminal zurückgegeben wird (wenn das Zahlungsterminal mit dem POS-System integriert ist und die Transaktions-ID auf dem Beleg gedruckt werden soll). Länderdetails: Dänemark: Die paymentTerminalReferenceId muss bei Kartenzahlungen in der Anfrage enthalten sein. Weitere Informationen finden Sie unter Punkt 7 der Anforderungen für Registrierkassen in Dänemark.
cardData		O	Belege von Kreditkartenterminals (ohne eigene Druckfunktion) können über cardData in einen Beleg integriert werden. In Ländern, in denen "Fiskaldrucker" verwendet werden (= das RetailForce-System steuert den Druck von Dokumenten), werden die im cardData-Bereich enthaltenen Informationen als Freitextzeilen nach dem Fiskalbeleg gedruckt. Es gibt keine Trennung zwischen den beiden Teilen. Länderdetails Griechenland: Zusätzliche Felder sind für die elektronische Zahlungsverarbeitung in Griechenland erforderlich, einschließlich providerSignature, providerTransactionId und providerSignatureMessage zur Einhaltung lokaler Vorschriften.
	receiptCopyCount	O	Anzahl der Belegkopien
	receipt	O	Belegtextzeilen-Array
	cardNumberMasked	O	Maskierte Kartennummer aus Sicherheitsgründen (z.B. ****1234)
	identificationToken	O	Eindeutiges Identifikationstoken für die Transaktion
	merchantCopyCount	O	Anzahl der Händlerbelegkopien
	merchantReceipt	O	Händlerbelegtextzeilen-Array
	cardType	O	Der Kartentyp der Zahlungstransaktion (z.B. VISA, MASTERCARD, etc.)
	authorizationCode	O	Der Autorisierungscode für die Zahlung
	terminalId	O	Die ID des Terminals für die Zahlung
	merchantId	O	Die ID (vom Acquirer) des Händlers
	transactionId	O	Eindeutige ID für die Transaktion
	providerSignature	O/M*	Die Signatur des Zahlungsanbieters für den Zahlungsprozess in Griechenland
	providerTransactionId	O/M*	Die Transaktions-ID des Zahlungsanbieters für den Zahlungsprozess in Griechenland
	providerSignatureMessage	O/M*	Die Signaturnachricht des Zahlungsanbieters für den Zahlungsprozess in Griechenland
	transactionDate	O	Das Datum der Zahlungstransaktion
	transactionNumber	O	Die Transaktionsnummer der elektronischen Zahlung

Hinweis: Ab dem 01. März 2023 wurde das Feld "IsCash" aus dem Objektmodell entfernt. Es kann weiterhin übertragen werden, löst aber keine Funktion mehr aus. Zahlungsarten werden über das Feld "PaymentType" gesteuert.

payments-Objekt

Verwandte Beiträge