Payment-object "payments" – RetailForce

This Article concerns the Payment object ("payments") within the Document object.

A complete description of the RetailForce DOM (Document Object Model), as well as a description of the individual elements, can be found in the downloads area of the RetailForce website (Object model documentation.pdf) in the respective version directory.

The payment object can of course contain several different payments (= different means of payment - PaymentType) for a single voucher.

payments-object

The following payment object contains sample data.

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

The following payment object contains sample data.

Information in "Type" column:

M ... mandatory / requird
M* ... mandatory / requird in certain countries or under certain conditions
R ... recommended
O... optional

Elements		Type	Description
amount		M	Total of the payment position
currencyIsoCode		M	ISO 4217 currency code
caption		M	Designation of the payment method / means of payment
uniqueReadablePaymentIdentifier		M	(arbitrary) unique identifier of the payment type. Examples: "cash", "cash payment", "VISA", "cash-EUR",... Attention: it is not possible to use 2 different currency abbreviations for the same unique Readable Payment Identifier within one daily statement (Z-report)! If several currencies are used, a uniqueReadablePaymentIdentifier must be used for each currency. E.g. "CashEUR", "CashUSD", "CashDKK", "Cash payment EUR",...
foreignAmount		O	Total if payment is made in a foreign currency
foreignAmountExchangeRate		O	Foreign currency exchange rate
additionalFields		M*
	voucherId	M*	Types: MultiPurposeVoucher, SinglePurposeVoucher. Attention: `VoucherId` must be nested under the `AdditionalFields` object.
	additionalProp1-x	M*
paymentType		M	Method of payment / Means of payment
~~isCash~~		-	the element "isCash" is no longer supported as of 01st of March 2023. Type of payment is defined by the element paymentType. Attention: Property "IsCash" has been removed as of Fiscal Client version 1.7.6!
createDate		O	Date when the payment type was created (if available)
vatIdentification		M*	VAT class ID (according to RF assignment), see: GET /api/v1/information/client/ {clientId}/getVatIdentification Attention: For certain types of payment, information on VAT must be provided. For example, for down payments (deposit), vouchers,... We recommend that you always include VAT details.
vatPercent		M*	VAT percentage / rate
vatPercent2		O	Second VAT percentage / rate (for mixed VAT rate payments)
taxValue		M*	VAT amount
taxValue2		O	Second VAT amount (for mixed VAT rate payments)
externalIdentifier		O
user		O/M*	Details of the cash register user (can be specified if this differs from the details in the document header or in the line items).
	id	O/M*	ID code of the cash register user
	caption	O/M*	Designation of the cash register user
	firstName	O	First name of the cash register user
	lastName	O	Surname of the cash register user
	taxNumber	O/M*	Tax number of the cash register user Country details: in certain countries (e.g. Slovenia), the tax number of the cashier must be indicated.
salesPerson		O/M*	Details of the salesperson (can be indicated if this differs from the details in the document header or in the individual items)
	id	O/M*	ID number of the salesperson
	caption	O/M*	Designation of the salesperson
	firstName	O	First name of the salesperson
	lastName	O	Surname of the salesperson
	taxNumber	O/M*	Tax number of the salesperson Country details: in certain countries (e.g. Slovenia), the tax number of the cashier must be indicated.
paymentTerminalReferenceId		O/M*	Transaction ID returned by the payment terminal (if the payment terminal is integrated with the POS system and the transaction ID is to be printed on the document). Country details: Denmark: the paymentTerminalReferenceId must be included in the request in the case of card payments. Further information can be found under point 7 of the requirements for cash registers in Denmark.
cardData		O	Receipts from credit card terminals (without their own print function) can be integrated into a receipt via cardData. In countries where "fiscal printers" are used (= the RetailForce system controls the printing of documents), the information included in the cardData area is printed as free text lines following the fiscal receipt. There is no separation between the two parts. Country details: Greece: Additional fields are required for electronic payment processing in Greece, including providerSignature, providerTransactionId, and providerSignatureMessage for compliance with local regulations.
	receiptCopyCount	O	Number of receipt copies
	receipt	O	Receipt text lines array
	cardNumberMasked	O	Masked card number for security (e.g., ****1234)
	identificationToken	O	Unique identification token for the transaction
	merchantCopyCount	O	Number of merchant receipt copies
	merchantReceipt	O	Merchant receipt text lines array
	cardType	O	The card type of the payment transaction (e.g., VISA, MASTERCARD, etc.)
	authorizationCode	O	The authorization code for the payment
	terminalId	O	The ID of the terminal for payment
	merchantId	O	The ID (from the acquirer) of the merchant
	transactionId	O	Unique ID for the transaction
	providerSignature	O/M*	The signature of the payment provider for payment process in Greece
	providerTransactionId	O/M*	The transactionId of the payment provider for payment process in Greece
	providerSignatureMessage	O/M*	The signature message of the payment provider for payment process in Greece
	transactionDate	O	The date of the payment transaction
	transactionNumber	O	The transaction number of the electronic payment

Note: As of 01st of March 2023, the field "IsCash" has been removed from the object model. It can still be transmitted, but no longer triggers a function. Payment types are controlled via the field "PaymentType".

payments-object

Related articles