Schemas
The operation pages expand referenced schemas inline. Use this page to browse the reusable component schemas and inspect their complete YAML definitions.
21 schemas.
- TokenResponse
object - AddStoreResponse
object - AddChainResponse
object - GetChainResponse
object - AllChainsResponse
array - GetStoreResponse
object - AllStoresResponse
array - ErrorResponse
object - ReceiptErrorResponse
object - Finding
object - AddStore
object - UpdateStore
object - AddChain
object - UpdateChain
object - RegisterEMS
object - RegisterPersonForEMS
object - DeregisterPersonForEMS
object - PrescriptionSpecificationResponse
object - Receipt v2.0
object - Receipt v1.1
object - Prescription v1.0
object
TokenResponseobject
title: TokenResponse
type: object
properties:
access_token:
type: string
token_type:
type: string
enum:
- Bearer
expires_in:
description: expiration time in seconds
type: integer
AddStoreResponseobject
title: AddStoreResponse
type: object
properties:
store_id:
type: string
vat:
type: string
external_id:
type: string
created:
type: boolean
AddChainResponseobject
title: AddChainResponse
type: object
properties:
chain_id:
type: string
vat:
type: string
created:
type: boolean
GetChainResponseobject
title: GetChainResponse
type: object
properties:
chain_id:
type: string
partner_id:
type: string
name:
type: string
vat:
type: string
phone:
type: string
icon_url:
type: string
logo_url:
type: string
greenbin_activated:
type: boolean
retained_activated:
type: boolean
address:
type: object
properties:
street1:
type: string
street2:
type: string
street3:
type: string
postalcode:
type: string
city:
type: string
state:
type: string
country:
type: string
AllChainsResponsearray
title: AllChainsResponse
type: array
items:
$ref: "#/components/schemas/GetChainResponse"
GetStoreResponseobject
title: GetStoreResponse
type: object
properties:
store_id:
type: string
external_id:
type: string
owner_id:
type: string
partner_id:
type: string
name:
type: string
vat:
type: string
phone:
type: string
icon_url:
type: string
logo_url:
type: string
address:
type: object
properties:
street1:
type: string
street2:
type: string
street3:
type: string
postalcode:
type: string
city:
type: string
state:
type: string
country:
type: string
AllStoresResponsearray
title: AllStoresResponse
type: array
items:
$ref: "#/components/schemas/GetStoreResponse"
ErrorResponseobject
title: ErrorResponse
type: object
properties:
error_code:
type: string
short_message:
type: string
long_message:
type: string
error_detail:
type: array
items:
type: string
ReceiptErrorResponseobject
title: ErrorResponse
type: object
properties:
error_code:
type: string
short_message:
type: string
long_message:
type: string
error_detail:
type: array
items:
type: string
findings:
type: array
description: Structured validation findings, present on a 40020
semantic-validation rejection for opted-in partners. See the Receipt
validation logic guide.
items:
$ref: "#/components/schemas/Finding"
Findingobject
One validation finding. See the Receipt validation logic guide.
title: Finding
type: object
description: One validation finding. See the Receipt validation logic guide.
required:
- code
- severity
- message
properties:
code:
type: string
description: Stable identifier for the check, e.g. items.paid_mismatch.
severity:
type: string
enum:
- error
- warning
- info
description: error = contract violation (rejected with 400 40020 for opted-in
partners); warning/info = non-fatal feedback.
path:
type: string
description: JSON path to the offending field, e.g. payments[0].tender.card_token.
message:
type: string
description: Human-readable description of the finding.
expected:
description: The expected value, for mismatch findings.
actual:
description: The value found, for mismatch findings.
AddStoreobject
title: AddStore
type: object
properties:
external_id:
type: string
description: ID provided by the POS that is unique per chain
name:
type: string
description: The name of the store
minLength: 1
vat:
type: string
description: The VAT number of the store
pattern: ^((SE)?[0-9]{12})$"
owner_id:
type: string
description: ID of the owner company (chain)
pattern: ^([a-z0-9]{42})$
phone:
type: string
description: The phone number of the store
address:
type: object
description: The address of the store
properties:
street1:
type: string
street2:
type: string
street3:
type: string
postalcode:
type: string
city:
type: string
state:
type: string
country:
type: string
maxLength: 3
minLength: 3
required:
- street1
- postalcode
- country
icon:
type: object
description: Icon displayed on the receipt
properties:
data:
type: string
description: Base64 encoded image
content_type:
type: string
description: The image content type
required:
- data
- content_type
logo:
type: object
description: Logo displayed on the receipt
properties:
data:
type: string
description: Base64 encoded image
content_type:
type: string
description: The image content type
required:
- data
- content_type
required:
- name
- vat
- owner_id
UpdateStoreobject
title: UpdateStore
type: object
properties:
name:
type: string
description: The name of the store
minLength: 1
vat:
type: string
description: The VAT number of the store
pattern: ^((SE)?[0-9]{12})$"
owner_id:
type: string
description: ID of the owner company (chain)
pattern: ^([a-z0-9]{42})$
phone:
type: string
description: The phone number of the store
address:
type: object
description: The address of the store
properties:
street1:
type: string
street2:
type: string
street3:
type: string
postalcode:
type: string
city:
type: string
state:
type: string
country:
type: string
maxLength: 3
minLength: 3
icon:
type: object
description: Icon displayed on the receipt
properties:
data:
type: string
description: Base64 encoded image
content_type:
type: string
description: The image content type
required:
- data
- content_type
logo:
type: object
description: Logo displayed on the receipt
properties:
data:
type: string
description: Base64 encoded image
content_type:
type: string
description: The image content type
required:
- data
- content_type
AddChainobject
title: AddChain
type: object
properties:
external_id:
type: string
description: External identifier for the chain, unique per partner
pattern: ^.{5,128}$
name:
type: string
description: The name of the chain
minLength: 1
vat:
type: string
description: The VAT number of the chain
pattern: ^((SE)?[0-9]{12})$"
phone:
type: string
description: The phone number of the store
address:
type: object
description: The address of the store
properties:
street1:
type: string
street2:
type: string
street3:
type: string
postalcode:
type: string
city:
type: string
state:
type: string
country:
type: string
maxLength: 3
minLength: 3
required:
- street1
- postalcode
- country
icon:
type: object
description: Icon displayed on the receipt
properties:
data:
type: string
description: Base64 encoded image
content_type:
type: string
description: The image content type
required:
- data
- content_type
logo:
type: object
description: Logo displayed on the receipt
properties:
data:
type: string
description: Base64 encoded image
content_type:
type: string
description: The image content type
required:
- data
- content_type
item_display_fields:
type: array
description: The extra fields from receipt items that should be displayed in the app
items:
type: string
enum:
- article_number_pos
- article_number_gtin
retained_activated:
type: boolean
description: >
Whether retained receipts are activated for this chain. If omitted along
with `greenbin_activated`, defaults to the partner's setting. If the other
field is provided but this one is omitted, defaults to `false`.
required:
- name
anyOf:
- required:
- vat
- required:
- external_id
UpdateChainobject
title: UpdateChain
type: object
properties:
external_id:
type: string
description: External identifier for the chain, unique per partner
pattern: ^.{5,128}$
name:
type: string
description: The name of the chain
minLength: 1
vat:
type: string
description: The VAT number of the chain
pattern: ^((SE)?[0-9]{12})$"
phone:
type: string
description: The phone number of the chain
address:
type: object
description: The address of the chain
properties:
street1:
type: string
street2:
type: string
street3:
type: string
postalcode:
type: string
city:
type: string
state:
type: string
country:
type: string
maxLength: 3
minLength: 3
icon:
type: object
description: Icon displayed on the receipt
properties:
data:
type: string
description: Base64 encoded image
content_type:
type: string
description: The image content type
required:
- data
- content_type
logo:
type: object
description: Logo displayed on the receipt
properties:
data:
type: string
description: Base64 encoded image
content_type:
type: string
description: The image content type
required:
- data
- content_type
item_display_fields:
type: array
description: The extra fields from receipt items that should be displayed in the app
items:
type: string
enum:
- article_number_pos
- article_number_gtin
retained_activated:
type: boolean
description: Whether retained receipts are activated for this chain
RegisterEMSobject
title: RegisterEMS
type: object
properties:
external_id:
type: string
description: External ID of the expense management system that identifies it in
foreign system
name:
type: string
description: The name of the expense management system
minLength: 1
url:
type: string
description: A URL that points to the root URL of the foreign EMS API
icon_url:
type: string
description: An optional icon URL that represents the full URL to an icon
belonging to the EMS
RegisterPersonForEMSobject
title: RegisterPersonForEMS
type: object
properties:
external_id:
type: string
description: External ID of the expense management system that identifies it in
foreign system
owner_id:
type: string
description: The id of the person registering for expense management system
minLength: 1
token:
type: string
description: A token to use when expensing a receipt for this person in the foreign EMS
DeregisterPersonForEMSobject
title: DeregisterPersonForEMS
type: object
properties:
external_id:
type: string
description: External ID of the expense management system that identifies it in
foreign system
owner_id:
type: string
description: The id of the person registering for expense management system
minLength: 1
PrescriptionSpecificationResponseobject
title: PrescriptionSpecificationResponse
type: object
properties:
receipt_id:
type: string
prescription_specification_id:
type: string
Receipt v2.0object
digital receipt schema
$id: https://se.receipts.kivra.com/schemas/json/retail/v2.0
$schema: https://json-schema.org/draft/2020-12/schema
description: digital receipt schema
type: object
properties:
copy:
type: boolean
default: false
description: If true the receipt is a copy
business_unit:
description: Merchant information
$ref: "#/components/schemas/Receipt v2.0/$defs/business_information"
cashier:
description: Identifies the person handling the purchase if applicable
$ref: "#/components/schemas/Receipt v2.0/$defs/cashier"
sales_recording_system:
description: Information about the point of sales system used. The system
producing the receipt
$ref: "#/components/schemas/Receipt v2.0/$defs/sales_recording_system"
receipt_identifier:
description: "Receipt identifiers: sequence number and/or extended number with
or without barcode representation"
$ref: "#/components/schemas/Receipt v2.0/$defs/receipt_identifier"
time_of_purchase:
description: "ISO 8601 date/time format: YYYY-MM-DDThh:mm:ssTZD"
type: string
format: date-time
currency:
description: The receipt default currency. This gives the currency for all
amounts in the receipt. If applicable overriding currencies can be added
to the tender parts
$ref: "#/components/schemas/Receipt v2.0/$defs/currency_code"
totals:
description: 'Total amounts keyed by type, e.g. {"gross": {...}, "vat": {...}}.'
type: object
properties:
paid:
$ref: "#/components/schemas/Receipt v2.0/$defs/total_paid_element"
gross:
$ref: "#/components/schemas/Receipt v2.0/$defs/total_gross_element"
vat:
$ref: "#/components/schemas/Receipt v2.0/$defs/total_tax_element"
net:
$ref: "#/components/schemas/Receipt v2.0/$defs/total_net_element"
loyalty:
$ref: "#/components/schemas/Receipt v2.0/$defs/total_loyalty_element"
rounding:
$ref: "#/components/schemas/Receipt v2.0/$defs/total_rounding_element"
modifiers:
$ref: "#/components/schemas/Receipt v2.0/$defs/total_modifiers_element"
additionalProperties: false
header_text:
description: Any textual information aimed for the receipt header
type: string
footer_text:
description: Any textual information aimed for the receipt footer
type: string
items:
description: 'List of receipt items, goods or services sold/returned. Each entry
is a single-key object naming the item type, e.g. {"sale": {...}}. The key
implies the type, so it need not be repeated inside the value.'
type: array
items:
type: object
minProperties: 1
maxProperties: 1
additionalProperties: false
properties:
sale:
$ref: "#/components/schemas/Receipt v2.0/$defs/sale_item"
return:
$ref: "#/components/schemas/Receipt v2.0/$defs/return_item"
text:
$ref: "#/components/schemas/Receipt v2.0/$defs/text_item"
deposit:
$ref: "#/components/schemas/Receipt v2.0/$defs/deposit_item"
modifiers:
type: array
description: "Receipt-level price modifiers (discounts/surcharges) that apply to
the whole receipt and cannot be attributed to individual lines — for
example a 5% discount on the entire purchase, spread pro-rata across its
VAT rates. If the POS can attribute a modifier to specific lines it does
not belong here: put it on those lines' own modifiers instead (e.g. a
discount on a single item). Distinct from totals.modifiers, which is the
aggregate discount/surcharge checksum derived from these."
items:
$ref: "#/components/schemas/Receipt v2.0/$defs/price_modifier_element"
payments:
description: Tender related information, several tender types can be used for payment
type: array
items:
$ref: "#/components/schemas/Receipt v2.0/$defs/tender_element"
customer:
description: Identification and information about the customer
$ref: "#/components/schemas/Receipt v2.0/$defs/customer"
customer_order:
description: Information about a connected customer order if applicable
$ref: "#/components/schemas/Receipt v2.0/$defs/customer_order_information"
control_unit:
description: Control unit information required by swedish tax authorities
type: object
properties:
id:
type: string
code:
type: string
required:
- id
additionalProperties: false
required:
- business_unit
- sales_recording_system
- receipt_identifier
- time_of_purchase
- currency
- totals
- items
- payments
additionalProperties: false
$defs:
organization_number:
type: string
description: Swedish organisationsnummer (10 digits, optionally hyphenated). A
VAT number must be sent in vat_number, not here.
pattern: ^[0-9]{6}-?[0-9]{4}$
vat_number:
type: string
description: VAT registration number incl. country prefix (SE/NO/DK/FI),
accepted as an alternative to organization_number. A plain Swedish
organisationsnummer must go in organization_number, not here.
examples:
- SE556677889901
- NO123456789MVA
- DK99999999
- FI99999999
pattern: ^(SE[0-9]{12}|NO[0-9]{9}(?:[Mm][Vv][Aa])?|DK[0-9]{8}|FI[0-9]{8})$
country_code:
title: country code
description: Country as an ISO 3166-1 alpha-3 code, e.g. SWE. Case-insensitive.
type: string
pattern: ^[A-Za-z]{3}$
address:
title: address
description: An address following the convention of
http://microformats.org/wiki/hcard. At least one of street_address or
post_box is required.
type: object
properties:
street_address:
type: string
extended_address:
type: string
post_box:
type: string
locality:
type: string
postal_code:
type: string
region:
type: string
country_code:
$ref: "#/components/schemas/Receipt v2.0/$defs/country_code"
type:
title: address type
description: Whether the address relates to a business or a home
type: string
enum:
- home
- business
anyOf:
- title: Street address
required:
- street_address
- title: Post box address
required:
- post_box
required:
- locality
- postal_code
additionalProperties: false
phone_number:
title: generic phone number
description: generic format for phone numbers where strict format can not be
enforced, use only for phone number to be displayed
type: string
pattern: ^(\(?((\+|(00))[0-9]{1,3})\)?)?( ?-?\(?[0-9]+\)?)+$
geo_location:
type: object
$comment: No additionalProperties:false — shared with the draft-07 ps family;
tightening it here would change ps behavior on its next regeneration.
title: Geographic location (long/lat)
description: A geographical coordinate
properties:
latitude:
type: number
longitude:
type: number
required:
- latitude
- longitude
business_information:
type: object
description: Merchant/business unit information. At least one of
organization_number or vat_number is required to identify the merchant and
a stable external_id alternatively an existing service_id.
properties:
name:
type: string
service_id:
description: Kivra id of an existing business unit.
type: string
minLength: 42
maxLength: 42
pattern: ^[0-9]{10}[0-9a-fA-F]{32}$
unit_id:
type: string
description: Internal merchant shop/business unit id
external_id:
type: string
description: Partner's own stable identifier for the store. The store is deduped
on (owning chain, external_id), so a partner keeps one store per
external_id.
organization_number:
$ref: "#/components/schemas/Receipt v2.0/$defs/organization_number"
vat_number:
$ref: "#/components/schemas/Receipt v2.0/$defs/vat_number"
contact:
type: object
description: Merchant contact information name, address, phone etc
properties:
address:
$ref: "#/components/schemas/Receipt v2.0/$defs/address"
email:
type: string
format: email
phone:
$ref: "#/components/schemas/Receipt v2.0/$defs/phone_number"
website:
type: string
format: uri
additionalProperties: false
geo_location:
$ref: "#/components/schemas/Receipt v2.0/$defs/geo_location"
chain:
type: object
description: Optional chain grouping for the store. Reference an existing chain
with service_id, or supply name plus organization_number, vat_number,
or external_id to group the store under a chain that is created on
first use. organization_number/vat_number follow the same semantics as
on the wrapping business unit. When omitted, the store is grouped
under the default chain (one per the store's own organization/VAT
number per partner).
properties:
service_id:
description: Kivra id of an existing chain. When present, references that chain
directly; name/organization_number/vat_number/external_id are then
not required.
type: string
minLength: 42
maxLength: 42
pattern: ^[0-9]{10}[0-9a-fA-F]{32}$
name:
type: string
description: Display name of the chain. Required when the chain may need to be
created (i.e. when service_id is absent).
organization_number:
description: Swedish organisationsnummer (10 digits, optionally hyphenated) of
the chain. A VAT number must be sent in vat_number, not here.
Grouping key when external_id is absent.
$ref: "#/components/schemas/Receipt v2.0/$defs/organization_number"
vat_number:
description: Chain VAT registration number incl. country prefix (SE/NO/DK/FI),
accepted as an alternative to organization_number. A plain Swedish
organisationsnummer must go in organization_number, not here.
Grouping key when external_id is absent.
$ref: "#/components/schemas/Receipt v2.0/$defs/vat_number"
external_id:
type: string
description: Partner's own stable identifier for the chain. Grouping key when no
organization_number/vat_number is given.
anyOf:
- title: Existing chain referenced by service_id
required:
- service_id
- title: Chain identified by name and organization number
required:
- name
- organization_number
- title: Chain identified by name and VAT number
required:
- name
- vat_number
- title: Chain identified by name and partner external id
required:
- name
- external_id
additionalProperties: false
required:
- name
- contact
anyOf:
- title: Identified by external_id and organization number
required:
- external_id
- organization_number
- title: Identified by external_id and VAT number
required:
- external_id
- vat_number
- title: Identified by service_id and organization number
required:
- service_id
- organization_number
- title: Identified by service_id and VAT number
required:
- service_id
- vat_number
additionalProperties: false
cashier:
title: cashier name and id
description: information about the cashier, optional
type: object
properties:
id:
type: string
name:
type: string
additionalProperties: false
pos_information:
title: point of sales system
description: information that somehow identifies the pos system. At least one of
id or name is required.
type: object
properties:
id:
type: string
name:
type: string
serial_number:
type: string
anyOf:
- title: POS identified by id
required:
- id
- title: POS identified by name
required:
- name
additionalProperties: false
sales_recording_system:
title: sales recording system information
description: A sales recording system is any system where the sales is
registered. Example POS
$ref: "#/components/schemas/Receipt v2.0/$defs/pos_information"
barcode_element:
type: string
enum:
- Interleaved2Of5
- EAN13
- EAN8
- Codabar
- Code39
- Code93
- Code128
- AztecCode
- Datamatrix
- PDF417
- QRCode
description: barcode representation of any data
extended_receipt_number_type:
type: object
$comment: No additionalProperties:false — shared with the draft-07 ps family;
tightening it here would change ps behavior on its next regeneration.
description: a more complex receipt number if applicable, must be unique in
given context
properties:
value:
type: string
description: data that will be presented as a barcode on the receipt
type:
$ref: "#/components/schemas/Receipt v2.0/$defs/barcode_element"
context:
type: string
enum:
- store
- chain
- global
description: in what context is the value (receipt number) unique, note GLOBAL
can only be used if a digital receipt provider receipt id is used
required:
- value
- context
receipt_identifier:
title: receipt identifier
description: a receipt is often identified by a sequence number and/or an
extended id (unique in some context) with or without a barcode
representation.
type: object
properties:
sequence_number:
type: integer
description: a sequence number as stipulated by the swedish tax authorities
extended_number:
$ref: "#/components/schemas/Receipt v2.0/$defs/extended_receipt_number_type"
required:
- sequence_number
additionalProperties: false
currency_code:
title: ISO-4217 currency codes
description: "ISO 4217 currency code, e.g.: USD, EUR, CHF"
type: string
pattern: ^[a-zA-Z]{3}$
total_paid_element:
title: Paid total amount
description: "paid: gross amount including discount and rounding."
type: object
properties:
amount:
type: number
description: "Signed paid total: negative when money goes back to the customer
(e.g. a return)."
received:
type: number
minimum: 0
description: Amount received from the customer (e.g. cash tendered), when it
differs from the paid amount.
returned:
type: number
minimum: 0
description: Amount returned to the customer (e.g. change given), when applicable.
required:
- amount
additionalProperties: false
total_gross_element:
title: Total gross amount presented on the receipt
description: "gross: total including vat, excluding discounts"
type: object
properties:
amount:
type: number
description: "Signed gross total: negative when money goes back to the customer
(e.g. a return)."
required:
- amount
additionalProperties: false
sub_total_vat:
title: Sub totals can be used on all totals but is mostly used on VAT
description: One or more sub totals, exactly one per distinct tax percentage.
Every line and modifier at a given rate is aggregated into that rate's
single bucket. Monetary fields are signed (see amount).
type: object
properties:
amount:
type: number
description: "Signed amount for this VAT bucket: the signed sum of every line
and modifier at this tax_percentage. Because there is one bucket per
rate, opposite-direction entries at the same rate cancel — e.g. a +15
kr sale and a −15 kr return, both at 15%, aggregate into a single 15%
bucket with amount 0. Negative when returns at the rate outweigh
sales."
taxable_amount:
description: Amount including tax amount (signed, same direction as amount).
type: number
net_amount:
description: Amount excluding tax amount (signed, same direction as amount).
type: number
tax_percentage:
type: number
minimum: 0
required:
- amount
- taxable_amount
- net_amount
- tax_percentage
additionalProperties: false
total_tax_element:
title: Total tax amount presented on the receipt
description: Tax releated total
type: object
properties:
amount:
type: number
description: "Signed tax total: negative when money goes back to the customer
(e.g. a return)."
sub_totals:
type: array
description: add sub total for each tax percentage used
items:
$ref: "#/components/schemas/Receipt v2.0/$defs/sub_total_vat"
required:
- amount
additionalProperties: false
total_net_element:
title: Total net amount presented on the receipt
description: "net: total excluding vat"
type: object
properties:
amount:
type: number
description: "Signed net total: negative when money goes back to the customer
(e.g. a return)."
required:
- amount
additionalProperties: false
total_loyalty_element:
title: Total loyalty amount
description: Total loyalty points/amount redeemed. Amount only — no breakdown applies.
type: object
properties:
amount:
type: number
minimum: 0
required:
- amount
additionalProperties: false
total_rounding_element:
title: Total rounding amount
description: Rounding adjustment applied to reach the paid amount. Amount only —
no breakdown applies.
type: object
properties:
amount:
type: number
description: Signed rounding adjustment (may be negative).
required:
- amount
additionalProperties: false
total_modifier_amount_element:
type: object
properties:
amount:
type: number
minimum: 0
description: Positive magnitude; the enclosing discount/surcharge key carries
the direction.
required:
- amount
additionalProperties: false
total_modifiers_element:
title: Modifier totals
description: Aggregate discount and surcharge totals. Both are fully derivable
from the line- and receipt-level modifiers (a checksum), so either may be
omitted. If sent, provide at least one.
type: object
minProperties: 1
properties:
discount:
$ref: "#/components/schemas/Receipt v2.0/$defs/total_modifier_amount_element"
surcharge:
$ref: "#/components/schemas/Receipt v2.0/$defs/total_modifier_amount_element"
additionalProperties: false
item_identifier:
title: Item identifier
description: "Identifier for an item being sold or returned. Supported types:
'pos' (Point of Sale identifier) and 'gtin' (Global Trade Item Number)."
type: object
properties:
identifier_type:
type: string
enum:
- pos
- gtin
value:
type: string
required:
- identifier_type
- value
additionalProperties: false
entry_method_elment:
type: string
enum:
- smartcard
- micr
- msr
- keyed
- scanned
- weighed
- measured
- rfid
- automatic
- integrated_chip_card
- tapped
- waved
default: scanned
quantity_element:
type: object
properties:
value:
type: number
exclusiveMinimum: 0
description: "Quantity sold/returned/covered. Must be > 0: a line for zero units
is not a real sale, and it would make the per-unit price
(actual_sales_unit_price = extended_amount / quantity) underivable."
unit:
type: string
minLength: 1
maxLength: 25
pattern: \S
description: Unit for this quantity; we recommend following a standard such as
UN/CEFACT Rec 20. Must contain at least one non-whitespace character.
entry_method:
$ref: "#/components/schemas/Receipt v2.0/$defs/entry_method_elment"
required:
- value
- unit
additionalProperties: false
price_modifier:
title: Price modifier value
description: The value of a discount or surcharge (direction is set by the
enclosing key). amount is authoritative; percent, base_amount and quantity
are informational only.
type: object
properties:
amount:
type: number
minimum: 0
description: Required, authoritative monetary magnitude (VAT-inclusive), always
positive. Direction is carried by the enclosing discount/surcharge
key.
description:
type: string
description: Human-readable label for the modifier, e.g. "Member offer −10%".
reason:
type: string
enum:
- loyalty
- coupon
- campaign
- employee
- staff
- damage
- price_match
- other
description: Optional category of the modifier.
percent:
type: number
minimum: 0
description: "Informational: the percentage applied (always positive)."
base_amount:
type: number
minimum: 0
description: "Informational: the amount the percent applied to."
quantity:
type: integer
minimum: 1
description: "Informational: how many times the modifier was applied. Might not
equal the item quantity. Example: 2 coupons '3 for 2' on six items —
item quantity 6, modifier quantity 2."
tax_percentage:
type: number
minimum: 0
description: "VAT-bucket routing key: the tax rate the modifier's
(VAT-inclusive) amount belongs to. Send only when it differs from the
affected line's rate."
required:
- amount
additionalProperties: false
price_modifier_element:
title: Price modifier
description: 'A single price modifier, keyed by direction: {"discount": {...}}
reduces what the customer pays, {"surcharge": {...}} increases it. The key
carries the direction — there is no action/type field and no sign on
amount. Used identically at line and receipt level.'
type: object
minProperties: 1
maxProperties: 1
additionalProperties: false
properties:
discount:
$ref: "#/components/schemas/Receipt v2.0/$defs/price_modifier"
surcharge:
$ref: "#/components/schemas/Receipt v2.0/$defs/price_modifier"
foreign_currency:
title: Foreign currency
description: Gives exchange rate etc when payment is done with a foreign currency
type: object
properties:
currency:
description: ISO 4217 foreign currency code
$ref: "#/components/schemas/Receipt v2.0/$defs/currency_code"
original_face_amount:
description: the original amount in the foreign currency the being converted to
local currency. For example, converting Yen to Dollars, this amount
would be the amount of Yen
type: number
minimum: 0
exchange_rate:
type: number
minimum: 0
required:
- currency
- original_face_amount
additionalProperties: false
sale_item:
description: Defines data needed to handle sold product/service
type: object
properties:
sequence_number:
description: All items must have a unique sequence number 1,2,3 etc. Used for
internal references. Also see item_link
type: integer
item_link:
description: A reference to an other items sequence_number if a relation exists
type: integer
text:
type: string
identifiers:
type: array
minItems: 1
items:
$ref: "#/components/schemas/Receipt v2.0/$defs/item_identifier"
serial_number:
description: Product serial number
type: string
lot_number:
description: Specifies a specific product batch/lot
type: string
description:
type: string
quantity:
$ref: "#/components/schemas/Receipt v2.0/$defs/quantity_element"
eligible_for_frequent_shopper_points:
type: boolean
default: false
description: true if item bought is eligible for bonus
unit_cost_price:
type: number
description: The unit cost of the item to the merchant at the time of the
Transaction.
regular_sales_unit_price:
type: number
description: "Optional: the undiscounted per-unit price the merchant printed,
before any discounts or surcharges."
actual_sales_unit_price:
type: number
description: 'Optional: the authoritative per-unit price the merchant printed,
net of discounts/surcharges, carried through for faithful display.
When omitted, consumers derive extended_amount / quantity. It is kept
as a field (not dropped as "derivable") because the printed price is
independently rounded, so the quotient can differ from what the
customer saw on the paper receipt. extended_amount remains the
authoritative line total.'
extended_amount:
type: number
description: The amount the customer paid for this line, net of any line-level
modifiers (VAT-inclusive). Authoritative for the line total.
modifiers:
type: array
description: Line-level price modifiers (discounts/surcharges) already reflected
in extended_amount.
items:
$ref: "#/components/schemas/Receipt v2.0/$defs/price_modifier_element"
tax_percentage:
type: number
tax_amount:
description: tax amount based on extended amount and tax percentage
type: number
foreign_currency:
$ref: "#/components/schemas/Receipt v2.0/$defs/foreign_currency"
required:
- sequence_number
- identifiers
- description
- quantity
- extended_amount
additionalProperties: false
return_item:
description: Defines data needed to handle returned product/service
type: object
properties:
sequence_number:
description: All items must have a unique sequence number 1,2,3 etc. Used for
internal references. Also see item_link
type: integer
item_link:
description: A reference to an other items sequence_number if a relation exists
type: integer
text:
type: string
receipt_reference:
$ref: "#/components/schemas/Receipt v2.0/$defs/extended_receipt_number_type"
identifiers:
type: array
minItems: 1
items:
$ref: "#/components/schemas/Receipt v2.0/$defs/item_identifier"
serial_number:
description: Product serial number
type: string
lot_number:
description: Specifies a specific product batch/lot
type: string
description:
type: string
quantity:
$ref: "#/components/schemas/Receipt v2.0/$defs/quantity_element"
eligible_for_frequent_shopper_points:
type: boolean
default: false
description: true if item bought is eligible for bonus
unit_cost_price:
type: number
description: The unit cost of the item to the merchant at the time of the
Transaction.
regular_sales_unit_price:
type: number
description: "Optional: the undiscounted per-unit price the merchant printed,
before any discounts or surcharges."
actual_sales_unit_price:
type: number
description: 'Optional: the authoritative per-unit price the merchant printed,
net of discounts/surcharges, carried through for faithful display.
When omitted, consumers derive extended_amount / quantity. It is kept
as a field (not dropped as "derivable") because the printed price is
independently rounded, so the quotient can differ from what the
customer saw on the paper receipt. extended_amount remains the
authoritative line total.'
extended_amount:
type: number
description: The amount the customer paid for this line, net of any line-level
modifiers (VAT-inclusive). Authoritative for the line total.
modifiers:
type: array
description: Line-level price modifiers (discounts/surcharges) already reflected
in extended_amount.
items:
$ref: "#/components/schemas/Receipt v2.0/$defs/price_modifier_element"
tax_percentage:
type: number
tax_amount:
description: tax amount based on extended amount and tax percentage
type: number
foreign_currency:
$ref: "#/components/schemas/Receipt v2.0/$defs/foreign_currency"
required:
- sequence_number
- identifiers
- description
- quantity
- extended_amount
additionalProperties: false
text_item:
description: "Text only item, example: product warranty text linked to item purchased"
type: object
properties:
sequence_number:
description: All items must have a unique sequence number 1,2,3 etc. Used for
internal references. Also see item_link
type: integer
item_link:
description: A reference to an other items sequence_number if a relation exists
type: integer
text:
type: string
required:
- sequence_number
- text
additionalProperties: false
sub_deposits_vat:
title: VAT sub deposit
description: A deposit can be divided into different VATs.
type: object
properties:
amount:
type: number
description: "Signed deposit amount for this VAT bucket: negative when it is
returned to the customer (a deposit return)"
tax_percentage:
type: number
minimum: 0
required:
- amount
- tax_percentage
additionalProperties: false
deposit_item:
description: Deposit to get or pay connected to items sold/returned
type: object
properties:
sequence_number:
description: All items must have a unique sequence number 1,2,3 etc. Used for
internal references. Also see item_link
type: integer
item_link:
description: A reference to an other items sequence_number if a relation exists
type: integer
text:
type: string
description:
type: string
unit_amount:
type: number
description: "Signed per-unit deposit amount: negative when the deposit is
returned to the customer."
amount:
type: number
description: "Signed total deposit amount (unit_amount * quantity): negative
when the deposit is returned to the customer."
quantity:
type: integer
description: Number of times deposit is applied
tax_percentage:
type: number
description: Tax on deposit is not always the same as the goods/service connected
sub_deposits:
type: array
items:
$ref: "#/components/schemas/Receipt v2.0/$defs/sub_deposits_vat"
required:
- sequence_number
- amount
- unit_amount
- quantity
additionalProperties: false
tender_cash:
title: Cash payment
description: Cash payment. Carries no additional fields; the enclosing key
identifies it.
type: object
properties: {}
additionalProperties: false
card_token_element:
title: Tokenized payment card
description: Gives a token value of the payment card and tokenizier info/scheme.
type: object
properties:
value:
type: string
description: tokenized payment card number
scheme:
type: string
description: Token scheme, vendor specific. Any unique token provider
definition, e.g. payprov_name_findity_dr
required:
- value
- scheme
additionalProperties: false
text_arr:
type: array
items:
type: string
tender_creditdebit:
title: Credit or Debit Card Tender
description: Credit or debit card payment properties
type: object
properties:
bank_identification_number:
type: string
description: ISO 8583 field 56 Payment Account Reference, masked card number
pattern: ^[A-Za-z0-9*]{0,99}$
acquiring_institution_id_code:
type: string
description: ISO 8583 field 32, Acquiring institution identification code
pattern: ^[0-9]{0,11}$
retrieval_reference_number:
type: string
description: ISO 8583 field 37, Retrieval Reference Number
pattern: ^[a-zA-Z0-9]{0,12}$
card_acceptor_id:
type: string
description: ISO 8583 field 42 Card Acceptor Identification Code
pattern: ^[a-zA-Z0-9\-]{0,15}$
card_acceptor_terminal_id:
type: string
description: ISO 8583 field 41 Card Acceptor Terminal ID
pattern: ^[a-zA-Z0-9\-]{8}$
card_acceptor_name:
type: string
description: ISO 8583 field 43 Card Acceptor Name/Location
pattern: ^[a-zA-Z0-9 .,\-/]{0,40}$
approval_code:
type: string
description: ISO 8583 field 38 Approval Code
pattern: ^[a-zA-Z0-9]{6,}$
card_token:
description: Gives a token value of the payment card and tokenizier info/scheme.
$ref: "#/components/schemas/Receipt v2.0/$defs/card_token_element"
payment_slip:
description: Payment slip data as an array of texts
$ref: "#/components/schemas/Receipt v2.0/$defs/text_arr"
additionalProperties: false
tender_barcode_element:
description: bar code representation of tender information
type: object
properties:
value:
type: string
description: the barcode value
type:
$ref: "#/components/schemas/Receipt v2.0/$defs/barcode_element"
description: the barcode type
required:
- value
- type
additionalProperties: false
tender_giftcard:
title: Giftcard payment type
description: "Gives giftcard payment info: amount (initial, current), valid
period, etc. Dates must be given in format: 2016-09-29"
type: object
properties:
card_number:
type: string
date_sold:
type: string
format: date
date_activated:
type: string
format: date
expiration_date:
type: string
format: date
initial_balance:
type: number
current_balance:
type: number
barcode:
description: barcode representation of tender details
$ref: "#/components/schemas/Receipt v2.0/$defs/tender_barcode_element"
required:
- card_number
- current_balance
additionalProperties: false
phone_number_id:
title: phone number identifer
description: more restrictive international phone number format used as
identifier, based on ITU-T E.123
type: string
pattern: ^\+(?:[0-9]\x20?){6,14}[0-9]$
tender_details:
title: Tender details
description: "Any additional payment information: free-form string key/value
pairs, plus an optional barcode representation of the details."
type: object
minProperties: 1
properties:
barcode:
description: barcode representation of tender details
$ref: "#/components/schemas/Receipt v2.0/$defs/tender_barcode_element"
additionalProperties:
type: string
tender_mobile:
title: Generic mobile payment type
description: Gives basic mobile payment information, mobile specific payment
info can be added in the tender_details section
type: object
properties:
provider:
type: string
enum:
- swish:pay
description: Mobile payment name, e.g. swish, android wallet, etc
phone:
$ref: "#/components/schemas/Receipt v2.0/$defs/phone_number_id"
tender_details:
description: any additional payment information needed
$ref: "#/components/schemas/Receipt v2.0/$defs/tender_details"
additionalProperties: false
tender_loyalty:
title: Loyalty payment
description: Loyalty payment, bonus check.
type: object
minProperties: 1
properties:
points_redeemed:
type: number
description: The number of loyalty points redeemed by the customer. Provide this
and/or amount_redeemed, depending on how the redemption is
denominated.
amount_redeemed:
type: number
description: The amount redeemed by the customer. Provide this and/or
points_redeemed, depending on how the redemption is denominated.
loyalty_program:
type: string
description: Add loyalty account data to the customer definitions
additionalProperties: false
tender_coupon:
title: Coupon payment
description: Coupon payment
type: object
properties:
name:
type: string
description: coupon name
description:
type: string
description: Any additional coupon description, if needed
coupon_code:
type: string
description: Coupon identifier
manufacture_id:
type: string
description: If a manufacture coupon
family_code:
type: string
description: Assigned by the manufacture for each product, validates that a
consumer has purchased a qualifying product
promotion_code:
type: string
description: Identifies promotion campaign
coupon_value:
type: number
description: Coupon value when redeemed
quantity:
$ref: "#/components/schemas/Receipt v2.0/$defs/quantity_element"
description: Quantity of items covered by the coupon
expiration_date:
type: string
format: date
item_links:
type: array
items:
type: integer
description: Links to sold item sequence numbers part of promotion is applicable
barcode:
description: barcode representation of tender details
$ref: "#/components/schemas/Receipt v2.0/$defs/tender_barcode_element"
required:
- coupon_code
- coupon_value
additionalProperties: false
tender_generic:
title: Generic payment type
description: Generic tender type. type names the specific generic tender; use
"other" together with type_name when none of the named types matches. Add
tender-specific payment info in the details section.
type: object
properties:
type:
type: string
enum:
- purchase_order
- accounts_receivable
- house_account
- voucher
- other
description: The specific generic tender type.
type_name:
type: string
description: Free-text name for the tender. Required when type is "other".
tender_details:
description: any additional payment information needed
$ref: "#/components/schemas/Receipt v2.0/$defs/tender_details"
anyOf:
- title: Named generic tender
properties:
type:
enum:
- purchase_order
- accounts_receivable
- house_account
- voucher
- title: Free-text tender (other + type_name)
properties:
type:
const: other
required:
- type_name
required:
- type
additionalProperties: false
tender_element:
title: Payment information
description: One or more tender types can be used. Each type is described and
the amount used for each tender type
type: object
properties:
amount:
type: number
description: "Signed amount for this tender: positive is money from the customer
to the merchant, negative is money back to the customer (a
refund/change leg)."
amount_applied_to_bill:
type: number
description: the amount applied to the transaction total
foreign_currency_amount:
$ref: "#/components/schemas/Receipt v2.0/$defs/foreign_currency"
description: Gives exchange rate etc when payment is done with a foreign currency
rounding:
type: number
description: If the amount to pay needs rounding
tender:
type: object
description: 'The payment/tender type used and its type-specific details, as a
single-key object naming the type, e.g. {"cash": {...}}. The key
implies the type, so it need not be repeated inside the value.'
minProperties: 1
maxProperties: 1
additionalProperties: false
properties:
cash:
$ref: "#/components/schemas/Receipt v2.0/$defs/tender_cash"
creditdebit:
$ref: "#/components/schemas/Receipt v2.0/$defs/tender_creditdebit"
giftcard:
$ref: "#/components/schemas/Receipt v2.0/$defs/tender_giftcard"
mobile:
$ref: "#/components/schemas/Receipt v2.0/$defs/tender_mobile"
loyalty:
$ref: "#/components/schemas/Receipt v2.0/$defs/tender_loyalty"
coupon:
$ref: "#/components/schemas/Receipt v2.0/$defs/tender_coupon"
generic:
$ref: "#/components/schemas/Receipt v2.0/$defs/tender_generic"
required:
- amount
- tender
additionalProperties: false
customer_loyalty_program:
type: object
description: Customer loyalty information
properties:
program:
type: string
description: "Loyalty program name, example: SJ Prio, ICA, SAS Eurobonus, etc.
NOTE! Named used must be approved by Findity"
level:
type: string
description: "Some programs has different levels based on point etc "
customer_number:
type: string
description: The actual loyalty number
incremental_count:
type: integer
description: Loyalty points gained/lost in transaction
current_count:
type: integer
description: Total loyalty points after increment
target_count:
type: integer
description: Loyalty points needed to achieve next goal/level
effective_date:
type: string
format: date
expiration_date:
type: string
format: date
required:
- program
- customer_number
additionalProperties: false
customer:
type: object
description: "The customer the receipt belongs to — the customer's identifiers
together with descriptive details in a single object. The identifiers
under `id` are what Kivra uses to match the receipt to a user's account,
so they must be accurate: an incorrect or missing identifier means the
receipt cannot be matched and delivered to the right user."
properties:
id:
type: object
description: Customer identifiers used to match the receipt to a Kivra user. Any
combination may be supplied; each value must be accurate, since an
incorrect identifier prevents the receipt from reaching the right
user.
minProperties: 1
properties:
service_id:
type: string
description: The digital receipt service customer identifier
email:
type: string
format: email
phone:
$ref: "#/components/schemas/Receipt v2.0/$defs/phone_number_id"
civic_registration_number:
type: string
pattern: ^[12]{1}[90]{1}[0-9]{6}-?[0-9]{4}$
description: swedish personnummer 12 digits
loyalty:
$ref: "#/components/schemas/Receipt v2.0/$defs/customer_loyalty_program"
additionalProperties: false
name:
type: string
contact:
type: object
properties:
address:
$ref: "#/components/schemas/Receipt v2.0/$defs/address"
additionalProperties: false
geo_location:
$ref: "#/components/schemas/Receipt v2.0/$defs/geo_location"
loyalty:
$ref: "#/components/schemas/Receipt v2.0/$defs/customer_loyalty_program"
additionalProperties: false
customer_information:
type: object
description: Defines customer information, like name, address, loyalty program.
properties:
name:
type: string
contact:
type: object
properties:
address:
$ref: "#/components/schemas/Receipt v2.0/$defs/address"
email:
type: string
format: email
phone:
$ref: "#/components/schemas/Receipt v2.0/$defs/phone_number"
additionalProperties: false
geo_location:
$ref: "#/components/schemas/Receipt v2.0/$defs/geo_location"
loyalty:
$ref: "#/components/schemas/Receipt v2.0/$defs/customer_loyalty_program"
additionalProperties: false
customer_order_information:
type: object
description: Use this if the receipt is connected to an order or booking.
minProperties: 1
properties:
order_number:
type: string
description: Order/booking number connected to the receipt. Provide this for a
new order/booking; for an existing order/booking being changed, use
order_reference instead.
order_reference:
type: string
description: Order/booking number connected to the receipt for an existing
order/booking when the order is changed. For a new order/booking, use
order_number instead.
customer:
$ref: "#/components/schemas/Receipt v2.0/$defs/customer_information"
description: To whom the order/order_reference belongs
additionalProperties: false
Receipt v1.1object
Digital receipt schema. The format conforms to Swedish fiscal law for cash registers (Skatteverket SKVFS 2014:9, chapter 7.1: https://www4.skatteverket.se/download/18.71e5c03417f5a7815e81e74/1647357497170/SKVFS%202014%209.pdf). Payloads can be previewed in the Merchant Toolbox https://sandbox-merchant-toolbox.kivra.com/ to verify both structure and rendering.
title: Receipt v1.1
$id: https://se.receipts.kivra.com/schemas/json/retail/v1.1
$schema: http://json-schema.org/draft-06/schema#
description: "Digital receipt schema. The format conforms to Swedish fiscal law
for cash registers (Skatteverket SKVFS 2014:9, chapter 7.1:
https://www4.skatteverket.se/download/18.71e5c03417f5a7815e81e74/164735749717\
0/SKVFS%202014%209.pdf). Payloads can be previewed in the Merchant Toolbox
https://sandbox-merchant-toolbox.kivra.com/ to verify both structure and
rendering."
type: object
properties:
copy:
type: boolean
default: false
description: If true the receipt is a copy
business_unit:
description: Merchant information
type: object
properties:
name:
type: string
service_id:
description: Id created when then business is registered in kivra
type: string
minLength: 42
maxLength: 42
pattern: ^[0-9]{10}[0-9a-fA-F]{32}$
unit_id:
type: string
description: Internal merchant shop/business unit id
organization_number:
type: string
description: Swedish organisationsnummer or vat reg number
contact:
type: object
description: Merchant contact information name, address, phone etc
properties:
address:
title: address
description: An address following the convention of
http://microformats.org/wiki/hcard
type: object
properties:
street_address:
type: string
extended_address:
type: string
post_box:
type: string
locality:
type: string
postal_code:
type: string
region:
type: string
country_name:
type: string
type:
type: object
title: address type
description: is address (physical/email) related to business, home, etc
properties:
type:
enum:
- home
- business
anyOf:
- required:
- street_address
- required:
- post_box
required:
- locality
- postal_code
email:
type: string
format: email
phone:
title: generic phone number
description: generic format for phone numbers where strict format can not be
enforced, use only for phone number to be displayed
type: string
pattern: ^(\(?((\+|(00))[0-9]{1,3})\)?)?( ?-?\(?[0-9]+\)?)+$
website:
type: string
format: uri
geo_location:
type: object
title: Geographic location (long/lat)
description: A geographical coordinate
properties:
latitude:
type: number
longitude:
type: number
required:
- latitude
- longitude
required:
- name
- service_id
- organization_number
- contact
cashier:
description: Identifies the person handling the purchase if applicable
title: cashier name and id
type: object
properties:
id:
type: string
name:
type: string
additionalProperties: false
sales_recording_system:
description: Information about the point of sales system used. The system
producing the receipt
title: sales recording system information
type: object
oneOf:
- title: point of sales system
description: information that somehow identifies the pos system
type: object
properties:
id:
type: string
name:
type: string
serial_number:
type: string
additionalProperties: false
anyOf:
- required:
- id
- required:
- name
receipt_identifier:
description: "Receipt identifiers: sequence number and/or extended number with
or without barcode representation"
title: receipt identifier
type: object
properties:
sequence_number:
type: integer
description: a sequence number as stipulated by the swedish tax authorities.
This counter resets when it reaches its maximum and is therefore not
globally unique; use extended_number to identify a receipt uniquely
within a context.
extended_number:
type: object
description: a more complex receipt number if applicable, must be unique in
given context
properties:
value:
type: string
description: data that will be presented as a barcode on the receipt
type:
type: string
enum:
- Interleaved2Of5
- EAN13
- EAN8
- Codabar
- Code39
- Code93
- Code128
- AztecCode
- Datamatrix
- PDF417
- QRCode
description: barcode representation of any data
context:
type: string
enum:
- store
- chain
- global
description: in what context is the value (receipt number) unique, note GLOBAL
can only be used if a digital receipt provider receipt id is used
required:
- value
- context
required:
- sequence_number
additionalProperties: false
time_of_purchase:
description: "ISO 8601 date/time format: YYYY-MM-DDThh:mm:ssTZD"
type: string
format: date-time
currency:
description: The receipt default currency. This gives the currency for all
amounts in the receipt. If applicable overriding currencies can be added
to the tender parts
title: ISO-4217 currency codes
type: string
pattern: ^[a-zA-Z]{3}$
totals:
description: Total amounts and types, example net, gross, vat, discount
type: array
items:
oneOf:
- title: Total discount amount
description: Total discount amount presented on the receipt
type: object
allOf:
- title: Total amounts presented on the receipt
description: One or more totals like net amount, vat, paid, discount
type: object
properties:
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: "true if amount to customer, example: on return of goods"
required:
- amount
- properties:
type:
type: string
enum:
- discount
description: "gross: total including vat."
sub_totals:
type: array
items:
anyOf:
- title: Loyalty based discount
description: Gives discount based on loyalty, connected to totals/discount
type: object
allOf:
- title: Common sub total properties
description: Common properties for all sub totals
type: object
properties:
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: "true if amount to customer, example: on return of goods"
text:
description: optional explaining text
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
required:
- amount
- properties:
type:
type: string
enum:
- loyalty
- title: Sub totals can be used on all totals if needed
description: One or more sub totals for example one for each tax percentage
type: object
allOf:
- title: Common sub total properties
description: Common properties for all sub totals
type: object
properties:
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: "true if amount to customer, example: on return of goods"
text:
description: optional explaining text
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
required:
- amount
- properties:
type:
type: string
description: Can be one of the total amount types or any other description what
the subtotal is about
required:
- type
- title: Paid total amount
description: "paid: gross amount including discount and rounding."
type: object
allOf:
- title: Total amounts presented on the receipt
description: One or more totals like net amount, vat, paid, discount
type: object
properties:
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: "true if amount to customer, example: on return of goods"
required:
- amount
- properties:
type:
type: string
enum:
- paid
sub_totals:
type: array
items:
anyOf:
- title: Amount received from customer
description: Use with total/paid if paid gives the total amount paid and the
subtotal gives what is given by customer
type: object
properties:
type:
type: string
enum:
- received
amount:
type: number
minimum: 0
text:
description: optional explaining text
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
required:
- type
- amount
additionalProperties: false
- title: Returned sub total
description: Use with total/paid if paid gives the total amount paid and the
subtotal gives what is returned to customer
type: object
properties:
type:
type: string
enum:
- returned
amount:
type: number
minimum: 0
text:
description: optional explaining text
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
required:
- type
- amount
additionalProperties: false
required:
- type
- title: Total gross amount presented on the receipt
description: "gross: total including vat, excluding discounts"
type: object
allOf:
- title: Total amounts presented on the receipt
description: One or more totals like net amount, vat, paid, discount
type: object
properties:
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: "true if amount to customer, example: on return of goods"
required:
- amount
- properties:
type:
type: string
enum:
- gross
description: "gross: total including vat."
sub_totals:
type: array
items:
anyOf:
- title: Sub totals can be used on all totals if needed
description: One or more sub totals eligible for bonus
type: object
allOf:
- title: Common sub total properties
description: Common properties for all sub totals
type: object
properties:
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: "true if amount to customer, example: on return of goods"
text:
description: optional explaining text
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
required:
- amount
- properties:
type:
type: string
enum:
- eligible_for_frequent_shopper_points
points:
type: integer
minimum: 0
description: loyalty points gained/lost in transaction
- title: Sub totals can be used on all totals if needed
description: One or more sub totals for example one for each tax percentage
type: object
allOf:
- title: Common sub total properties
description: Common properties for all sub totals
type: object
properties:
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: "true if amount to customer, example: on return of goods"
text:
description: optional explaining text
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
required:
- amount
- properties:
type:
type: string
description: Can be one of the total amount types or any other description what
the subtotal is about
required:
- type
- title: Total tax amount presented on the receipt
description: Tax releated total
type: object
properties:
type:
type: string
enum:
- vat
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: "true if amount to customer, example: on return of goods"
sub_totals:
type: array
description: add sub total for each tax percentage used
items:
title: Sub totals can be used on all totals but is mostly used on VAT
description: One or more sub totals, one for each tax percentage
type: object
properties:
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: "true if amount to customer, example: on return of goods"
taxable_amount:
description: Amount including tax amount
type: number
minimum: 0
net_amount:
description: Amount excluding tax amount
type: number
minimum: 0
tax_percentage:
type: number
minimum: 0
required:
- amount
- taxable_amount
- net_amount
- tax_percentage
required:
- type
- amount
additionalProperties: false
- title: Total loyalty points redeemed
description: One or more totals on loyalty points/programs
type: object
properties:
type:
type: string
enum:
- loyalty
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: "true if amount to customer, example: on return of goods"
required:
- type
- amount
additionalProperties: false
- title: Total net or rounding amounts presented on the receipt
description: One or more totals of type net amount or rounding
type: object
allOf:
- title: Total amounts presented on the receipt
description: One or more totals like net amount, vat, paid, discount
type: object
properties:
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: "true if amount to customer, example: on return of goods"
required:
- amount
- properties:
type:
type: string
enum:
- net
- rounding
description: "net: total including discounts, excluding tax."
sub_totals:
type: array
items:
anyOf:
- title: Sub totals can be used on all totals if needed
description: One or more sub totals for example one for each tax percentage
type: object
allOf:
- title: Common sub total properties
description: Common properties for all sub totals
type: object
properties:
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: "true if amount to customer, example: on return of goods"
text:
description: optional explaining text
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
required:
- amount
- properties:
type:
type: string
description: Can be one of the total amount types or any other description what
the subtotal is about
required:
- type
header_text:
description: Any textual information aimed for the receipt header
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
footer_text:
description: Any textual information aimed for the receipt footer
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
items:
description: List of receipt items, goods or services sold/returned
type: array
items:
oneOf:
- description: Defines data needed to handle sold product/service
allOf:
- description: Item sold by the merchant
type: object
properties:
type:
type: string
enum:
- sale
required:
- type
- title: Item definition
description: Item and/or service description
type: object
minProperties: 1
properties:
identifiers:
type: array
minItems: 1
items:
title: Item identifier
description: "Identifier for an item being sold or returned. Supported types:
'pos' (Point of Sale identifier) and 'gtin' (Global Trade
Item Number)."
type: object
properties:
identifier_type:
type: string
enum:
- pos
- gtin
value:
type: string
required:
- identifier_type
- value
serial_number:
description: Product serial number
type: string
lot_number:
description: Specifies a specific product batch/lot
type: string
description:
type: string
quantity:
type: object
properties:
value:
type: number
unit:
type: string
enum:
- ea
- 6 pack
- 12 pack
- 24 pack
- kg
- grm
- km
- m
- cm
- mm
- annual
- days
- hours
- seconds
- l
- gallon
entry_method:
type: string
enum:
- smartcard
- micr
- msr
- keyed
- scanned
- weighed
- measured
- rfid
- automatic
- integrated_chip_card
- tapped
- waved
default: scanned
required:
- value
- unit
entry_method:
type: string
enum:
- smartcard
- micr
- msr
- keyed
- scanned
- weighed
- measured
- rfid
- automatic
- integrated_chip_card
- tapped
- waved
default: scanned
eligible_for_frequent_shopper_points:
type: boolean
default: false
description: true if item bought is eligible for bonus
required:
- identifiers
- description
- quantity
- title: Common item properties
description: Common item properties for ordering and navigation
type: object
minProperties: 1
properties:
sequence_number:
description: All items must have a unique sequence number 1,2,3 etc. Used for
internal references. Also see item_link
type: integer
item_link:
description: A reference to an other items sequence_number if a relation exists
type: integer
text:
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
required:
- sequence_number
oneOf:
- type: object
properties:
unit_cost_price:
type: number
description: The unit cost of the item to the mechant at the time of the
Transaction.
regular_sales_unit_price:
type: number
description: The per-unit price for the item/service before any discounts or
surcharges have been applied.
extended_gross_amount:
type: number
description: The amount this item sells for excluding discounts. It is the
regular_sales_unit_price times the quantity
actual_sales_unit_price:
type: number
description: The amount a single item sold for taking into account discounts and
surcharges. The amount charged the customer
(extended_amount) takes into account this number times
quantity
extended_amount:
type: number
description: The actual amount this item sells for. It is the
actual_sales_unit_price times the quantity taking into
account any retail price modifiers
retail_price_modifiers:
type: array
items:
title: Retail price modifier
description: Specifies any modifier to a service/item price on a specific line
item, e.g. discount, deposit
type: object
properties:
action:
enum:
- add
- subtract
- replace
description: Tells whether to add, subtract or replace the modifier to/from he
sales amount.
default: subtract
unit_amount:
type: number
description: The unit refund for the modifier.
amount:
type: number
minimum: 0
description: Total modifier amount, that is unit_amount * quantity
percent:
type: number
minimum: 0
quantity:
description: "How many times is the modifier used. Might no be the same as
number of items/services bought. Example: 2 coupons '3
for 2' on six items. Item quantity == 6, modifier
quantity == 2"
type: integer
minimum: 1
description:
description: modifier reason
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
tax_percentage:
type: number
description: If the modifier has another tax percentage than the item/service
amount it affects
required:
- amount
extended_discount_amount:
type: number
description: The total discount applied to this item
tax_percentage:
type: number
tax_amount:
description: tax amount based on extended amount and tex percentage
type: number
foreign_currency:
title: Foreign currency
description: Gives exchange rate etc when payment is done with a foreign
currency
type: object
properties:
currency:
description: ISO 4217 foreign currency code
title: ISO-4217 currency codes
type: string
pattern: ^[a-zA-Z]{3}$
original_face_amount:
description: the original amount in the foreign currency the being converted to
local currency. For example, converting Yen to Dollars,
this amount would be the amount of Yen
type: number
minimum: 0
exchange_rate:
type: number
minimum: 0
required:
- currency
- original_face_amount
required:
- actual_sales_unit_price
- extended_amount
- extended_gross_amount
- description: Amount in loyalty program points
type: object
properties:
points:
type: number
description: cost for goods/service as number of loyalty points
required:
- points
- description: Defines data needed to handle returned product/service
allOf:
- description: Item returned to the merchant
type: object
properties:
type:
type: string
enum:
- return
receipt_reference:
type: object
description: a more complex receipt number if applicable, must be unique in
given context. Links a return receipt to its original sale
receipt (typically the sale's extended_number value); if
omitted the return receipt is standalone and not linked to a
sale.
properties:
value:
type: string
description: data that will be presented as a barcode on the receipt
type:
type: string
enum:
- Interleaved2Of5
- EAN13
- EAN8
- Codabar
- Code39
- Code93
- Code128
- AztecCode
- Datamatrix
- PDF417
- QRCode
description: barcode representation of any data
context:
type: string
enum:
- store
- chain
- global
description: in what context is the value (receipt number) unique, note GLOBAL
can only be used if a digital receipt provider receipt
id is used
required:
- value
- context
required:
- type
- title: Item definition
description: Item and/or service description
type: object
minProperties: 1
properties:
identifiers:
type: array
minItems: 1
items:
title: Item identifier
description: "Identifier for an item being sold or returned. Supported types:
'pos' (Point of Sale identifier) and 'gtin' (Global Trade
Item Number)."
type: object
properties:
identifier_type:
type: string
enum:
- pos
- gtin
value:
type: string
required:
- identifier_type
- value
serial_number:
description: Product serial number
type: string
lot_number:
description: Specifies a specific product batch/lot
type: string
description:
type: string
quantity:
type: object
properties:
value:
type: number
unit:
type: string
enum:
- ea
- 6 pack
- 12 pack
- 24 pack
- kg
- grm
- km
- m
- cm
- mm
- annual
- days
- hours
- seconds
- l
- gallon
entry_method:
type: string
enum:
- smartcard
- micr
- msr
- keyed
- scanned
- weighed
- measured
- rfid
- automatic
- integrated_chip_card
- tapped
- waved
default: scanned
required:
- value
- unit
entry_method:
type: string
enum:
- smartcard
- micr
- msr
- keyed
- scanned
- weighed
- measured
- rfid
- automatic
- integrated_chip_card
- tapped
- waved
default: scanned
eligible_for_frequent_shopper_points:
type: boolean
default: false
description: true if item bought is eligible for bonus
required:
- identifiers
- description
- quantity
- title: Common item properties
description: Common item properties for ordering and navigation
type: object
minProperties: 1
properties:
sequence_number:
description: All items must have a unique sequence number 1,2,3 etc. Used for
internal references. Also see item_link
type: integer
item_link:
description: A reference to an other items sequence_number if a relation exists
type: integer
text:
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
required:
- sequence_number
oneOf:
- type: object
properties:
unit_cost_price:
type: number
description: The unit cost of the item to the mechant at the time of the
Transaction.
regular_sales_unit_price:
type: number
description: The per-unit price for the item/service before any discounts or
surcharges have been applied.
extended_gross_amount:
type: number
description: The amount this item sells for excluding discounts. It is the
regular_sales_unit_price times the quantity
actual_sales_unit_price:
type: number
description: The amount a single item sold for taking into account discounts and
surcharges. The amount charged the customer
(extended_amount) takes into account this number times
quantity
extended_amount:
type: number
description: The actual amount this item sells for. It is the
actual_sales_unit_price times the quantity taking into
account any retail price modifiers
retail_price_modifiers:
type: array
items:
title: Retail price modifier
description: Specifies any modifier to a service/item price on a specific line
item, e.g. discount, deposit
type: object
properties:
action:
enum:
- add
- subtract
- replace
description: Tells whether to add, subtract or replace the modifier to/from he
sales amount.
default: subtract
unit_amount:
type: number
description: The unit refund for the modifier.
amount:
type: number
minimum: 0
description: Total modifier amount, that is unit_amount * quantity
percent:
type: number
minimum: 0
quantity:
description: "How many times is the modifier used. Might no be the same as
number of items/services bought. Example: 2 coupons '3
for 2' on six items. Item quantity == 6, modifier
quantity == 2"
type: integer
minimum: 1
description:
description: modifier reason
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
tax_percentage:
type: number
description: If the modifier has another tax percentage than the item/service
amount it affects
required:
- amount
extended_discount_amount:
type: number
description: The total discount applied to this item
tax_percentage:
type: number
tax_amount:
description: tax amount based on extended amount and tex percentage
type: number
foreign_currency:
title: Foreign currency
description: Gives exchange rate etc when payment is done with a foreign
currency
type: object
properties:
currency:
description: ISO 4217 foreign currency code
title: ISO-4217 currency codes
type: string
pattern: ^[a-zA-Z]{3}$
original_face_amount:
description: the original amount in the foreign currency the being converted to
local currency. For example, converting Yen to Dollars,
this amount would be the amount of Yen
type: number
minimum: 0
exchange_rate:
type: number
minimum: 0
required:
- currency
- original_face_amount
required:
- actual_sales_unit_price
- extended_amount
- extended_gross_amount
- description: Amount in loyalty program points
type: object
properties:
points:
type: number
description: cost for goods/service as number of loyalty points
required:
- points
- allOf:
- description: "Text only item, example: product warranty text linked to item
purchased"
type: object
properties:
type:
type: string
enum:
- text
text:
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
required:
- type
- text
- title: Common item properties
description: Common item properties for ordering and navigation
type: object
minProperties: 1
properties:
sequence_number:
description: All items must have a unique sequence number 1,2,3 etc. Used for
internal references. Also see item_link
type: integer
item_link:
description: A reference to an other items sequence_number if a relation exists
type: integer
text:
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
required:
- sequence_number
- description: Deposit to get or pay connected to items sold/returned
type: object
allOf:
- properties:
type:
type: string
enum:
- deposit
description:
type: string
unit_amount:
type: number
description: The unit cost/refund for goods/service deposit.
amount:
type: number
description: Total cost/refund for goods/service deposit, unit_amount * quantity
quantity:
type: integer
description: Number of times deposit is applied
refund:
type: boolean
description: True if amount goes to customer, false otherwise
tax_percentage:
type: number
description: Tax on deposit is not always the same as the goods/service
connected
sub_deposits:
type: array
items:
title: VAT sub deposit
description: A desposit can be devided into different VATs
type: object
properties:
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: true if amount to customer, a deposit return
tax_percentage:
type: number
minimum: 0
required:
- amount
- tax_percentage
required:
- type
- refund
- amount
- unit_amount
- quantity
- title: Common item properties
description: Common item properties for ordering and navigation
type: object
minProperties: 1
properties:
sequence_number:
description: All items must have a unique sequence number 1,2,3 etc. Used for
internal references. Also see item_link
type: integer
item_link:
description: A reference to an other items sequence_number if a relation exists
type: integer
text:
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
required:
- sequence_number
retail_price_modifiers:
type: array
description: "Specifies any modifier(s) related to the amount paid by the
customer. Example: 5% discount on the total amount"
items:
title: Retail price modifier
description: Specifies any modifier to a service/item price on a more general
receipt level or connected to a specific item/service
type: object
allOf:
- properties:
item_links:
type: array
items:
type: integer
description: Reference to sale/return item sequence_number if applicable
- title: Retail price modifier
description: Specifies any modifier to a service/item price on a specific line
item, e.g. discount, deposit
type: object
properties:
action:
enum:
- add
- subtract
- replace
description: Tells whether to add, subtract or replace the modifier to/from he
sales amount.
default: subtract
unit_amount:
type: number
description: The unit refund for the modifier.
amount:
type: number
minimum: 0
description: Total modifier amount, that is unit_amount * quantity
percent:
type: number
minimum: 0
quantity:
description: "How many times is the modifier used. Might no be the same as
number of items/services bought. Example: 2 coupons '3 for 2' on
six items. Item quantity == 6, modifier quantity == 2"
type: integer
minimum: 1
description:
description: modifier reason
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
tax_percentage:
type: number
description: If the modifier has another tax percentage than the item/service
amount it affects
required:
- amount
payments:
description: Tender related information, several tender types can be used for payment
type: array
items:
title: Payment information
description: One or more tender types can be used. Each type is described and
the amount used for each tender type
type: object
properties:
amount:
type: number
amount_applied_to_bill:
type: number
description: the amount applied to the transaction total
foreign_currency_amount:
description: Gives exchange rate etc when payment is done with a foreign currency
title: Foreign currency
type: object
properties:
currency:
description: ISO 4217 foreign currency code
title: ISO-4217 currency codes
type: string
pattern: ^[a-zA-Z]{3}$
original_face_amount:
description: the original amount in the foreign currency the being converted to
local currency. For example, converting Yen to Dollars, this
amount would be the amount of Yen
type: number
minimum: 0
exchange_rate:
type: number
minimum: 0
required:
- currency
- original_face_amount
rounding:
type: number
description: If the amount to pay needs rounding
refund:
type: boolean
default: false
description: True if customer is given a refund or change
tender:
type: object
description: Gives the payment/tender type used and payment/tender specific
information
oneOf:
- title: Cash payment
description: Cash payment
type: object
properties:
type:
type: string
enum:
- cash
required:
- type
additionalProperties: false
- title: Credit or Debit Card Tender
description: Credit or debit card payment properties
type: object
properties:
type:
type: string
enum:
- creditdebit
bank_identification_number:
type: string
description: ISO 8583 field 56 Payment Account Reference, masked card number
pattern: ^[A-Za-z0-9*]{0,99}$
acquiring_institution_id_code:
type: string
description: ISO 8583 field 32, Acquiring institution identification code
pattern: ^[0-9]{0,11}$
retrieval_reference_number:
type: string
description: ISO 8583 field 37, Retrieval Reference Number
pattern: ^[a-zA-Z0-9]{0,12}$
card_acceptor_id:
type: string
description: ISO 8583 field 42 Card Acceptor Identification Code
pattern: ^[a-zA-Z0-9\-]{0,15}$
card_acceptor_terminal_id:
type: string
description: ISO 8583 field 41 Card Acceptor Terminal ID
pattern: ^[a-zA-Z0-9\-]{8}$
merchant_identifier:
type: string
description: ISO 8583 field 42 Card Acceptor Identification Code, Deprecated,
use card_acceptor_id
pattern: \w{0,15}
card_acceptor_name:
type: string
description: ISO 8583 field 43 Card Acceptor Name/Location
pattern: ^[a-zA-Z0-9 .,\-/]{0,40}$
approval_code:
type: string
description: ISO 8583 field 38 Approval Code
pattern: ^[a-zA-Z0-9]{6,}$
card_token:
description: Gives a token value of the payment card and tokenizier info/scheme.
title: Tokenized payment card
type: object
properties:
value:
type: string
description: tokenized payment card number
scheme:
type: string
description: Token scheme, vendor specific. Any unique token provider
definition, e.g. payprov_name_findity_dr
required:
- value
- scheme
payment_slip:
description: Payment slip data as an array of texts
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
required:
- type
additionalProperties: false
- title: Giftcard payment type
description: "Gives giftcard payment info: amount (initial, current), valid
period, etc. Dates must be given in format: 2016-09-29"
type: object
properties:
type:
type: string
enum:
- giftcard
card_number:
type: string
date_sold:
type: string
format: date
date_activated:
type: string
format: date
expiration_date:
type: string
format: date
initial_balance:
type: number
current_balance:
type: number
barcode:
description: barcode representation of tender details
properties:
value:
type: string
description: the barcode value
type:
description: the barcode type
type: string
enum:
- Interleaved2Of5
- EAN13
- EAN8
- Codabar
- Code39
- Code93
- Code128
- AztecCode
- Datamatrix
- PDF417
- QRCode
required:
- value
- type
additionalProperties: false
required:
- type
- card_number
- current_balance
additionalProperties: false
- title: Generic mobile payment type
description: Gives basic mobile payment information, mobile specific payment
info can be added in the tender_details section
type: object
properties:
type:
type: string
enum:
- mobile
provider:
type: string
enum:
- swish:pay
description: Mobile payment name, e.g. swish, android wallet, etc
phone:
title: phone number identifer
description: more restrictive international phone number format used as
identifier, based on ITU-T E.123
type: string
pattern: ^\+(?:[0-9]\x20?){6,14}[0-9]$
tender_details:
description: any aditional payment information needed
allOf:
- description: Generic text collection type used where additional text is needed
in a structured (key/value) or unstructured way
oneOf:
- type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
- type: object
description: Add any key-value pair (string based properties) to this collection
properties:
type:
type: string
enum:
- map
collection: {}
required:
- type
- collection
additionalProperties: false
- properties:
barcode:
description: barcode representation of tender details
properties:
value:
type: string
description: the barcode value
type:
description: the barcode type
type: string
enum:
- Interleaved2Of5
- EAN13
- EAN8
- Codabar
- Code39
- Code93
- Code128
- AztecCode
- Datamatrix
- PDF417
- QRCode
required:
- value
- type
additionalProperties: false
required:
- type
additionalProperties: false
- title: Loyalty payment
description: Loyalty payment, bonus check
type: object
properties:
type:
type: string
enum:
- loyalty
points_redeemed:
type: number
description: The number of loyalty points redeemed by the customer
amount_redeemed:
type: number
description: The amount redeemed by the customer
loyalty_program:
type: string
description: Add loyalty account data to the customer defintions
anyOf:
- required:
- points_redeemed
- required:
- amount_redeemed
required:
- type
additionalProperties: false
- title: Coupon payment
description: Coupon payment
type: object
properties:
type:
type: string
enum:
- coupon
name:
type: string
description: coupon name
description:
type: string
description: Any additional coupon description, if needed
coupon_code:
type: string
description: Coupon identifier
manufacture_id:
type: string
description: If a manufacture coupon
family_code:
type: string
description: Assigned by the manufacture for each product, validates that a
consumer has purchased a qualifying product
promotion_code:
type: string
description: Identifies promotion campaign
coupon_value:
type: number
description: Coupon value when redeemed
quantity:
description: Quantity of items covered by the coupon
type: object
properties:
value:
type: number
unit:
type: string
enum:
- ea
- 6 pack
- 12 pack
- 24 pack
- kg
- grm
- km
- m
- cm
- mm
- annual
- days
- hours
- seconds
- l
- gallon
entry_method:
type: string
enum:
- smartcard
- micr
- msr
- keyed
- scanned
- weighed
- measured
- rfid
- automatic
- integrated_chip_card
- tapped
- waved
default: scanned
required:
- value
- unit
expiration_date:
type: string
format: date
item_links:
type: array
items:
type: integer
description: Links to sold item sequence numbers part of promotion is applicable
barcode:
description: barcode representation of tender details
properties:
value:
type: string
description: the barcode value
type:
description: the barcode type
type: string
enum:
- Interleaved2Of5
- EAN13
- EAN8
- Codabar
- Code39
- Code93
- Code128
- AztecCode
- Datamatrix
- PDF417
- QRCode
required:
- value
- type
additionalProperties: false
required:
- type
- coupon_code
- coupon_value
additionalProperties: false
- title: Generic payment type
description: Generic tendertype. Use other+type_name if no other payment type
matches. Add tender specific payment in the details section
type: object
oneOf:
- properties:
type:
type: string
enum:
- purchase_order
- accounts_receivable
- house_account
- voucher
tender_details:
type: object
description: any aditional payment information needed
allOf:
- type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
- properties:
barcode:
description: barcode representation of tender details
properties:
value:
type: string
description: the barcode value
type:
description: the barcode type
type: string
enum:
- Interleaved2Of5
- EAN13
- EAN8
- Codabar
- Code39
- Code93
- Code128
- AztecCode
- Datamatrix
- PDF417
- QRCode
required:
- value
- type
additionalProperties: false
required:
- type
additionalProperties: false
- properties:
type:
type: string
enum:
- other
type_name:
type: string
description: other
tender_details:
type: object
description: any aditional payment information needed
allOf:
- type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
- properties:
barcode:
description: barcode representation of tender details
properties:
value:
type: string
description: the barcode value
type:
description: the barcode type
type: string
enum:
- Interleaved2Of5
- EAN13
- EAN8
- Codabar
- Code39
- Code93
- Code128
- AztecCode
- Datamatrix
- PDF417
- QRCode
required:
- value
- type
additionalProperties: false
required:
- type
- type_name
additionalProperties: false
required:
- amount
- tender
additionalProperties: false
customer:
description: Information and/or identification of the customer. Not required
when the customer is identified via a card token (see
payments.tender.creditdebit.card_token), nor for greenbin / retained
(anonymous) receipts.
anyOf:
- type: object
description: Defines valid customer identifiers
properties:
id:
type: object
oneOf:
- type: object
description: The digital receipt service customer identifier
properties:
service_id:
type: string
required:
- service_id
additionalProperties: false
- type: object
description: The customer email address
properties:
email:
type: string
format: email
required:
- email
additionalProperties: false
- type: object
description: The customer phone number
properties:
phone:
title: phone number identifer
description: more restrictive international phone number format used as
identifier, based on ITU-T E.123
type: string
pattern: ^\+(?:[0-9]\x20?){6,14}[0-9]$
required:
- phone
additionalProperties: false
- type: object
description: The customer ssn
properties:
civic_registration_number:
type: string
pattern: ^[12]{1}[90]{1}[0-9]{6}-?[0-9]{4}$
description: swedish personnummer 12 digits
required:
- civic_registration_number
additionalProperties: false
- type: object
description: Use loyalty program name and customer loyalty number as identifier
properties:
loyalty:
type: object
description: Customer loyalty information
properties:
program:
type: string
description: "Loyalty program name, example: SJ Prio, ICA, SAS Eurobonus, etc.
NOTE! Named used must be approved by Findity"
level:
type: string
description: "Some programs has different levels based on point etc "
customer_number:
type: string
description: The actual loyalty number
incremental_count:
type: integer
description: Loyalty points gained/lost in transaction
current_count:
type: integer
description: Total loyalty points after increment
target_count:
type: integer
description: Loyalty points needed to achieve next goal/level
effective_date:
type: string
format: date
expiration_date:
type: string
format: date
required:
- program
- customer_number
required:
- loyalty
- type: object
description: Defines customer information, like name, address, loyalty program.
properties:
name:
type: string
contact:
type: object
properties:
address:
title: address
description: An address following the convention of
http://microformats.org/wiki/hcard
type: object
properties:
street_address:
type: string
extended_address:
type: string
post_box:
type: string
locality:
type: string
postal_code:
type: string
region:
type: string
country_name:
type: string
type:
type: object
title: address type
description: is address (physical/email) related to business, home, etc
properties:
type:
enum:
- home
- business
anyOf:
- required:
- street_address
- required:
- post_box
required:
- locality
- postal_code
email:
type: string
format: email
phone:
title: generic phone number
description: generic format for phone numbers where strict format can not be
enforced, use only for phone number to be displayed
type: string
pattern: ^(\(?((\+|(00))[0-9]{1,3})\)?)?( ?-?\(?[0-9]+\)?)+$
additionalProperties: false
geo_location:
type: object
title: Geographic location (long/lat)
description: A geographical coordinate
properties:
latitude:
type: number
longitude:
type: number
required:
- latitude
- longitude
loyalty:
type: object
description: Customer loyalty information
properties:
program:
type: string
description: "Loyalty program name, example: SJ Prio, ICA, SAS Eurobonus, etc.
NOTE! Named used must be approved by Findity"
level:
type: string
description: "Some programs has different levels based on point etc "
customer_number:
type: string
description: The actual loyalty number
incremental_count:
type: integer
description: Loyalty points gained/lost in transaction
current_count:
type: integer
description: Total loyalty points after increment
target_count:
type: integer
description: Loyalty points needed to achieve next goal/level
effective_date:
type: string
format: date
expiration_date:
type: string
format: date
required:
- program
- customer_number
additionalProperties: false
customer_order:
description: Information about a connected customer order if applicable
type: object
properties:
order_number:
type: string
description: Order/booking number connected to receipt on new order/booking
order_reference:
type: string
description: Order/booking number connected to receipt on existing order/booking
when the order is changed.
customer:
description: To whom the order/order_reference belongs
type: object
properties:
name:
type: string
contact:
type: object
properties:
address:
title: address
description: An address following the convention of
http://microformats.org/wiki/hcard
type: object
properties:
street_address:
type: string
extended_address:
type: string
post_box:
type: string
locality:
type: string
postal_code:
type: string
region:
type: string
country_name:
type: string
type:
type: object
title: address type
description: is address (physical/email) related to business, home, etc
properties:
type:
enum:
- home
- business
anyOf:
- required:
- street_address
- required:
- post_box
required:
- locality
- postal_code
email:
type: string
format: email
phone:
title: generic phone number
description: generic format for phone numbers where strict format can not be
enforced, use only for phone number to be displayed
type: string
pattern: ^(\(?((\+|(00))[0-9]{1,3})\)?)?( ?-?\(?[0-9]+\)?)+$
additionalProperties: false
geo_location:
type: object
title: Geographic location (long/lat)
description: A geographical coordinate
properties:
latitude:
type: number
longitude:
type: number
required:
- latitude
- longitude
loyalty:
type: object
description: Customer loyalty information
properties:
program:
type: string
description: "Loyalty program name, example: SJ Prio, ICA, SAS Eurobonus, etc.
NOTE! Named used must be approved by Findity"
level:
type: string
description: "Some programs has different levels based on point etc "
customer_number:
type: string
description: The actual loyalty number
incremental_count:
type: integer
description: Loyalty points gained/lost in transaction
current_count:
type: integer
description: Total loyalty points after increment
target_count:
type: integer
description: Loyalty points needed to achieve next goal/level
effective_date:
type: string
format: date
expiration_date:
type: string
format: date
required:
- program
- customer_number
additionalProperties: false
oneOf:
- required:
- order_number
- required:
- order_reference
additionalProperties: false
control_unit:
description: "Control unit information required by swedish tax authorities. The
control unit (Swedish: kontrollenhet) is required when a control unit is
connected to the POS."
type: object
properties:
id:
type: string
code:
type: string
required:
- id
required:
- business_unit
- sales_recording_system
- receipt_identifier
- time_of_purchase
- currency
- totals
- items
- payments
additionalProperties: false
Prescription v1.0object
Prescription specification issued by pharmacies and connected to a receipt in Kivra. The format is based on discussions with pharmacies and data from the Swedish eHealth Agency. Version 1.0 — first release 2025-03-11.
title: Prescription v1.0
$id: https://se.kivra.com/schemas/json/retail/ps/v1.0
$schema: http://json-schema.org/draft-07/schema#
description: Prescription specification issued by pharmacies and connected to a
receipt in Kivra. The format is based on discussions with pharmacies and data
from the Swedish eHealth Agency. Version 1.0 — first release 2025-03-11.
type: object
properties:
business_unit:
description: Merchant information (the pharmacy issuing the specification).
type: object
properties:
name:
type: string
service_id:
description: Id created when then business is registered in kivra
type: string
minLength: 42
maxLength: 42
pattern: ^[0-9]{10}[0-9a-fA-F]{32}$
unit_id:
type: string
description: Internal merchant shop/business unit id
organization_number:
type: string
description: Swedish organisationsnummer or vat reg number
contact:
type: object
description: Merchant contact information name, address, phone etc
properties:
address:
title: address
description: An address following the convention of
http://microformats.org/wiki/hcard
type: object
properties:
street_address:
type: string
extended_address:
type: string
post_box:
type: string
locality:
type: string
postal_code:
type: string
region:
type: string
country_name:
type: string
type:
type: object
title: address type
description: is address (physical/email) related to business, home, etc
properties:
type:
enum:
- home
- business
anyOf:
- required:
- street_address
- required:
- post_box
required:
- locality
- postal_code
email:
type: string
format: email
phone:
title: generic phone number
description: generic format for phone numbers where strict format can not be
enforced, use only for phone number to be displayed
type: string
pattern: ^(\(?((\+|(00))[0-9]{1,3})\)?)?( ?-?\(?[0-9]+\)?)+$
website:
type: string
format: uri
geo_location:
type: object
title: Geographic location (long/lat)
description: A geographical coordinate
properties:
latitude:
type: number
longitude:
type: number
required:
- latitude
- longitude
required:
- name
- service_id
- organization_number
- contact
cashier:
description: Identifies the person handling the purchase if applicable
title: cashier name and id
type: object
properties:
id:
type: string
name:
type: string
additionalProperties: false
receipt_identifier:
description: "Receipt identifiers: sequence number and/or extended number with
or without barcode representation"
title: receipt identifier
type: object
properties:
sequence_number:
type: integer
description: a sequence number as stipulated by the swedish tax authorities, not
mandatory for PS.
extended_number:
type: object
description: a more complex receipt number if applicable, must be unique in
given context
properties:
value:
type: string
description: data that will be presented as a barcode on the receipt
type:
type: string
enum:
- Interleaved2Of5
- EAN13
- EAN8
- Codabar
- Code39
- Code93
- Code128
- AztecCode
- Datamatrix
- PDF417
- QRCode
description: barcode representation of any data
context:
type: string
enum:
- store
- chain
- global
description: in what context is the value (receipt number) unique, note GLOBAL
can only be used if a digital receipt provider receipt id is used
required:
- value
- context
required:
- extended_number
additionalProperties: false
time_of_purchase:
description: "ISO 8601 date/time format: YYYY-MM-DDThh:mm:ssTZD"
type: string
format: date-time
currency:
description: The receipt default currency. This gives the currency for all
amounts in the receipt. If applicable overriding currencies can be added
to the tender parts
title: ISO-4217 currency codes
type: string
pattern: ^[a-zA-Z]{3}$
amount_with_benefit:
description: Amount with the high-cost benefit applied. Human prescriptions
only; usually equals amount_paid_by_benefit but differs when insurances
are involved.
type: number
minimum: 0
amount_without_benefit:
description: Amount without the high-cost benefit. Given on both animal and
human prescriptions.
type: number
minimum: 0
amount_paid_by_benefit:
description: Amount paid by the high-cost benefit. Human prescriptions only;
usually equals amount_with_benefit but differs when insurances are
involved.
type: number
minimum: 0
amount_to_pay:
description: Final amount the customer pays. Given on both animal and human
prescriptions.
type: number
minimum: 0
totals:
description: Total amounts and types, for example vat, gross, paid. Included
when the prescription contains goods/services the customer pays tax on;
the VAT is then added here.
type: array
items:
oneOf:
- title: Paid total amount
description: "paid: gross amount including discount and rounding."
type: object
allOf:
- title: Total amounts presented on the receipt
description: One or more totals like net amount, vat, paid, discount
type: object
properties:
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: "true if amount to customer, example: on return of goods"
required:
- amount
- properties:
type:
type: string
enum:
- paid
sub_totals:
type: array
items:
anyOf:
- title: Amount received from customer
description: Use with total/paid if paid gives the total amount paid and the
subtotal gives what is given by customer
type: object
properties:
type:
type: string
enum:
- received
amount:
type: number
minimum: 0
text:
description: optional explaining text
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
required:
- type
- amount
additionalProperties: false
- title: Returned sub total
description: Use with total/paid if paid gives the total amount paid and the
subtotal gives what is returned to customer
type: object
properties:
type:
type: string
enum:
- returned
amount:
type: number
minimum: 0
text:
description: optional explaining text
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
required:
- type
- amount
additionalProperties: false
required:
- type
- title: Total gross amount presented on the receipt
description: "gross: total including vat, excluding discounts"
type: object
allOf:
- title: Total amounts presented on the receipt
description: One or more totals like net amount, vat, paid, discount
type: object
properties:
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: "true if amount to customer, example: on return of goods"
required:
- amount
- properties:
type:
type: string
enum:
- gross
description: "gross: total including vat."
sub_totals:
type: array
items:
anyOf:
- title: Sub totals can be used on all totals if needed
description: One or more sub totals eligible for bonus
type: object
allOf:
- title: Common sub total properties
description: Common properties for all sub totals
type: object
properties:
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: "true if amount to customer, example: on return of goods"
text:
description: optional explaining text
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
required:
- amount
- properties:
type:
type: string
enum:
- eligible_for_frequent_shopper_points
points:
type: integer
minimum: 0
description: loyalty points gained/lost in transaction
- title: Sub totals can be used on all totals if needed
description: One or more sub totals for example one for each tax percentage
type: object
allOf:
- title: Common sub total properties
description: Common properties for all sub totals
type: object
properties:
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: "true if amount to customer, example: on return of goods"
text:
description: optional explaining text
type: object
properties:
type:
type: string
enum:
- array
collection:
type: array
description: Arbitray array of strings used where additional info needed at some
part
items:
type: string
required:
- type
- collection
required:
- amount
- properties:
type:
type: string
description: Can be one of the total amount types or any other description what
the subtotal is about
required:
- type
- title: Total tax amount presented on the receipt
description: Tax releated total
type: object
properties:
type:
type: string
enum:
- vat
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: "true if amount to customer, example: on return of goods"
sub_totals:
type: array
description: add sub total for each tax percentage used
items:
title: Sub totals can be used on all totals but is mostly used on VAT
description: One or more sub totals, one for each tax percentage
type: object
properties:
amount:
type: number
minimum: 0
refund:
type: boolean
default: false
description: "true if amount to customer, example: on return of goods"
taxable_amount:
description: Amount including tax amount
type: number
minimum: 0
net_amount:
description: Amount excluding tax amount
type: number
minimum: 0
tax_percentage:
type: number
minimum: 0
required:
- amount
- taxable_amount
- net_amount
- tax_percentage
required:
- type
- amount
additionalProperties: false
customer:
description: The person or animal owner to whom the prescription is issued.
anyOf:
- type: object
description: Defines valid customer identifiers
properties:
id:
type: object
oneOf:
- type: object
description: The customer ssn
properties:
civic_registration_number:
type: string
pattern: ^[12]{1}[90]{1}[0-9]{6}-?[0-9]{4}$
description: swedish personnummer 12 digits
required:
- civic_registration_number
additionalProperties: false
- type: object
description: The customer birth date
properties:
birth_date:
type: string
pattern: ^[12]{1}[90]{1}[0-9]{6}$
description: birth date 10 digits, e.g 19920101
required:
- birth_date
additionalProperties: false
- type: object
description: The company registration number, when a company is the customer
properties:
company_registration_number:
type: string
description: company registration number used as id when the customer is a
company
required:
- company_registration_number
additionalProperties: false
- type: object
description: Defines customer information, like name, address, loyalty program.
properties:
name:
type: string
contact:
type: object
properties:
address:
title: address
description: An address following the convention of
http://microformats.org/wiki/hcard
type: object
properties:
street_address:
type: string
extended_address:
type: string
post_box:
type: string
locality:
type: string
postal_code:
type: string
region:
type: string
country_name:
type: string
type:
type: object
title: address type
description: is address (physical/email) related to business, home, etc
properties:
type:
enum:
- home
- business
anyOf:
- required:
- street_address
- required:
- post_box
required:
- locality
- postal_code
email:
type: string
format: email
phone:
title: generic phone number
description: generic format for phone numbers where strict format can not be
enforced, use only for phone number to be displayed
type: string
pattern: ^(\(?((\+|(00))[0-9]{1,3})\)?)?( ?-?\(?[0-9]+\)?)+$
additionalProperties: false
geo_location:
type: object
title: Geographic location (long/lat)
description: A geographical coordinate
properties:
latitude:
type: number
longitude:
type: number
required:
- latitude
- longitude
additionalProperties: false
animal:
type: object
description: Specific properties related to animal prescriptions
properties:
id:
type: string
description: identifies the animal to whom the prescription is issued
required:
- id
additionalProperties: false
human:
description: Human prescription data related to high-cost reimbursement, given
as previous, current and next periods.
properties:
high_cost:
description: Defines properties related to high cost reimbursement
type: object
properties:
previous_period:
type: object
properties:
gross:
type: number
net:
type: number
start_date:
description: "high cost period start date-time, ISO 8601 date/time format:
YYYY-MM-DDThh:mm:ssTZD"
type: string
format: date-time
end_date:
description: "high cost period end date-time, ISO 8601 date/time format:
YYYY-MM-DDThh:mm:ssTZD"
type: string
format: date-time
required:
- gross
- net
- start_date
additionalProperties: false
current_period:
type: object
properties:
gross:
type: number
net:
type: number
start_date:
description: "high cost period start date-time, ISO 8601 date/time format:
YYYY-MM-DDThh:mm:ssTZD"
type: string
format: date-time
end_date:
description: "high cost period end date-time, ISO 8601 date/time format:
YYYY-MM-DDThh:mm:ssTZD"
type: string
format: date-time
required:
- gross
- net
- start_date
additionalProperties: false
next_period:
type: object
properties:
gross:
type: number
net:
type: number
start_date:
description: "high cost period start date-time, ISO 8601 date/time format:
YYYY-MM-DDThh:mm:ssTZD"
type: string
format: date-time
end_date:
description: "high cost period end date-time, ISO 8601 date/time format:
YYYY-MM-DDThh:mm:ssTZD"
type: string
format: date-time
required:
- gross
- net
- start_date
additionalProperties: false
amount_left_to_reimbursement:
description: The amount left to high cost reimbursement
type: object
properties:
gross:
type: number
minimum: 0
net:
type: number
minimum: 0
required:
- gross
- net
additionalProperties: false
allOf:
- required:
- previous_period
- required:
- current_period
- required:
- next_period
additionalProperties: false
required:
- high_cost
additionalProperties: false
medications:
type: array
description: List of medications issued and their cost. Can be used on both
animal and human prescriptions.
items:
type: object
properties:
description:
type: string
amount:
type: number
required:
- description
additionalProperties: false
expedition:
type: object
description: Expedition / prescription details. The format differs between
pharmacies, so the user-facing part is carried as the 'details' array of
strings.
properties:
id:
description: expedition id, prescription id, etc. For internal use and exchange
with other systems
type: string
details:
description: this is what the user will see
type: array
minItems: 1
items:
type: string
required:
- id
- details
oneOf:
- required:
- animal
- required:
- human
- amount_with_benefit
allOf:
- required:
- business_unit
- required:
- cashier
- required:
- receipt_identifier
- required:
- time_of_purchase
- required:
- amount_without_benefit
- required:
- amount_to_pay
- required:
- expedition
additionalProperties: false