Physical POS
Payment Operations
Sale Items

Sale Items

For invoice, buyer and fiscal-document fields, and the sale application registration awaiting release, see Sales data and support status. merchantReference does not provide an invoice number or fiscal validation.

You can start a sale (SALE) with product lines. On a sale with items, the tax breakdown is computed per line on the server, refunds can be made by quantity and the tax report is built from the items. Sending items is optional; a sale without items is reversed with an amount refund.

Sale items

In the start a payment request, the items array is sent only on SALE; at most 500 lines. For a sale without items omit the field; an empty array is rejected.

FieldTypeRequiredDescription
lineNointegerYesLine number, starts at 1 and increases without gaps (1, 2, 3 …).
namestringYesProduct name, at most 200 characters (Unicode code points). Follows the text rules; a value that looks like a card number is rejected.
quantityMilliintegerYesQuantity × 1000, greater than 0: 1 piece = 1000, 1.5 kg = 1500.
unitCodestringYesUnit code. → Unit codes
unitPriceMinorstringYesUnit price including all taxes, in minor units, greater than 0. Send a discounted line with its discounted unit price; there is no separate discount field.
taxGroupCodestringYesThe line's tax group; the only tax input of the line. → Tax groups
lineTotalMinorstringYesLine total = quantityMilli × unitPriceMinor / 1000, computed with exact arithmetic and rounded half up. The value you send must match this calculation exactly.
barcodestring | nullNoProduct barcode. → Barcode
  • The sum of the lines' lineTotalMinor must equal the payment's amountMinor.
  • Field types and basic limits are checked when the request is received: lineNo 1–500; quantityMilli a JSON integer of 1 or more; unitPriceMinor and lineTotalMinor canonical positive minor-unit strings; name a non-empty string of at most 400 characters; unitCode at most 3, taxGroupCode at most 24, barcode at most 14 characters. A request failing this check also gets 400 physical_pos.fiscal_document.items_invalid: details.field gives the field's dotted path (such as items.0.quantityMilli) and details.reason the field's reason (line_no_sequence, name_invalid, quantity_invalid, unit_code_invalid, unit_price_invalid, tax_group_code_invalid, line_total_invalid, barcode_invalid; invalid if items is not an array or a line is not an object). If there is more than one error, the response returns the first one. An undefined field in a line gets 400 VALIDATION_ERROR. → Errors
  • You do not send tax amounts; the tax breakdown is computed from the line's tax group and comes back in the item view when the payment is read.
{
  "operation": "SALE",
  "target": { "vendorCode": "PAVO", "serialNumber": "SN0000000001" },
  "amountMinor": "4500",
  "currency": "TRY",
  "merchantReference": "ORD-2026-000124",
  "items": [
    { "lineNo": 1, "name": "Tea", "quantityMilli": 2000, "unitCode": "C62", "unitPriceMinor": "1500", "taxGroupCode": "KDV10", "lineTotalMinor": "3000", "barcode": "8690000000005" },
    { "lineNo": 2, "name": "Simit", "quantityMilli": 1000, "unitCode": "C62", "unitPriceMinor": "1500", "taxGroupCode": "KDV1", "lineTotalMinor": "1500" }
  ]
}

Tax groups

taxGroupCode says which taxes the line is subject to. The group list can grow: an unrecognised group gets 422 physical_pos.fiscal_document.unsupported (details.reason: tax_group_unsupported).

taxGroupCodeTaxes
KDV0_350VAT (KDV) 0%, exempt (reason code 350)
KDV1VAT 1%
KDV10VAT 10%
KDV20VAT 20%
KDV10_TEVKIFAT_604VAT 10% with VAT withholding 5/10 (reason code 604)
OTV25_KDV20Special consumption tax (ÖTV) 25% and VAT 20%; ÖTV is included in the VAT base
KONAKLAMA2_KDV10Accommodation tax 2% and VAT 10%
BSMV5Banking and insurance transaction tax (BSMV) 5%; no VAT

An empty or malformed group code gets 400 physical_pos.fiscal_document.items_invalid (details.reason: tax_group_code_invalid). If the group's fixed per-unit tax exceeds the line total: tax_exceeds_line_total.

Unit codes

unitCodeUnitunitCodeUnit
C62PieceMTQCubic metre
KGMKilogramKWHKilowatt hour
GRMGramHURHour
TNETonneMINMinute
LTRLitreDAYDay
MLTMillilitreMONMonth
MTRMetreANNYear
CMTCentimetrePRPair
KMTKilometreSETSet
MTKSquare metrePAPacket
BXBox

A code not on the list gets 400 physical_pos.fiscal_document.items_invalid (details.reason: unit_code_invalid). Codes are written in upper case, exactly as listed.

Barcode

  • barcode is optional and digits only: GTIN-8, GTIN-12, GTIN-13 or GTIN-14 with a valid check digit. Otherwise 400 physical_pos.fiscal_document.items_invalid (details.reason: barcode_invalid); the value is not echoed.
  • Omitted, null or "" means no barcode.
  • The barcode is stored with the sale and does not change; it comes back only when the payment is read.
  • A 13- or 14-digit barcode with a valid check digit written without separators in the product name (name) is not treated as a card number. Digit runs of 15–19 digits and runs separated by spaces or hyphens are scanned as card numbers.

Item view

Items come back only in the GET /payments/{paymentId} and transaction detail responses, in the sale payment's items array. In list and write responses items is an empty array.

FieldTypeDescription
lineNo, name, quantityMilli, unitCode, unitPriceMinor, taxGroupCode, lineTotalMinorThe values you sent.
netMinorstringThe line amount excluding taxes.
refundedQuantityMilliintegerQuantity refunded by item refunds (× 1000).
refundedMinorstringAmount refunded by item refunds.
reservedQuantityMilliintegerQuantity held by an item refund that has not completed.
reservedMinorstringAmount held by an item refund that has not completed.
refundStatusstringNONE, PARTIAL or FULL. → Item refund status
taxesarrayThe line's tax breakdown; see below.
barcodestring | nullBarcode.

taxes element:

FieldTypeDescription
taxTypestringKDV, KDV_TEVKIFAT, OTV_I, OTV_II, OTV_III, OTV_IV, OIV, BSMV or KONAKLAMA.
taxModestringPERCENT (rate based) or FIXED_PER_UNIT (fixed per unit).
rateBpinteger | nullRate in basis points (1000 = 10%). null for a fixed tax.
unitAmountMinorstring | nullFixed amount per unit. null for a rate-based tax.
baseMinorstringTax base.
amountMinorstringTax amount.
reasonCodestring | nullThe exemption code on a 0% VAT line, the withholding code on a withholding line; null otherwise.
refundedAmountMinorstringTax returned by item refunds.
reservedAmountMinorstringTax held by an item refund that has not completed.

Errors

400 physical_pos.fiscal_document.items_invalid (sale items). details.field gives the path of the field in the request (such as items[0].unitCode; items for rules on the whole list; a dotted path such as items.0.unitCode for the type and limit check made when the request is received), details.reason the reason, and on line rules details.lineNo the line number. The value is not echoed.

details.reasonMeaning
invaliditems is not an array, or one of the lines is not an object.
emptyitems is an empty array.
too_manyMore than 500 lines.
line_no_sequenceLine numbers do not start at 1 or have gaps.
name_invalidThe name is empty, too long or contains a forbidden character.
quantity_invalidThe quantity is 0 or invalid.
unit_code_invalidThe unit code is not on the list.
unit_price_invalidThe unit price is 0 or invalid.
tax_group_code_invalidThe tax group code is empty or malformed.
tax_exceeds_line_totalThe group's fixed tax exceeds the line total.
line_total_invalidThe line total is invalid.
line_total_mismatchThe line total does not match the calculation; details.expectedMinor gives the expected value (a string).
total_mismatchThe sum of the line totals does not equal amountMinor; details.expectedMinor.
barcode_invalidThe barcode is not a GTIN or its check digit is wrong.

422 physical_pos.fiscal_document.unsupported (details.reason: tax_group_unsupported): the tax group code is well formed but not recognised.

All codes: Error Codes.

Refunding an itemized sale: Itemized Refund.