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 MetaData
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
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?
Notes
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?
Notes
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
receipt.location.address
Element
Description
Data Type
Nullable?
Notes
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?
Notes
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
