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.
| Field | Type | Required | Description |
|---|---|---|---|
lineNo | integer | Yes | Line number, starts at 1 and increases without gaps (1, 2, 3 …). |
name | string | Yes | Product name, at most 200 characters (Unicode code points). Follows the text rules; a value that looks like a card number is rejected. |
quantityMilli | integer | Yes | Quantity × 1000, greater than 0: 1 piece = 1000, 1.5 kg = 1500. |
unitCode | string | Yes | Unit code. → Unit codes |
unitPriceMinor | string | Yes | Unit 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. |
taxGroupCode | string | Yes | The line's tax group; the only tax input of the line. → Tax groups |
lineTotalMinor | string | Yes | Line total = quantityMilli × unitPriceMinor / 1000, computed with exact arithmetic and rounded half up. The value you send must match this calculation exactly. |
barcode | string | null | No | Product barcode. → Barcode |
- The sum of the lines'
lineTotalMinormust equal the payment'samountMinor. - Field types and basic limits are checked when the request is received:
lineNo1–500;quantityMillia JSON integer of 1 or more;unitPriceMinorandlineTotalMinorcanonical positive minor-unit strings;namea non-empty string of at most 400 characters;unitCodeat most 3,taxGroupCodeat most 24,barcodeat most 14 characters. A request failing this check also gets400 physical_pos.fiscal_document.items_invalid:details.fieldgives the field's dotted path (such asitems.0.quantityMilli) anddetails.reasonthe 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;invalidifitemsis 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 gets400 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).
taxGroupCode | Taxes |
|---|---|
KDV0_350 | VAT (KDV) 0%, exempt (reason code 350) |
KDV1 | VAT 1% |
KDV10 | VAT 10% |
KDV20 | VAT 20% |
KDV10_TEVKIFAT_604 | VAT 10% with VAT withholding 5/10 (reason code 604) |
OTV25_KDV20 | Special consumption tax (ÖTV) 25% and VAT 20%; ÖTV is included in the VAT base |
KONAKLAMA2_KDV10 | Accommodation tax 2% and VAT 10% |
BSMV5 | Banking 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
unitCode | Unit | unitCode | Unit |
|---|---|---|---|
C62 | Piece | MTQ | Cubic metre |
KGM | Kilogram | KWH | Kilowatt hour |
GRM | Gram | HUR | Hour |
TNE | Tonne | MIN | Minute |
LTR | Litre | DAY | Day |
MLT | Millilitre | MON | Month |
MTR | Metre | ANN | Year |
CMT | Centimetre | PR | Pair |
KMT | Kilometre | SET | Set |
MTK | Square metre | PA | Packet |
BX | Box |
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
barcodeis optional and digits only: GTIN-8, GTIN-12, GTIN-13 or GTIN-14 with a valid check digit. Otherwise400 physical_pos.fiscal_document.items_invalid(details.reason:barcode_invalid); the value is not echoed.- Omitted,
nullor""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.
| Field | Type | Description |
|---|---|---|
lineNo, name, quantityMilli, unitCode, unitPriceMinor, taxGroupCode, lineTotalMinor | The values you sent. | |
netMinor | string | The line amount excluding taxes. |
refundedQuantityMilli | integer | Quantity refunded by item refunds (× 1000). |
refundedMinor | string | Amount refunded by item refunds. |
reservedQuantityMilli | integer | Quantity held by an item refund that has not completed. |
reservedMinor | string | Amount held by an item refund that has not completed. |
refundStatus | string | NONE, PARTIAL or FULL. → Item refund status |
taxes | array | The line's tax breakdown; see below. |
barcode | string | null | Barcode. |
taxes element:
| Field | Type | Description |
|---|---|---|
taxType | string | KDV, KDV_TEVKIFAT, OTV_I, OTV_II, OTV_III, OTV_IV, OIV, BSMV or KONAKLAMA. |
taxMode | string | PERCENT (rate based) or FIXED_PER_UNIT (fixed per unit). |
rateBp | integer | null | Rate in basis points (1000 = 10%). null for a fixed tax. |
unitAmountMinor | string | null | Fixed amount per unit. null for a rate-based tax. |
baseMinor | string | Tax base. |
amountMinor | string | Tax amount. |
reasonCode | string | null | The exemption code on a 0% VAT line, the withholding code on a withholding line; null otherwise. |
refundedAmountMinor | string | Tax returned by item refunds. |
reservedAmountMinor | string | Tax 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.reason | Meaning |
|---|---|
invalid | items is not an array, or one of the lines is not an object. |
empty | items is an empty array. |
too_many | More than 500 lines. |
line_no_sequence | Line numbers do not start at 1 or have gaps. |
name_invalid | The name is empty, too long or contains a forbidden character. |
quantity_invalid | The quantity is 0 or invalid. |
unit_code_invalid | The unit code is not on the list. |
unit_price_invalid | The unit price is 0 or invalid. |
tax_group_code_invalid | The tax group code is empty or malformed. |
tax_exceeds_line_total | The group's fixed tax exceeds the line total. |
line_total_invalid | The line total is invalid. |
line_total_mismatch | The line total does not match the calculation; details.expectedMinor gives the expected value (a string). |
total_mismatch | The sum of the line totals does not equal amountMinor; details.expectedMinor. |
barcode_invalid | The 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.