Enriched Transaction Schema

Overview

When a match is generated between your transaction and a receipt on the Banyan network, Banyan generates an Enriched Transaction (eTx). Understanding the schema is essential to using the data you receive from Banyan.

Data is sent in Avro format with guarantees of backwards compatibility. As different types of information is sent depending on the vertical the merchant is in (i.e., "In Room Dining" amount doesn't pertain to a big box retailer receipt), there will be some item objects that are null within the eTx. This is not an error.

eTx Top Level

Element	Description	Data Type	Nullable?	Notes
byn_etx_id	Unique ID generated by Banyan when creating the enriched record	string	No
byn_match_id	Unique ID generated by Banyan when a receipt is married with a transaction	string	No
match_ts	Timestamp of when the receipt is married with a transaction	timestamp-millis	No	Recorded in UTC
split_tender	Whether the payment that was matched was the only tender on the receipt	boolean	No	True means that there is more than one tender

etx.receipt

Element	Description	Data Type	Nullable?	Notes
byn_receipt_id	Unique ID created by Banyan to represent a receipt received from a merchant	string	No
currency	Currency of the total amount	numeric	No
merchant_total_amount	Total amount for the entire receipt	numeric	No	Could be different than payment.total_amount if there is a split tender on the receipt
fulfillment_type	How the items are received by the customer	string	Yes	Valid values include {in_store, shipped, delivered, pick_up}
barcode_url	The URL to the image of a receipt barcode	string	Yes
merchant_receipt_id	Merchant generated ID for the receipt	string	No
order_type	Location of where the transaction took place	string	Yes	Valid values include {web, in_store, phone, third_party_delivery}
received_ts	Timestamp when Banyan ingested the receipt	timestamp-millis	No	Presented in UTC
purchase_ts	Timestamp when the customer made the purchase	timestamp-millis	No	Presented in UTC
image_url	The URL to the image of the receipt	string	Yes
merchant_mid	The merchant id provided by the acquiring bank	string	Yes
payment	top level object	record
item	top level object	array
hotel	top level object	map

etx.receipt.payment

Payments (AKA tenders) are the way that the goods are paid for on the receipt. While there may be more than one payment on a single receipt, your eTx will only contain the payment that pertains to your transaction sent to Banyan. Given this, there is a possibility that the total amount on the receipt (or items amount paid total) will not match your payment amount if more than one payment is used on the receipt. This is not an error, it is the sign of a split tender.

Element	Description	Data Type	Nullable?
subtotal_amount	Total amount less tax amount	numeric	No
shipping_amount	Amount paid for a ship or delivery fulfillment type	numeric	Yes
total_amount	Amount paid by the customer	numeric	No
payment_type	Credit card vs Debit card transaction	string	Yes
tax_amount	Sales tax amount	numeric	No
other_negative_amounts	Any negative amounts included in the total amount that are not specified	numeric	Yes
other_positive_amounts	Any additional amounts included in the total amount that are not specified	numeric	Yes

etx.receipt.item

Element	Description	Data Type	Nullable?	Notes
image_url	The URL for the image of the receipt if available	string	Yes
description	Describes the Item	string	Yes
brand	Brand name of item	string	Yes
full_price_per_unit	The regular price for the item specified in the item id	numeric	No	Up to 2 decimal places
merchant_item_id	Unique ID for the item sold in the transaction	string	Yes	This ID is a sequencing ID on the receipt. It could be a unique ID from the basket detail table or a counter on each receipt. Used for QA purposes.
byn_item_id	Banyan generated ID for each item in the array	string	No
upc	Universal product code	string	Yes	Including check number
sku	Store specific ID of item	string	Yes
unit_type	The unit the item is sold in	string	Yes
tags	Labels provided by the taxonomy of the merchant in the form of key value pairs	array of strings	Yes	Each merchant will have different tag key value pairs
discount_price_per_unit	The amount paid for the item	numeric	No	Up to 2 decimal places
quantity	Number of the same item purchased	numeric	No	Up to 2 decimal places
amount_paid	Total amount paid for the item, quantity*discount_price_per_unit	numeric	No	Up to 2 decimal places

etx.receipt.merchant

Element	Description	Data Type	Nullable?	Notes
name	DBA of merchant	string	Yes
display_name	Store display name	string	Yes

etx.receipt.location

Element	Description	Data Type	Nullable?
merchant_store_id	ID for the specific location under the merchant	string	Yes
name	DBA of the store	string	Yes
display_name	Store display name	string	Yes
phone number	Phone number of the store	string	Yes
address	Next level object	object

etx.receipt.location.address

Element	Description	Data Type	Nullable?
address_line_one	First line of street address of the store	string	Yes
address_line_two	Apartment, suite number of the store	string	Yes
city	City of the store	string	Yes
state	State of the store	string	Yes
postal_code	Postal code of the store	string	Yes
country_code	Country code of the store	string	Yes

etx.transaction

The transaction data that you have sent to Banyan will be returned to you within the enriched transaction record to make it easy to join within your systems using your transaction_id (finx_transaction_id).

Element	Description	Data Type	Nullable?	Notes
finx_transaction_id	Unique transaction id from the finx	string	No
received_ts	Timestamp of when Banyan ingested the record	timestamp-millis	No
byn_transaction_id	Banyan created transaction id	string	No	This ID can be used to query the Banyan GET /transaction API end point
order_type	FinX designation of web or in store transaction	string	Yes
description	Description of the transaction provided by the finx	string	Yes
finx_consumer_token	Finx created ID for the account or user	string	Yes
payment	Top level object
location	Top level object
merchant	Top level object

etx.transaction.payment

Element	Description	Data Type	Nullable?
finx_mid	A merchant identification number (MID) is a distinctive, numerical code that identifies a merchant to their acquirer.	string	Yes
card_last_four	Last 4 digits on the debit card, credit card	string	Yes
arn	A unique 16-digit number that tags a credit or debit card transaction when it goes from the merchant’s bank through to the cardholder's bank. Also called a trace ID, this number is often used to determine where a transaction's funds lie at a certain time, and make a transaction traceable in case of an error in bank or merchant accounts.	string	Yes
scheme	The network the card was issued on	string	Yes
bin	Bank Identification Number associated with the card used	string	Yes
payment_type	Credit card vs Debit card transaction	string	Yes
currency	3 lettered code of the currency the amount is in	string	No
auth_code	Six digit alphanumeric code passed between banks that signal a transaction is possible	string	Yes
total_amount	Amount paid for goods/services	string	No

etx.transaction.location

Element	Description	Data Type	Nullable?
merchant_store_id	ID for the specific location under the merchant	string	Yes
name	DBA of the store	string	Yes
display_name	Store display name	string	Yes
phone_number	Phone number of the store	string	Yes
address	Top level object	string	Yes

etx.transaction.location.address

Element	Description	Data Type	Nullable?
address_line_one	First line of street address of the store	string	Yes
address_line_two	Apartment, suite number of the store	string	Yes
city	City of the store	string	Yes
state	State of the store	string	Yes
postal_code	Postal code of the store	string	Yes
country_code	Country code of the store	string	Yes

eTx Example


  "data": [
    {
      "id": "403abe9b-cd9b-43f5-bdc9-924c8e17be77",
      "campaign": {
        "byn_campaign_id": "74567b52-18ca-5974-bb30-8d67830ee080",
        "name": "Walgreens Rewards",
        "byn_publisher_id": 316,
        "created_ts": "2024-08-15T21:32:04.131143Z",
        "updated_ts": "2024-08-15T21:32:04.131143Z"
      },
      "offer_activation": null,
      "offer": {
        "byn_offer_id": "70770c15-0d5b-5e74-89e7-da17a7c19d49",
        "name": "082624: Walgreens 2.5% On Non Private Label Items",
        "publisher_offer_id": "08262024B",
        "return_receipt_detail": true,
        "always_on": true,
        "byn_advertiser_id": 327,
        "byn_publisher_id": 316,
        "amount_back_limit": "0",
        "amount_back_per_dollar": "0.025",
        "amount_back_type": "DOLLAR",
        "start_ts": "2024-08-26T04:00:00Z",
        "expiration_ts": "2025-08-27T03:59:00Z",
        "offer_criteria": {
          "order_types": [
            "any"
          ],
          "item_qualification_expression": "\"PRIVATE_LABEL_IND:|:N\"",
          "item_disqualification_expression": "\"excluded:|:excluded item\"",
          "incl_tags": [
            "PRIVATE_LABEL_IND:|:N"
          ],
          "excl_tags": [
            "excluded:|:excluded item"
          ],
          "incl_sku": [],
          "excl_sku": [],
          "amount_threshold": "0",
          "fulfillment_count_limit": 0
        },
        "offer_hotel_criteria": null,
        "created_ts": "2024-08-15T21:38:00.568616Z",
        "updated_ts": "2024-08-15T21:38:00.568616Z",
        "currency": "",
        "allow_activation_after_purchase": true,
        "prorate_qualified_spend": true,
        "card_issuer": "",
        "card_types": null,
        "activation_window_minutes": null
      },
      "result": {
        "items": {
          "qualified_total_amount": "0.39",
          "qualified_ids": [
            "1b8a79d5-5562-5e37-9f39-e83105d98c16"
          ],
          "unqualified_ids": []
        },
        "fulfilled": true,
        "cumulative_qualified_total_amount": "0.39",
        "amount_back": "0.01",
        "hotel": {
          "qualified_dining_charges": null,
          "unqualified_dining_charges": null,
          "total_qualified_dining_spend": "0",
          "qualified_room_charges": null,
          "unqualified_room_charges": null,
          "total_qualified_room_spend": "0"
        }