Versa Schema

The Versa schema is the core data model for structured transaction records in the Versa protocol. Schema objects include "header" information — the merchant name, merchant logo, total amount, transaction date, etc. — as well as "line item" details — the quantity, description, and cost of each item purchased.

A JSON Schema document and corresponding TypeScript Types are available on GitHub or via the @versa/schema package.

Event Types

All primary event types share the same underlying schema structure, but differ in which fields are expected to be present. The event_type is typically inferred from the data provided, but can be specified in the event registration payload.

receipt: A completed transaction. Includes payments.
booking: A travel reservation. Payments are not required, and header.paid is typically zero. Bookings are only valid for travel itemization types: car_rental, flight, lodging, or transit_route.
invoice: An outstanding bill. Structurally identical to a receipt, but header.paid is less than header.total, indicating payment is still due.
itinerary: Travel information without financial data. Excludes totals, taxes, and payments. Focused on travel details only. See the Itinerary Schema for details.

Sections

Schema objects are composed of four sections:

Header: Top-level fields, e.g. merchant details, totals, transaction date.
Itemization: Description, quantity, unit cost, and total for each line item. Type-specific templates describe different purchase types, e.g. flight, e-commerce purchase, service.
Footer: Optional merchant-defined actions, pivoting off the purchase, and supplemental text. For example: 'Contact Support,' 'Buy Again,' 'Manage Subscription.'
Payments: Payment status and details. Required for receipt and invoice event types; omitted for itinerary; optional for booking.

Rough diagram of receipt elements.

Wrapper

Schema objects are wrapped in a top-level envelope that includes the schema version:

{
  "schema_version": "2.2.0",
  "header": { ... },
  "itemization": { ... },
  "payments": [ ... ],
  "footer": { ... }
}

Field	Type	Description
`schema_version`	`string`	Version of the schema; useful for validating the object.
`header`	`object`	Header.
`itemization`	`object`	Itemization object.
`payments`	`nullable array`	List of payments.
`footer`	`object`	The footer includes actions and supplemental text.

Below we cover each of these sections in detail.

The header provides a high-level view of the transaction, describing the "who," "when," and "where" (the "what" is covered in the itemization section). An example header:

"header": {
  "currency": "usd",
  "subtotal": 5928,
  "total": 6332,
  "paid": 6332,
  "invoiced_at": 1713295619,
  "invoice_number": "1024",
  "mcc": 3234,
  "third_party": null,
  "customer": null,
  "location": null,
  "invoice_asset_id": "asset_6dbca44449094eb28aaa6b3c6b2aa4",
  "receipt_asset_id": null
}

Field	Type	Description
`currency`	`string`	A lowercase ISO 4217 currency code, e.g. `usd`.
`subtotal`	`integer`	Subtotal (before taxes, fees, tip).
`total`	`integer`	Total amount. In the currency specified and in the smallest currency unit.
`paid`	`integer`	Sum of all payments. Will equal `total` if paid in full; zero for bookings; less than `total` for invoices.
`invoiced_at`	`integer`	Time at which the invoice was created. Measured in seconds since the Unix epoch.
`invoice_number`	`nullable string`	Unique identifier for the invoice / receipt.
`mcc`	`nullable string`	Merchant Category Code. This value should match the value on the card network.
`third_party`	`nullable object`	Third party involved in the transaction, where applicable.
`customer`	`nullable object`	Customer involved in the transaction, where applicable.
`location`	`nullable object`	Place object for the merchant. Also where you can set the primary timezone.
`invoice_asset_id`	`nullable string`	Asset id of uploaded invoice PDF or image.
`receipt_asset_id`	`nullable string`	Asset id of uploaded receipt PDF or image.

Third Party Object

Third Party

Use the optional third party object in cases where the sender is a platform / broker. For example, if a coffee shop uses Square to process sales, the 'sending merchant' would be Square and the 'third party merchant' would be the coffee shop. The make_primary flag specifies whether the sending merchant or the third party merchant should get top billing on the receipt.

Field	Type	Description
`relation`	`enum`	One of `bnpl`, `delivery_service`, `marketplace`, `payment_processor`, `platform`, `point_of_sale`.
`make_primary`	`boolean`	Determines whether the merchant or third party gets top billing on the receipt.
`merchant`	`nullable object`	An org object representing the third party.

Customer Object

Customer

Used in cases where the merchant has a profile for the customer. Can be left null i.e. for guest checkout flows.

Field	Type	Description
`name`	`string`
`email`	`nullable string`
`website`	`nullable string`
`address`	`nullable object`	An address object.
`phone`	`nullable string`	Phone number in the E.164 format.
`booker`	`nullable object`	A person object for the person who arranged the purchase (booked, bought).
`metadata`	`array`	Array of metadata objects, for any additional info.

Itemization

The Itemization section describes the goods and services that compose the purchase. Based on the type of purchase, the object conforms to one of seven templates: General, Car Rental, E-commerce, Flight, Lodging, Service, or Transit Route. Exactly one itemization template must be non-null. When in doubt, use the 'general' template.

NOTE

For booking event types, only the travel itemization types are valid: car_rental, flight, lodging, or transit_route. For itinerary event types, general and ecommerce are also excluded. See the Itinerary Schema for the full itinerary itemization spec.

"itemization": {
  "general": { ... },
  "car_rental": null,
  "ecommerce": null,
  "flight": null,
  "lodging": null,
  "service": null,
  "transit_route": null
}

General Object

General

Field	Type	Description
`items`	`array`	An array of generic item objects.
`invoice_level_adjustments`	`array`	Array of adjustments applied at the top (invoice) level. These are independent of line item adjustments, which are added at the line item level.

Car Rental Object

Car Rental

View a complete car rental receipt example.

"car_rental": {
  "rental_at": 1713196492,
  "return_at": 1713415500,
  "confirmation_number": null,
  "record_locator": null,
  "vendor_code": null,
  "rental_location": { ... },
  "return_location": { ... },
  "vehicle": {
    "description": "Polestar 2",
    "image": null,
    "license_plate_number": null,
    "vehicle_class": "EDAE"
  },
  "drivers": [{ ... }],
  "odometer_reading_in": 100,
  "odometer_reading_out": 210,
  "items": [ ... ],
  "metadata": [],
  "invoice_level_adjustments": [],
}

Field	Type	Description
`rental_at`	`integer`	Rental time. Measured in seconds since the Unix epoch.
`return_at`	`integer`	Return time. Measured in seconds since the Unix epoch.
`confirmation_number`	`nullable string`	Rental confirmation number.
`record_locator`	`nullable string`	PNR or booking record locator.
`vendor_code`	`nullable string`	Two-letter GDS vendor code, e.g. `ZI` for Avis, `ZB` for Budget.
`rental_location`	`object`	A place describing the rental location.
`return_location`	`object`	A place describing the return location.
`vehicle`	`object`	A vehicle object.
`drivers`	`nullable array`	Array of person objects.
`odometer_reading_in`	`nullable integer`
`odometer_reading_out`	`nullable integer`
`items`	`array`	An array of generic item objects.
`metadata`	`array`	Array of metadata objects, for any additional info.
`invoice_level_adjustments`	`array`	Array of adjustments applied at the top (invoice) level. These are independent of line item adjustments, which are added at the line item level.

Vehicle

Field	Type	Description
`description`	`string`	Type of car.
`image`	`nullable string`	Image of car.
`license_plate_number`	`nullable string`
`vehicle_class`	`nullable string`	ACRISS car code, four letters.

E-commerce Object

E-commerce

For online orders, with shipping info. If items have not been assigned to a shipment, add those items to invoice_level_line_items. Once they've been assigned to a shipment, move them to shipment.items. View a complete E-commerce receipt example.

Field	Type	Description
`invoice_level_line_items`	`array`	An array of item objects at the invoice level. For items that are part of shipment, move them under the shipment object.
`shipments`	`array`	An array of shipment objects.
`invoice_level_adjustments`	`array`	Array of adjustments applied at the top (invoice) level. These are independent of line item adjustments, which are added at the line item level.

Shipment

Field	Type	Description
`items`	`array`	An array of item objects at shipment level.
`carrier`	`nullable string`	Shipping carrier name (e.g., "FedEx", "UPS").
`tracking_number`	`nullable string`	Label that appears on the button.
`expected_delivery_at`	`nullable int`	Measured in seconds since the Unix epoch.
`shipment_status`	`nullable enum`	One of `prep`, `in_transit`, `delivered`.
`destination_address`	`nullable object`	An address object.

Flight Object

Flight

View a complete flight receipt example.

Field	Type	Description
`tickets`	`array`	An array of ticket objects.
`itinerary_locator`	`nullable string`
`invoice_level_adjustments`	`array`	Array of adjustments applied at the top (invoice) level. These are independent of line item adjustments, which are added at the line item level.

Tickets

Field	Type	Description
`segments`	`array`	Array of segments.
`number`	`nullable string`
`record_locator`	`nullable string`	PNR.
`passenger`	`nullable object`	A person object.
`metadata`	`array`	Array of metadata objects, for any additional info.
`fare`	`nullable integer`	Optional, only needed if fares are not included on the contained segments.
`taxes`	`array`	Optional, only needed if taxes are not included on the contained segments.

Segments

Field	Type	Description
`departure_airport_code`	`string`	The three-letter IATA airport code that the flight departed from.
`arrival_airport_code`	`string`	The three-letter IATA airport code of the flight's destination.
`fare`	`nullable integer`	Should be included, unless `fare` is on the parent ticket object instead.
`taxes`	`array`	Array of tax objects.
`departure_at`	`nullable integer`	Departure time. Measured in seconds since the Unix epoch.
`arrival_at`	`nullable integer`	Arrival time. Measured in seconds since the Unix epoch.
`departure_tz`	`nullable string`	A list of possible time zone values is maintained at the IANA Time Zone Database.
`arrival_tz`	`nullable string`	A list of possible time zone values is maintained at the IANA Time Zone Database.
`flight_number`	`nullable string`	The two-letter IATA airline designator followed by a one to four digit number (e.g. 'DL123').
`class_of_service`	`nullable string`
`seat`	`nullable string`
`aircraft_type`	`nullable string`	The ICAO code of the aircraft.
`metadata`	`array`	Array of metadata objects, for any additional info.
`adjustments`	`array`	Array of adjustment objects.

Lodging Object

Lodging

View a complete lodging receipt example.

lodging: {
  "check_in": 1713196492,
  "check_out": 1713473361,
  "confirmation_number": null,
  "chain_code": null,
  "property_id": null,
  "record_locator": null,
  "guests": [{
    "first_name": "Susan",
    "last_name": "Doe",
    "preferred_first_name": "Sue",
    "email": "sdoe@platform.co",
    "phone": "+14155552671",
    "metadata": []
  }],
  "room": "806",
  "location": { ... },
  "items": [ ... ],
  "metadata": [],
  "invoice_level_adjustments": []
}

Field	Type	Description
`check_in`	`int`	Check-in date-time. Measured in seconds since the Unix epoch.
`check_out`	`int`	Check-out date-time. Measured in seconds since the Unix epoch.
`confirmation_number`	`nullable string`	Hotel confirmation number.
`chain_code`	`nullable string`	Two-character chain code, e.g. `MC` for Marriott, `HY` for Hyatt.
`property_id`	`nullable string`	Property identifier. Examples: `gds.sabre:19835`, `gds.amadeus:BWNYCMQ`, `chain.marriott:NYCMQ`, `giata:17324`.
`record_locator`	`nullable string`	PNR or booking record locator.
`guests`	`nullable array`	Array of person objects.
`room`	`nullable string`	Room number.
`location`	`nullable object`	A place object describing the hotel / lodging.
`items`	`array`	An array of generic item objects. This includes the room rate, as well as incidentals / full folio.
`metadata`	`array`	Array of metadata objects, for any additional info.
`invoice_level_adjustments`	`array`	Array of adjustments applied at the top (invoice) level. These are independent of line item adjustments, which are added at the line item level.

Service Object

Service

For airport parking, SaaS subscriptions, phone bills, etc. View a complete service receipt example.

"service": {
  "service_items": [{
    "recurring": true,
    "description": "Pro monthly plan",
    "amount": 1000,
    "interval": "month",
    "interval_count": 1,
    "current_period_start_at": 1679609767,
    "current_period_end_at": 1682288167,
    "quantity": 10,
    "unit_cost": 875,
    "taxes": [],
    "metadata": [],
    "adjustments": []
  }],
  "invoice_level_adjustments": []
}

Field	Type	Description
`service_items`	`array`	An array of service item objects.
`invoice_level_adjustments`	`array`	Array of adjustments applied at the top (invoice) level. These are independent of line item adjustments, which are added at the line item level.

Service Item

Field	Type	Description
`amount`	`integer`	Subtotal for the line item (typically `quantity` × `unit_cost` + `adjustments`). Does not include `taxes`.
`service_location`	`nullable object`	A place object describing the location where the service was provided (e.g., parking lot, service center).
`recurring`	`boolean`	Whether this is a recurring service.
`description`	`string`	Description of the service.
`interval`	`nullable enum`	One of `day`, `week`, `month` or `year`.
`interval_count`	`nullable integer`	The number of intervals (specified in the interval attribute) between subscription billings. For example, interval=month and interval_count=3 bills every 3 months.
`current_period_start_at`	`nullable integer`	Start of the current period of the service. Measured in seconds since the Unix epoch.
`current_period_end_at`	`nullable integer`	End of the current period. Measured in seconds since the Unix epoch.
`quantity`	`nullable number`	Quantity of items.
`unit_cost`	`nullable integer`	Cost of the service in the smallest currency unit.
`taxes`	`array`	Array of tax objects.
`metadata`	`array`	Array of key/value metadata pairs, e.g. SKU.
`adjustments`	`array`	Array of adjustment objects.

Transit Route Object

Transit Route

A route, typically used by rideshare / taxi services, or rail / bus / ferry / etc. View complete taxi receipt or rail receipt examples.

"transit_route": {
  "transit_route_items": [{
    "departure_address": {
      "street_address": "273 Sesame St",
      "city": "Brooklyn",
      "region": "NY",
      "country": "US",
      "postal_code": "11205",
      "lat": 40.68266,
      "lon": -73.94237,
      "tz": "America/New_York"
    },
    "arrival_address": {
      "street_address": "141 Broadway",
      "city": "Brooklyn",
      "region": "NY",
      "country": "US",
      "postal_code": "11205",
      "lat": 40.69954,
      "lon": -73.97064,
      "tz": "America/New_York"
    },
    "fare": 4215,
    "departure_at": 1713196492,
    "arrival_at": 1713197752,
    "passenger": null,
    "polyline": "syhwFxzhbMrFtdAmpAhOlGzmAi%5CdEaGEDgEoAEMfK",
    "taxes": [],
    "metadata": [],
    "adjustments": []
  }],
  "invoice_level_adjustments": []
}

Field	Type	Description
`transit_route_items`	`array`	Array of transit route item objects.
`invoice_level_adjustments`	`array`	Array of adjustments applied at the top (invoice) level. These are independent of line item adjustments, which are added at the line item level.

Transit Route Item

Field	Type	Description
`departure_location`	`object`	The origin place object.
`arrival_location`	`object`	The destination place object.
`fare`	`integer`	Ride amount, typically the same as the header subtotal.
`departure_at`	`nullable integer`	Departure time. Measured in seconds since the Unix epoch.
`arrival_at`	`nullable integer`	Arrival time. Measured in seconds since the Unix epoch.
`mode`	`nullable enum`	One of `car`, `taxi`, `rail`, `bus`, `ferry`, `other`.
`passenger`	`nullable object`	A person object.
`polyline`	`nullable string`	An encoded polyline of the route.
`taxes`	`array`	Array of tax objects.
`metadata`	`array`	Array of key/value metadata pairs.
`adjustments`	`array`	Array of adjustment objects.

Field	Type	Description
`actions`	`array`	List of actions.
`supplemental_text`	`nullable string`	Terms and conditions or other info. Supports Markdown

Actions

Merchants have the option to provide useful next actions in the Actions section. An action is typically a deep link to a page within the merchant's website. For example 'Buy Again' might deep link to a pre-filled shopping cart. There is a limit of three actions.

NOTE

For security reasons, we recommend that the action urls share the same domain as the sending merchant, wherever possible. Authoritative social media sites like Instagram and Facebook are also common. Action URLs that don't share a domain with the sending merchant, and aren't to an authoritative site, may be filtered by the receiver.

"actions": [
  {
    "name": "Emergency Roadside Assistance",
    "url": "https://yourco.com/support/be1e1b57-8fe9-4729-8b7d-f9a4690bb2cd"
  },
  {
    "name": "Re-book",
    "url": "https://yourco.com/buy/ad058b82-d0dd-4534-a915-d448df098167"
  },
  {
    "name": "Instagram: yourco",
    "url": "https://instagram.com/yourco"
  }
]

Field	Type	Description
`name`	`string`	Label that appears on the button.
`url`	`string`	Action deep link.

Payments

"payments": [
  {
    "paid_at": 1679609767,
    "payment_type": "card",
    "amount": 234,
    "card_payment": {
      "last_four": "7806",
      "network": "mastercard"
    },
    "ach_payment": null
  }
]

Field	Type	Description
`amount`	`int`
`paid_at`	`int`	Measured in seconds since the Unix epoch.
`payment_type`	`nullable enum`	One of `card` or `ach`.
`card_payment`	`nullable object`	Card payment object.
`ach_payment`	`nullable object`	ACH payment object.

Card Payment Object

Card Payment

Field	Type	Description
`last_four`	`string`	The last four digits of the card number.
`network`	`nullable enum`	One of `amex`, `diners`, `discover`, `eftpos_au`, `jcb`, `mastercard`, `unionpay`, or `visa`.

ACH Payment Object

ACH Payment

Field	Type	Description
`routing_number`	`string`	ACH routing number.

Primitives

Foundational objects used throughout the schema.

Org Primitive

Org

A merchant, third party, or employer profile.

TIP

The org object is used to describe both a sending merchant and a third party merchant. In the former case, the org object is expanded implicitly via the Versa Registry, whereas in the latter case, the org object is explicitly encoded into the receipt, via the header third_party object.

{
  "name": "Some Co",
  "legal_name": "Some Co, Inc.",
  "brand_color": "#f0C14B",
  "logo": "https://static.platform.co/image_url.png",
  "logo_asset_id": "asset_6dbca44449094eb28aaa6b3c6b2aa4",
  "website": "platform.co",
  "vat_number": null,
  "address": null
}

Field	Type	Description
`name`	`string`	The organization's common name.
`legal_name`	`nullable string`	The organization's legal name.
`brand_color`	`nullable string`	Hex color.
`logo`	`nullable string`	Deprecated: Logo image url, in a square aspect ratio. Use `logo_asset_id` instead.
`logo_asset_id`	`nullable string`	Asset id of uploaded logo image. Recommended size 400x400 in a square aspect ratio.
`website`	`nullable string`	Organization's primary website url.
`vat_number`	`nullable string`
`address`	`nullable object`	An address object.

Person Primitive

Person

{
  "first_name": "Theodore",
  "last_name": "Doe",
  "preferred_first_name": "Ted",
  "email": "tdoe@platform.co",
  "phone": "+14155552671",
  "metadata": []
}

Field	Type	Description
`first_name`	`nullable string`	Legal first name.
`last_name`	`nullable string`	Legal last name.
`preferred_first_name`	`nullable string`
`email`	`nullable string`
`phone`	`nullable string`	Phone number in the E.164 format.
`metadata`	`array`	Array of metadata objects, for any additional info.

Place Primitive

Place

Describes a brick-and-mortar location.

{
  "name": "Widget Co",
  "address": {
    "tz": "America/New_York"
  },
  "phone": "+14155552671",
  "url": null,
  "google_place_id": null,
  "image": null
}

Field	Type	Description
`name`	`nullable string`	Place name.
`address`	`nullable object`	An address object.
`phone`	`nullable string`	Phone number in the E.164 format.
`url`	`nullable string`	URL for specific place, e.g. chain.com/store-id.
`google_place_id`	`nullable string`	Mapping to the Google Places database.
`image`	`nullable string`	Image representing the place.

Address Primitive

Address

{
  "street_address": "123 Main St",
  "city": "Anytown",
  "region": "CA",
  "country": "US",
  "postal_code": "12345",
  "lat": 37.7749,
  "lon": -122.4194,
  "tz": "America/Los_Angeles"
}

Field	Type	Description
`street_address`	`nullable string`
`city`	`nullable string`
`region`	`nullable string`	Two letter region code.
`country`	`nullable string`	Two letter ISO 3166 country code.
`postal_code`	`nullable string`
`lat`	`nullable number`
`lon`	`nullable number`
`tz`	`nullable string`	A list of possible time zone values is maintained at the IANA Time Zone Database.

Item Primitive

Item

A generic line item.

{
  "description": "Blue Cheese Crumbles",
  "amount": 1780,
  "quantity": 10,
  "unit_cost": 178,
  "unit": null,
  "product_image_asset_id": null,
  "group": null,
  "unspsc": null,
  "url": null,
  "date": null,
  "taxes": [
    {
      "amount": 432,
      "rate": 0.0875,
      "name": "GST"
    }
  ],
  "metadata": [{ "key": "SKU", "value": "524959" }],
  "adjustments": []
}

Field	Type	Description
`description`	`string`	Description of the good / service.
`amount`	`integer`	Subtotal for the line item (typically `quantity` × `unit_cost` + `adjustments`). Does not include `taxes` or `adjustments`.
`quantity`	`nullable number`	Quantity of items.
`unit_cost`	`nullable integer`	Cost of the good / service in the smallest currency unit.
`unit`	`nullable string`	Field describing the unit type, typically for weight or volume -based values, e.g. 'kg' or 'gallons'. Leave null for 'each'.
`product_image_asset_id`	`nullable string`	Asset id of uploaded product image.
`group`	`nullable string`	Grouping of line items.
`unspsc`	`nullable string`	The 8-digit UNSPSC code for this item.
`url`	`nullable string`	URL to product page.
`date`	`nullable string`	Date corresponding to the line item, in ISO 8601 format (YYYY-MM-DD), e.g. for nightly rate in a hotel folio.
`taxes`	`array`	Array of tax objects.
`metadata`	`array`	Array of key/value metadata pairs, e.g. SKU.
`adjustments`	`array`	Array of adjustment objects.

Metadata Primitive

Metadata

Use line item metadata to track things not otherwise in the schema. E.g. SKU, Size, Color, UNSPSC Code, etc.

{
  "key": "SKU",
  "value": "524959"
}

Field	Type	Description
`key`	`string`	The type of metadata, e.g. 'Size', 'Brand', 'Product Condition', 'Special Instructions', etc.
`value`	`string`	The corresponding value.

Tax Primitive

Tax

{
  "amount": 432,
  "name": "GST",
  "rate": 0.0875
}

Field	Type	Description
`amount`	`int`	The total tax, in the smallest currency unit.
`name`	`string`	E.g. 'VAT' or 'GST'.
`rate`	`nullable number`	The tax rate, e.g. 0.05 for 5%.

Adjustment Primitive

Adjustment

To be used for discounts, tip, fees, surcharges, tolls.

{
  "amount": 1234,
  "adjustment_type": "tip",
  "name": "Tip",
  "rate": null
}

Field	Type	Description
`amount`	`int`	The total of the adjustment, in the smallest currency unit. Positive value for tip / fee, negative value for discount.
`adjustment_type`	`enum`	One of `discount`, `tip`, `fee`, `add_on`, `other`.
`name`	`nullable string`	The name of the adjustment.
`rate`	`nullable number`	The adjustment rate, e.g. -0.1 for 10% discount, or 0.2 for 20% tip. Null for fixed adjustment.

Definitions & Formatting

Currency Values

All API requests expect amounts to be provided in a currency's smallest unit. For example, to represent 10 USD, provide an amount value of 1000 (that is, 1000 cents). For zero-decimal currencies, still provide amounts as an integer but without multiplying by 100. For example, to represent ¥500, provide an amount value of 500.

Images

Images must be hosted at public URLs. The images are likely to be indexed by the receiver. For best results, no image dimension should be less than 400px, or greater than 2,000px.

Cancelations

To mark a transaction as canceled, an update event should be sent with an empty itemization. See example:

{
  "schema_version": "2.2.0",
  "header": {
    "invoiced_at": 1713295619,
    "currency": "usd",
    "total": 0,
    "subtotal": 0,
    "paid": 0,
    "location": {
      "name": null,
      "address": {
        "tz": "America/New_York"
      }
    }
  },
  "itemization": {},
  "footer": {},
  "payments": []
}

Edit this doc on GitHub