Skip to content
KivraAPI Reference
This is a new version of the Kivra Developer Docs. Report issues or share feedback at avsandare.support@kivra.se. The previous version can be found here.

Send receipt

POST
/dr/v1/receipts
curl --request POST \
  --url https://sender.sandbox-api.kivra.com/dr/v1/receipts \
  --header 'Content-Type: application/json;profile=https://se.receipts.kivra.com/schemas/json/retail/v2.0' \
  --data '{ "business_unit": { "name": "Merchant name", "organization_number": "112233-4499", "unit_id": "466", "contact": { "address": { "street_address": "Merchant road", "locality": "Merchant town", "postal_code": "12345", "country_code": "SWE" }, "phone": "010-123 45 67" } }, "cashier": { "id": "601ada97949c9530f2e087c1", "name": "Stangen" }, "sales_recording_system": { "id": "389114001", "name": "Merchant name", "serial_number": "1462-DASDAD-SE" }, "receipt_identifier": { "sequence_number": 68612 }, "time_of_purchase": "2022-04-27T11:59:08.831+02:00", "currency": "SEK", "totals": { "gross": { "amount": 141 }, "vat": { "amount": 15.11, "sub_totals": [ { "amount": 15.11, "taxable_amount": 141, "net_amount": 125.89, "tax_percentage": 12 } ] }, "paid": { "amount": 141, "received": 141, "returned": 0 } }, "items": [ { "sale": { "identifiers": [ { "identifier_type": "pos", "value": "5cc90e04-86c3-4f29-ae02-5146f328c123" } ], "description": "Dirty Burger Dubbel", "quantity": { "value": 1, "unit": "ea" }, "eligible_for_frequent_shopper_points": true, "regular_sales_unit_price": 125, "extended_amount": 125, "tax_percentage": 12, "tax_amount": 13.39, "sequence_number": 1 } }, { "sale": { "identifiers": [ { "identifier_type": "pos", "value": "9b4e4d67-2483-43c8-bbfc-eca1cb68a123" } ], "description": "Béarnaise", "quantity": { "value": 1, "unit": "ea" }, "eligible_for_frequent_shopper_points": true, "regular_sales_unit_price": 16, "extended_amount": 16, "tax_percentage": 12, "tax_amount": 1.71, "sequence_number": 2 } } ], "payments": [ { "amount": 141, "amount_applied_to_bill": 141, "tender": { "creditdebit": { "bank_identification_number": "535583******7361", "acquiring_institution_id_code": "8025689", "retrieval_reference_number": "220427039945", "card_acceptor_id": "47238220", "card_acceptor_terminal_id": "47238220", "card_acceptor_name": "Merchant name", "approval_code": "882875", "card_token": { "value": "709215290212149250", "scheme": "par" } } } } ], "customer": { "loyalty": { "program": "Stammis", "customer_number": "197305105111" }, "id": { "civic_registration_number": "196801249290" } } }'

Sends a receipt to Kivra. The receipt is routed to a store via one of two options:

  • Automatically: describe the store inline in business_unit; Kivra resolves — or creates — the owning chain and store.
  • Explicitly: set business_unit.service_id to a store_id obtained when the store was created (see Chain/Store Management).

Access scope

  • PARTNER
  • CHAIN
  • STORE

Headers

The Content-Type must be set to:

  • Content-Type: application/json;profile=https://se.receipts.kivra.com/schemas/json/retail/v2.0

The profile tells what version of the JSON schema the receipt is based on.

This schema is available for download in JSON.

Body

Receipts are sent as JSON.

IMPORTANT NOTE:

For card payments, Kivra’s JSON scheme uses the masked card number:

  • Bank Identification Number — masked card number (preferred). The card’s 6-8 digit BIN may be sent if the masked card number is unavailable. In addition, the following payment terminal information should be provided according to ISO standard 8583:
  • Retrieval Reference Number
  • Card Acceptor Terminal ID
  • Card Acceptor ID
  • Card Acceptor Name
  • Approval Code
  • Acquiring institution identification code

Request Bodyrequired

Section titled “Request Bodyrequired”

Sends a receipt

Media typeapplication/json;profile=https://se.receipts.kivra.com/schemas/json/retail/v2.0

Digital receipt schema

object
copy

If true the receipt is a copy

boolean
business_unit
required
Any of:
Identified by external_id and organization number

Merchant information

object
name
string
service_id

Kivra id of an existing business unit.

string
>= 42 characters <= 42 characters /^[0-9]{10}[0-9a-fA-F]{32}$/
unit_id

Internal merchant shop/business unit id

string
external_id
required

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.

string
organization_number
required

Swedish organisationsnummer (10 digits, optionally hyphenated). A VAT number must be sent in vat_number, not here.

string
/^[0-9]{6}-?[0-9]{4}$/
vat_number

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.

string
/^(SE[0-9]{12}|NO[0-9]{9}(?:[Mm][Vv][Aa])?|DK[0-9]{8}|FI[0-9]{8})$/
contact

Merchant contact information name, address, phone etc

object
address
Any of:
Street address

An address following the convention of http://microformats.org/wiki/hcard. At least one of street_address or post_box is required.

object
street_address
required
string
extended_address
string
post_box
string
locality
string
postal_code
string
region
string
country_code
country code

Country as an ISO 3166-1 alpha-3 code, e.g. SWE. Case-insensitive.

string
/^[A-Za-z]{3}$/
type
address type

Whether the address relates to a business or a home

string
Allowed values: home business
email
string format: email
phone
generic phone number

Generic format for phone numbers where strict format can not be enforced, use only for phone number to be displayed

string
/^(\(?((\+|(00))[0-9]{1,3})\)?)?( ?-?\(?[0-9]+\)?)+$/
website
string format: uri
geo_location
Geographic location (long/lat)

A geographical coordinate

object
latitude
required
number
longitude
required
number
chain
Any of:
Existing chain referenced by service_id

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).

object
service_id
required

Kivra id of an existing chain. When present, references that chain directly; name/organization_number/vat_number/external_id are then not required.

string
>= 42 characters <= 42 characters /^[0-9]{10}[0-9a-fA-F]{32}$/
name

Display name of the chain. Required when the chain may need to be created (i.e. when service_id is absent).

string
organization_number

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.

string
/^[0-9]{6}-?[0-9]{4}$/
vat_number

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.

string
/^(SE[0-9]{12}|NO[0-9]{9}(?:[Mm][Vv][Aa])?|DK[0-9]{8}|FI[0-9]{8})$/
external_id

Partner’s own stable identifier for the chain. Grouping key when no organization_number/vat_number is given.

string
cashier
cashier name and id

Identifies the person handling the purchase if applicable

object
id
string
name
string
sales_recording_system
required
Any of:
POS identified by id

Information about the point of sales system used. The system producing the receipt

object
id
required
string
name
string
serial_number
string
receipt_identifier
required
receipt identifier

Receipt identifiers: sequence number and/or extended number with or without barcode representation

object
sequence_number
required

A sequence number as stipulated by the swedish tax authorities

integer
extended_number

A more complex receipt number if applicable, must be unique in given context

object
value
required

Data that will be presented as a barcode on the receipt

string
type

Barcode representation of any data

string
Allowed values: Interleaved2Of5 EAN13 EAN8 Codabar Code39 Code93 Code128 AztecCode Datamatrix PDF417 QRCode
context
required

In what context is the value (receipt number) unique, note GLOBAL can only be used if a digital receipt provider receipt id is used

string
Allowed values: store chain global
time_of_purchase
required

ISO 8601 date/time format: YYYY-MM-DDThh:mm:ssTZD

string format: date-time
currency
required
ISO-4217 currency codes

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

string
/^[a-zA-Z]{3}$/
totals
required

Total amounts keyed by type, e.g. {“gross”: {…}, “vat”: {…}}.

object
paid
Paid total amount

Paid: gross amount including discount and rounding.

object
amount
required

Signed paid total: negative when money goes back to the customer (e.g. a return).

number
received

Amount received from the customer (e.g. cash tendered), when it differs from the paid amount.

number
returned

Amount returned to the customer (e.g. change given), when applicable.

number
gross
Total gross amount presented on the receipt

Gross: total including vat, excluding discounts

object
amount
required

Signed gross total: negative when money goes back to the customer (e.g. a return).

number
vat
Total tax amount presented on the receipt

Tax releated total

object
amount
required

Signed tax total: negative when money goes back to the customer (e.g. a return).

number
sub_totals

Add sub total for each tax percentage used

Array<object>
Sub totals can be used on all totals but is mostly used on VAT

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).

object
amount
required

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.

number
taxable_amount
required

Amount including tax amount (signed, same direction as amount).

number
net_amount
required

Amount excluding tax amount (signed, same direction as amount).

number
tax_percentage
required
number
net
Total net amount presented on the receipt

Net: total excluding vat

object
amount
required

Signed net total: negative when money goes back to the customer (e.g. a return).

number
loyalty
Total loyalty amount

Total loyalty points/amount redeemed. Amount only — no breakdown applies.

object
amount
required
number
rounding
Total rounding amount

Rounding adjustment applied to reach the paid amount. Amount only — no breakdown applies.

object
amount
required

Signed rounding adjustment (may be negative).

number
modifiers
Modifier totals

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.

object
>= 1 properties
discount
object
amount
required

Positive magnitude; the enclosing discount/surcharge key carries the direction.

number
surcharge
object
amount
required

Positive magnitude; the enclosing discount/surcharge key carries the direction.

number
header_text

Any textual information aimed for the receipt header

string
footer_text

Any textual information aimed for the receipt footer

string
items
required

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.

Array<object>
object
>= 1 properties <= 1 properties
sale

Defines data needed to handle sold product/service

object
sequence_number
required

All items must have a unique sequence number 1,2,3 etc. Used for internal references. Also see item_link

integer
item_link

A reference to an other items sequence_number if a relation exists

integer
text
string
identifiers
required
Array<object>
>= 1 items
Item identifier

Identifier for an item being sold or returned. Supported types: ‘pos’ (Point of Sale identifier) and ‘gtin’ (Global Trade Item Number).

object
identifier_type
required
string
Allowed values: pos gtin
value
required
string
serial_number

Product serial number

string
lot_number

Specifies a specific product batch/lot

string
description
required
string
quantity
required
object
value
required

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.

number
> 0
unit
required

Unit for this quantity; we recommend following a standard such as UN/CEFACT Rec 20. Must contain at least one non-whitespace character.

string
>= 1 characters <= 25 characters /\S/
entry_method
string
default: scanned
Allowed values: smartcard micr msr keyed scanned weighed measured rfid automatic integrated_chip_card tapped waved
eligible_for_frequent_shopper_points

True if item bought is eligible for bonus

boolean
unit_cost_price

The unit cost of the item to the merchant at the time of the Transaction.

number
regular_sales_unit_price

Optional: the undiscounted per-unit price the merchant printed, before any discounts or surcharges.

number
actual_sales_unit_price

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.

number
extended_amount
required

The amount the customer paid for this line, net of any line-level modifiers (VAT-inclusive). Authoritative for the line total.

number
modifiers

Line-level price modifiers (discounts/surcharges) already reflected in extended_amount.

Array<object>
Price modifier

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.

object
>= 1 properties <= 1 properties
discount
Price modifier value

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.

object
amount
required

Required, authoritative monetary magnitude (VAT-inclusive), always positive. Direction is carried by the enclosing discount/surcharge key.

number
description

Human-readable label for the modifier, e.g. “Member offer −10%”.

string
reason

Optional category of the modifier.

string
Allowed values: loyalty coupon campaign employee staff damage price_match other
percent

Informational: the percentage applied (always positive).

number
base_amount

Informational: the amount the percent applied to.

number
quantity

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.

integer
>= 1
tax_percentage

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.

number
surcharge
Price modifier value

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.

object
amount
required

Required, authoritative monetary magnitude (VAT-inclusive), always positive. Direction is carried by the enclosing discount/surcharge key.

number
description

Human-readable label for the modifier, e.g. “Member offer −10%”.

string
reason

Optional category of the modifier.

string
Allowed values: loyalty coupon campaign employee staff damage price_match other
percent

Informational: the percentage applied (always positive).

number
base_amount

Informational: the amount the percent applied to.

number
quantity

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.

integer
>= 1
tax_percentage

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.

number
tax_percentage
number
tax_amount

Tax amount based on extended amount and tax percentage

number
foreign_currency
Foreign currency

Gives exchange rate etc when payment is done with a foreign currency

object
currency
required
ISO-4217 currency codes

ISO 4217 foreign currency code

string
/^[a-zA-Z]{3}$/
original_face_amount
required

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

number
exchange_rate
number
return

Defines data needed to handle returned product/service

object
sequence_number
required

All items must have a unique sequence number 1,2,3 etc. Used for internal references. Also see item_link

integer
item_link

A reference to an other items sequence_number if a relation exists

integer
text
string
receipt_reference

A more complex receipt number if applicable, must be unique in given context

object
value
required

Data that will be presented as a barcode on the receipt

string
type

Barcode representation of any data

string
Allowed values: Interleaved2Of5 EAN13 EAN8 Codabar Code39 Code93 Code128 AztecCode Datamatrix PDF417 QRCode
context
required

In what context is the value (receipt number) unique, note GLOBAL can only be used if a digital receipt provider receipt id is used

string
Allowed values: store chain global
identifiers
required
Array<object>
>= 1 items
Item identifier

Identifier for an item being sold or returned. Supported types: ‘pos’ (Point of Sale identifier) and ‘gtin’ (Global Trade Item Number).

object
identifier_type
required
string
Allowed values: pos gtin
value
required
string
serial_number

Product serial number

string
lot_number

Specifies a specific product batch/lot

string
description
required
string
quantity
required
object
value
required

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.

number
> 0
unit
required

Unit for this quantity; we recommend following a standard such as UN/CEFACT Rec 20. Must contain at least one non-whitespace character.

string
>= 1 characters <= 25 characters /\S/
entry_method
string
default: scanned
Allowed values: smartcard micr msr keyed scanned weighed measured rfid automatic integrated_chip_card tapped waved
eligible_for_frequent_shopper_points

True if item bought is eligible for bonus

boolean
unit_cost_price

The unit cost of the item to the merchant at the time of the Transaction.

number
regular_sales_unit_price

Optional: the undiscounted per-unit price the merchant printed, before any discounts or surcharges.

number
actual_sales_unit_price

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.

number
extended_amount
required

The amount the customer paid for this line, net of any line-level modifiers (VAT-inclusive). Authoritative for the line total.

number
modifiers

Line-level price modifiers (discounts/surcharges) already reflected in extended_amount.

Array<object>
Price modifier

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.

object
>= 1 properties <= 1 properties
discount
Price modifier value

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.

object
amount
required

Required, authoritative monetary magnitude (VAT-inclusive), always positive. Direction is carried by the enclosing discount/surcharge key.

number
description

Human-readable label for the modifier, e.g. “Member offer −10%”.

string
reason

Optional category of the modifier.

string
Allowed values: loyalty coupon campaign employee staff damage price_match other
percent

Informational: the percentage applied (always positive).

number
base_amount

Informational: the amount the percent applied to.

number
quantity

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.

integer
>= 1
tax_percentage

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.

number
surcharge
Price modifier value

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.

object
amount
required

Required, authoritative monetary magnitude (VAT-inclusive), always positive. Direction is carried by the enclosing discount/surcharge key.

number
description

Human-readable label for the modifier, e.g. “Member offer −10%”.

string
reason

Optional category of the modifier.

string
Allowed values: loyalty coupon campaign employee staff damage price_match other
percent

Informational: the percentage applied (always positive).

number
base_amount

Informational: the amount the percent applied to.

number
quantity

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.

integer
>= 1
tax_percentage

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.

number
tax_percentage
number
tax_amount

Tax amount based on extended amount and tax percentage

number
foreign_currency
Foreign currency

Gives exchange rate etc when payment is done with a foreign currency

object
currency
required
ISO-4217 currency codes

ISO 4217 foreign currency code

string
/^[a-zA-Z]{3}$/
original_face_amount
required

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

number
exchange_rate
number
text

Text only item, example: product warranty text linked to item purchased

object
sequence_number
required

All items must have a unique sequence number 1,2,3 etc. Used for internal references. Also see item_link

integer
item_link

A reference to an other items sequence_number if a relation exists

integer
text
required
string
deposit

Deposit to get or pay connected to items sold/returned

object
sequence_number
required

All items must have a unique sequence number 1,2,3 etc. Used for internal references. Also see item_link

integer
item_link

A reference to an other items sequence_number if a relation exists

integer
text
string
description
string
unit_amount
required

Signed per-unit deposit amount: negative when the deposit is returned to the customer.

number
amount
required

Signed total deposit amount (unit_amount * quantity): negative when the deposit is returned to the customer.

number
quantity
required

Number of times deposit is applied

integer
tax_percentage

Tax on deposit is not always the same as the goods/service connected

number
sub_deposits
Array<object>
VAT sub deposit

A deposit can be divided into different VATs.

object
amount
required

Signed deposit amount for this VAT bucket: negative when it is returned to the customer (a deposit return)

number
tax_percentage
required
number
modifiers

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.

Array<object>
Price modifier

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.

object
>= 1 properties <= 1 properties
discount
Price modifier value

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.

object
amount
required

Required, authoritative monetary magnitude (VAT-inclusive), always positive. Direction is carried by the enclosing discount/surcharge key.

number
description

Human-readable label for the modifier, e.g. “Member offer −10%”.

string
reason

Optional category of the modifier.

string
Allowed values: loyalty coupon campaign employee staff damage price_match other
percent

Informational: the percentage applied (always positive).

number
base_amount

Informational: the amount the percent applied to.

number
quantity

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.

integer
>= 1
tax_percentage

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.

number
surcharge
Price modifier value

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.

object
amount
required

Required, authoritative monetary magnitude (VAT-inclusive), always positive. Direction is carried by the enclosing discount/surcharge key.

number
description

Human-readable label for the modifier, e.g. “Member offer −10%”.

string
reason

Optional category of the modifier.

string
Allowed values: loyalty coupon campaign employee staff damage price_match other
percent

Informational: the percentage applied (always positive).

number
base_amount

Informational: the amount the percent applied to.

number
quantity

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.

integer
>= 1
tax_percentage

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.

number
payments
required

Tender related information, several tender types can be used for payment

Array<object>
Payment information

One or more tender types can be used. Each type is described and the amount used for each tender type

object
amount
required

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).

number
amount_applied_to_bill

The amount applied to the transaction total

number
foreign_currency_amount
Foreign currency

Gives exchange rate etc when payment is done with a foreign currency

object
currency
required
ISO-4217 currency codes

ISO 4217 foreign currency code

string
/^[a-zA-Z]{3}$/
original_face_amount
required

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

number
exchange_rate
number
rounding

If the amount to pay needs rounding

number
tender
required

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.

object
>= 1 properties <= 1 properties
cash
Cash payment

Cash payment. Carries no additional fields; the enclosing key identifies it.

object
creditdebit
Credit or Debit Card Tender

Credit or debit card payment properties

object
bank_identification_number

ISO 8583 field 56 Payment Account Reference, masked card number

string
/^[A-Za-z0-9*]{0,99}$/
acquiring_institution_id_code

ISO 8583 field 32, Acquiring institution identification code

string
/^[0-9]{0,11}$/
retrieval_reference_number

ISO 8583 field 37, Retrieval Reference Number

string
/^[a-zA-Z0-9]{0,12}$/
card_acceptor_id

ISO 8583 field 42 Card Acceptor Identification Code

string
/^[a-zA-Z0-9\-]{0,15}$/
card_acceptor_terminal_id

ISO 8583 field 41 Card Acceptor Terminal ID

string
/^[a-zA-Z0-9\-]{8}$/
card_acceptor_name

ISO 8583 field 43 Card Acceptor Name/Location

string
/^[a-zA-Z0-9 .,\-/]{0,40}$/
approval_code

ISO 8583 field 38 Approval Code

string
/^[a-zA-Z0-9]{6,}$/
card_token
Tokenized payment card

Gives a token value of the payment card and tokenizier info/scheme.

object
value
required

Tokenized payment card number

string
scheme
required

Token scheme, vendor specific. Any unique token provider definition, e.g. payprov_name_findity_dr

string
payment_slip

Payment slip data as an array of texts

Array<string>
giftcard
Giftcard payment type

Gives giftcard payment info: amount (initial, current), valid period, etc. Dates must be given in format: 2016-09-29

object
card_number
required
string
date_sold
string format: date
date_activated
string format: date
expiration_date
string format: date
initial_balance
number
current_balance
required
number
barcode

Barcode representation of tender details

object
value
required

The barcode value

string
type
required

The barcode type

string
Allowed values: Interleaved2Of5 EAN13 EAN8 Codabar Code39 Code93 Code128 AztecCode Datamatrix PDF417 QRCode
mobile
Generic mobile payment type

Gives basic mobile payment information, mobile specific payment info can be added in the tender_details section

object
provider

Mobile payment name, e.g. swish, android wallet, etc

string
Allowed values: swish:pay
phone
phone number identifer

More restrictive international phone number format used as identifier, based on ITU-T E.123

string
/^\+(?:[0-9]\x20?){6,14}[0-9]$/
tender_details
Tender details

Any additional payment information needed

object
>= 1 properties
barcode

Barcode representation of tender details

object
value
required

The barcode value

string
type
required

The barcode type

string
Allowed values: Interleaved2Of5 EAN13 EAN8 Codabar Code39 Code93 Code128 AztecCode Datamatrix PDF417 QRCode
key
additional properties
string
loyalty
Loyalty payment

Loyalty payment, bonus check.

object
>= 1 properties
points_redeemed

The number of loyalty points redeemed by the customer. Provide this and/or amount_redeemed, depending on how the redemption is denominated.

number
amount_redeemed

The amount redeemed by the customer. Provide this and/or points_redeemed, depending on how the redemption is denominated.

number
loyalty_program

Add loyalty account data to the customer definitions

string
coupon
Coupon payment

Coupon payment

object
name

Coupon name

string
description

Any additional coupon description, if needed

string
coupon_code
required

Coupon identifier

string
manufacture_id

If a manufacture coupon

string
family_code

Assigned by the manufacture for each product, validates that a consumer has purchased a qualifying product

string
promotion_code

Identifies promotion campaign

string
coupon_value
required

Coupon value when redeemed

number
quantity

Quantity of items covered by the coupon

object
value
required

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.

number
> 0
unit
required

Unit for this quantity; we recommend following a standard such as UN/CEFACT Rec 20. Must contain at least one non-whitespace character.

string
>= 1 characters <= 25 characters /\S/
entry_method
string
default: scanned
Allowed values: smartcard micr msr keyed scanned weighed measured rfid automatic integrated_chip_card tapped waved
expiration_date
string format: date
item_links

Links to sold item sequence numbers part of promotion is applicable

Array<integer>
barcode

Barcode representation of tender details

object
value
required

The barcode value

string
type
required

The barcode type

string
Allowed values: Interleaved2Of5 EAN13 EAN8 Codabar Code39 Code93 Code128 AztecCode Datamatrix PDF417 QRCode
generic
Any of:
Named generic tender

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.

object
type
required
Allowed values: purchase_order accounts_receivable house_account voucher
type_name

Free-text name for the tender. Required when type is “other”.

string
tender_details
Tender details

Any additional payment information needed

object
>= 1 properties
barcode

Barcode representation of tender details

object
value
required

The barcode value

string
type
required

The barcode type

string
Allowed values: Interleaved2Of5 EAN13 EAN8 Codabar Code39 Code93 Code128 AztecCode Datamatrix PDF417 QRCode
key
additional properties
string
customer

Identification and information about the customer

object
id

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.

object
>= 1 properties
service_id

The digital receipt service customer identifier

string
email
string format: email
phone
phone number identifer

More restrictive international phone number format used as identifier, based on ITU-T E.123

string
/^\+(?:[0-9]\x20?){6,14}[0-9]$/
civic_registration_number

Swedish personnummer 12 digits

string
/^[12]{1}[90]{1}[0-9]{6}-?[0-9]{4}$/
loyalty

Customer loyalty information

object
program
required

Loyalty program name, example: SJ Prio, ICA, SAS Eurobonus, etc. NOTE! Named used must be approved by Findity

string
level

Some programs has different levels based on point etc

string
customer_number
required

The actual loyalty number

string
incremental_count

Loyalty points gained/lost in transaction

integer
current_count

Total loyalty points after increment

integer
target_count

Loyalty points needed to achieve next goal/level

integer
effective_date
string format: date
expiration_date
string format: date
name
string
contact
object
address
Any of:
Street address

An address following the convention of http://microformats.org/wiki/hcard. At least one of street_address or post_box is required.

object
street_address
required
string
extended_address
string
post_box
string
locality
string
postal_code
string
region
string
country_code
country code

Country as an ISO 3166-1 alpha-3 code, e.g. SWE. Case-insensitive.

string
/^[A-Za-z]{3}$/
type
address type

Whether the address relates to a business or a home

string
Allowed values: home business
geo_location
Geographic location (long/lat)

A geographical coordinate

object
latitude
required
number
longitude
required
number
loyalty

Customer loyalty information

object
program
required

Loyalty program name, example: SJ Prio, ICA, SAS Eurobonus, etc. NOTE! Named used must be approved by Findity

string
level

Some programs has different levels based on point etc

string
customer_number
required

The actual loyalty number

string
incremental_count

Loyalty points gained/lost in transaction

integer
current_count

Total loyalty points after increment

integer
target_count

Loyalty points needed to achieve next goal/level

integer
effective_date
string format: date
expiration_date
string format: date
customer_order

Information about a connected customer order if applicable

object
>= 1 properties
order_number

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.

string
order_reference

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.

string
customer

To whom the order/order_reference belongs

object
name
string
contact
object
address
Any of:
Street address

An address following the convention of http://microformats.org/wiki/hcard. At least one of street_address or post_box is required.

object
street_address
required
string
extended_address
string
post_box
string
locality
string
postal_code
string
region
string
country_code
country code

Country as an ISO 3166-1 alpha-3 code, e.g. SWE. Case-insensitive.

string
/^[A-Za-z]{3}$/
type
address type

Whether the address relates to a business or a home

string
Allowed values: home business
email
string format: email
phone
generic phone number

Generic format for phone numbers where strict format can not be enforced, use only for phone number to be displayed

string
/^(\(?((\+|(00))[0-9]{1,3})\)?)?( ?-?\(?[0-9]+\)?)+$/
geo_location
Geographic location (long/lat)

A geographical coordinate

object
latitude
required
number
longitude
required
number
loyalty

Customer loyalty information

object
program
required

Loyalty program name, example: SJ Prio, ICA, SAS Eurobonus, etc. NOTE! Named used must be approved by Findity

string
level

Some programs has different levels based on point etc

string
customer_number
required

The actual loyalty number

string
incremental_count

Loyalty points gained/lost in transaction

integer
current_count

Total loyalty points after increment

integer
target_count

Loyalty points needed to achieve next goal/level

integer
effective_date
string format: date
expiration_date
string format: date
control_unit

Control unit information required by swedish tax authorities

object
id
required
string
code
string
Examples

Sale — auto-created store

A card sale where the store is created straight from the receipt. business_unit describes the store (name + organization_number) and business_unit.service_id is omitted, so Kivra resolves — or creates — the owning chain and store. Customer identified by civic registration number; card_token uses the par scheme for reliable matching.

{
  "business_unit": {
    "name": "Merchant name",
    "organization_number": "112233-4499",
    "unit_id": "466",
    "contact": {
      "address": {
        "street_address": "Merchant road",
        "locality": "Merchant town",
        "postal_code": "12345",
        "country_code": "SWE"
      },
      "phone": "010-123 45 67"
    }
  },
  "cashier": {
    "id": "601ada97949c9530f2e087c1",
    "name": "Stangen"
  },
  "sales_recording_system": {
    "id": "389114001",
    "name": "Merchant name",
    "serial_number": "1462-DASDAD-SE"
  },
  "receipt_identifier": {
    "sequence_number": 68612
  },
  "time_of_purchase": "2022-04-27T11:59:08.831+02:00",
  "currency": "SEK",
  "totals": {
    "gross": {
      "amount": 141
    },
    "vat": {
      "amount": 15.11,
      "sub_totals": [
        {
          "amount": 15.11,
          "taxable_amount": 141,
          "net_amount": 125.89,
          "tax_percentage": 12
        }
      ]
    },
    "paid": {
      "amount": 141,
      "received": 141,
      "returned": 0
    }
  },
  "items": [
    {
      "sale": {
        "identifiers": [
          {
            "identifier_type": "pos",
            "value": "5cc90e04-86c3-4f29-ae02-5146f328c123"
          }
        ],
        "description": "Dirty Burger Dubbel",
        "quantity": {
          "value": 1,
          "unit": "ea"
        },
        "eligible_for_frequent_shopper_points": true,
        "regular_sales_unit_price": 125,
        "extended_amount": 125,
        "tax_percentage": 12,
        "tax_amount": 13.39,
        "sequence_number": 1
      }
    },
    {
      "sale": {
        "identifiers": [
          {
            "identifier_type": "pos",
            "value": "9b4e4d67-2483-43c8-bbfc-eca1cb68a123"
          }
        ],
        "description": "Béarnaise",
        "quantity": {
          "value": 1,
          "unit": "ea"
        },
        "eligible_for_frequent_shopper_points": true,
        "regular_sales_unit_price": 16,
        "extended_amount": 16,
        "tax_percentage": 12,
        "tax_amount": 1.71,
        "sequence_number": 2
      }
    }
  ],
  "payments": [
    {
      "amount": 141,
      "amount_applied_to_bill": 141,
      "tender": {
        "creditdebit": {
          "bank_identification_number": "535583******7361",
          "acquiring_institution_id_code": "8025689",
          "retrieval_reference_number": "220427039945",
          "card_acceptor_id": "47238220",
          "card_acceptor_terminal_id": "47238220",
          "card_acceptor_name": "Merchant name",
          "approval_code": "882875",
          "card_token": {
            "value": "709215290212149250",
            "scheme": "par"
          }
        }
      }
    }
  ],
  "customer": {
    "loyalty": {
      "program": "Stammis",
      "customer_number": "197305105111"
    },
    "id": {
      "civic_registration_number": "196801249290"
    }
  }
}

Responses

Section titled “Responses”

201

Section titled “201”

Receipt successfully sent

Media typeapplication/json
object
message
string
findings

Non-fatal validation findings (warning/info). See Validation feedback above.

Array<object>
Finding

One validation finding. See the Receipt validation logic guide.

object
code
required

Stable identifier for the check, e.g. items.paid_mismatch.

string
severity
required

Error = contract violation (rejected with 400 40020 for opted-in partners); warning/info = non-fatal feedback.

string
Allowed values: error warning info
path

JSON path to the offending field, e.g. payments[0].tender.card_token.

string
message
required

Human-readable description of the finding.

string
expected

The expected value, for mismatch findings.

actual

The value found, for mismatch findings.

Example
{
  "message": "Received receipt",
  "findings": [
    {
      "code": "transaction.card_token_scheme_not_par",
      "severity": "info",
      "path": "payments[0].tender.card_token.scheme",
      "message": "card_token scheme is \"kivra\"; par is recommended for reliable matching"
    }
  ]
}

Headers

Section titled “Headers”
x-dr-transactionid
string
/^([a-z0-9]{42})$/

The id of the created receipt

Example
15662258993a2dcd45aba54f9086544f5f97c60ec4
x-dr-storeid
string

The service_id (store id) the receipt was routed to. When the store is auto-created (retail/v2.0 with business_unit.service_id omitted) this is the id of the newly created — or resolved — store, which the caller otherwise has no way to learn.

Example
15594097555922f97bfeb148d6b9a6ef76f76ebdce
x-dr-chainid
string

The id of the owning chain. Under auto-create, the newly created — or resolved — chain.

Example
15594097552e6dfbe7ca6d4679acd8120c3344cc8c

202

Section titled “202”

Retained or Greenbin receipt received

Media typeapplication/json
One of:
Retained receipt
object
data

Base64 encoded QR code

string
token

Token

string
url

URL to the receipt

string
Example
{
  "data": "base64-encoded-qr-code",
  "token": "token",
  "url": "https://url-to-receipt"
}

Headers

Section titled “Headers”
x-dr-transactionid
string
/^([a-z0-9]{42})$/

The id of the retained receipt. Not applicable for greenbin receipts

Example
15662258993a2dcd45aba54f9086544f5f97c60ec4
x-dr-storeid
string

The service_id (store id) the receipt was routed to. When the store is auto-created (retail/v2.0 with business_unit.service_id omitted) this is the id of the newly created — or resolved — store, which the caller otherwise has no way to learn.

Example
15594097555922f97bfeb148d6b9a6ef76f76ebdce
x-dr-chainid
string

The id of the owning chain. Under auto-create, the newly created — or resolved — chain.

Example
15594097552e6dfbe7ca6d4679acd8120c3344cc8c

400

Section titled “400”

Bad request

Media typeapplication/json
ErrorResponse
object
error_code
string
short_message
string
long_message
string
error_detail
Array<string>
Examples
{
  "error_code": "40000",
  "short_message": "bad_request",
  "long_message": "body is missing required fields or has invalid fields"
}

401

Section titled “401”

Unauthorized access

Media typeapplication/json
ErrorResponse
object
error_code
string
short_message
string
long_message
string
error_detail
Array<string>
Examples
Exampleunauthorized
{
  "error_code": "40100",
  "short_message": "unauthorized",
  "long_message": "permission denied"
}

404

Section titled “404”

Not found

Media typeapplication/json
ErrorResponse
object
error_code
string
short_message
string
long_message
string
error_detail
Array<string>
Examples
Exampleunauthorized
{
  "error_code": "40400",
  "short_message": "not found",
  "long_message": "the requested resource could not be found",
  "error_detail": "invalid service_id"
}

500

Section titled “500”

Internal server error

Media typeapplication/json
ErrorResponse
object
error_code
string
short_message
string
long_message
string
error_detail
Array<string>
Example
{
  "error_code": "50000",
  "short_message": "internal server error",
  "long_message": "unknown error ocurred"
}