Batch Enriched Transaction Schema

Descriptions of output fields

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 MetaData

ElementDescriptionData TypeNullable?Notes
byn_etx_idUnique ID generated by Banyan when creating the enriched recordstringNo
byn_match_idUnique ID generated by Banyan when a receipt is married with a transactionstringNo
match_tsTimestamp of when the receipt is married with a transactiontimestamp-millisNoRecorded in UTC

receipt

ElementDescriptionData TypeNullable?Notes
byn_receipt_idUnique ID created by Banyan to represent a receipt received from a merchantstringNo
currencyCurrency of the total amountnumericNo
merchant_total_amountTotal amount for the entire receiptnumericNoCould be different than payment.total_amount if there is a split tender on the receipt
fulfillment_typeHow the items are received by the customerstringYesValid values include {in_store, shipped, delivered, pick_up}
barcode_urlThe URL to the image of a receipt barcodestringYes
merchant_receipt_idMerchant generated ID for the receiptstringNo
order_typeLocation of where the transaction took placestringYesValid values include {web, in_store, phone, third_party_delivery}
received_tsTimestamp when Banyan ingested the receipttimestamp-millisNoPresented in UTC
purchase_tsTimestamp when the customer made the purchasetimestamp-millisNoPresented in UTC
image_urlThe URL to the image of the receiptstringYes
merchant_midThe merchant id provided by the acquiring bankstringYes
paymenttop level objectrecord
itemtop level objectarray
hoteltop level objectmap

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.

ElementDescriptionData TypeNullable?Notes
subtotal_amountTotal amount less tax amountnumericNo
shipping_amountAmount paid for a ship or delivery fulfillment typenumericYes
total_amountAmount paid by the customernumericNo
payment_typeCredit card vs Debit card transactionstringYes
tax_amountSales tax amountnumericNo
other_negative_amountsAny negative amounts included in the total amount that are not specifiednumericYes
other_positive_amountsAny additional amounts included in the total amount that are not specifiednumericYes

receipt.item

ElementDescriptionData TypeNullable?Notes
image_urlThe URL for the image of the receipt if availablestringYes
descriptionDescribes the ItemstringYes
brandBrand name of itemstringYes
full_price_per_unitThe regular price for the item specified in the item idnumericNoUp to 2 decimal places
merchant_item_idUnique ID for the item sold in the transactionstringYesThis 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_idBanyan generated ID for each item in the arraystringNo
upcUniversal product codestringYesIncluding check number
skuStore specific ID of itemstringYes
unit_typeThe unit the item is sold instringYes
tagsLabels provided by the taxonomy of the merchant in the form of key value pairsarray of stringsYesEach merchant will have different tag key value pairs
discount_price_per_unitThe amount paid for the itemnumericNoUp to 2 decimal places
quantityNumber of the same item purchasednumericNoUp to 2 decimal places
amount_paidTotal amount paid for the item, quantity*discount_price_per_unitnumericNoUp to 2 decimal places

receipt.merchant

ElementDescriptionData TypeNullable?Notes
nameDBA of merchantstringYes
display_nameStore display namestringYes

receipt.location

ElementDescriptionData TypeNullable?Notes
merchant_store_idID for the specific location under the merchantstringYes
nameDBA of the storestringYes
display_nameStore display namestringYes
phone numberPhone number of the storestringYes
addressNext level objectobject

receipt.location.address

ElementDescriptionData TypeNullable?Notes
address_line_oneFirst line of street address of the storestringYes
address_line_twoApartment, suite number of the storestringYes
cityCity of the storestringYes
stateState of the storestringYes
postal_codePostal code of the storestringYes
country_codeCountry code of the storestringYes

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

ElementDescriptionData TypeNullable?Notes
finx_transaction_idUnique transaction id from the finxstringNo
received_tsTimestamp of when Banyan ingested the recordtimestamp-millisNo
byn_transaction_idBanyan created transaction idstringNoThis ID can be used to query the Banyan GET /transaction API end point
order_typeFinX designation of web or in store transactionstringYes
descriptionDescription of the transaction provided by the finxstringYes
finx_consumer_tokenFinx created ID for the account or userstringYes
paymentTop level object
locationTop level object
merchantTop level object

transaction.payment

ElementDescriptionData TypeNullable?Notes
finx_midA merchant identification number (MID) is a distinctive, numerical code that identifies a merchant to their acquirer.stringYes
card_last_fourLast 4 digits on the debit card, credit cardstringYes
arnA 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.stringYes
schemeThe network the card was issued onstringYes
binBank Identification Number associated with the card usedstringYes
payment_typeCredit card vs Debit card transactionstringYes
currency3 lettered code of the currency the amount is instringNo
auth_codeSix digit alphanumeric code passed between banks that signal a transaction is possiblestringYes
total_amountAmount paid for goods/servicesstringNo

transaction.location

ElementDescriptionData TypeNullable?Notes
merchant_store_idID for the specific location under the merchantstringYes
nameDBA of the storestringYes
display_nameStore display namestringYes
phone_numberPhone number of the storestringYes
addressTop level objectstringYes

transaction.location.address

ElementDescriptionData TypeNullable?Notes
address_line_oneFirst line of street address of the storestringYes
address_line_twoApartment, suite number of the storestringYes
cityCity of the storestringYes
stateState of the storestringYes
postal_codePostal code of the storestringYes
country_codeCountry code of the storestringYes

eTx Example

[
   {
      "byn_etx_id": {
         "string": "7jeif9q8y82tu09jqfjuhj7"
      },
      "byn_match_id": {
         "string": "7rHAcSJxass5rTKVG5xaZb"
      },
      "match_ts": 1667416310635,
      "receipt": {
         "currency": {
            "string": "usd"
         },
         "merchant_total_amount": {
            "string": "118.64"
         },
         "payment": {
            "com.banyan.datamodel.egress.receipt_payment": {
               "subtotal_amount": {
                  "string": "110.88"
               },
               "shipping_amount": null,
               "tip_amount": {
                  "string": "0.00"
               },
               "total_amount": {
                  "string": "118.64"
               },
               "payment_type": {
                  "string": "credit"
               },
               "tax_amount": {
                  "string": "7.76"
               },
               "other_negative_amounts": null,
               "scheme": {
                  "string": "Hiper"
               },
               "other_positive_amounts": null,
               "cash_back_amount": {
                  "string": "0.00"
               }
            }
         },
         "merchant": {
            "com.banyan.datamodel.egress.merchant": {
               "name": {
                  "string": "Center for Responsive Politics, LLC"
               },
               "display_name": {
                  "string": "Center for Responsive Politics"
               },
               "created_ts": {
                  "long.timestamp-millis": 1667416310634
               }
            }
         },
         "fulfillment_type": {
            "string": "ship"
         },
         "barcode_url": {
            "string": "https://centerforresponsivepolitics.com/receipt/barcode/874271786565"
         },
         "hotel": null,
         "merchant_receipt_id": "874271786565",
         "order_type": {
            "string": "web"
         },
         "received_ts": 1667416310634,
         "byn_receipt_id": "mqDftBjfAmbvJbrawuTCJ4",
         "image_url": {
            "string": "https://centerforresponsivepolitics.com/receipt/image/874271786565"
         },
         "location": {
            "com.banyan.datamodel.egress.location": {
               "merchant_store_id": {
                  "string": ""
               },
               "name": {
                  "string": "StreetCred Software, Inc"
               },
               "display_name": {
                  "string": "StreetCred Software, Inc"
               },
               "phone_number": {
                  "string": "(057)934-6859"
               },
               "address": {
                  "com.banyan.datamodel.egress.address": {
                     "address_line_two": {
                        "string": ""
                     },
                     "city": {
                        "string": "Kilbackland"
                     },
                     "state": {
                        "string": "New Jersey"
                     },
                     "country": {
                        "string": "USA"
                     },
                     "postal_code": {
                        "string": "54300"
                     },
                     "created_ts": {
                        "long.timestamp-millis": 1667416310634
                     },
                     "address_line_one": {
                        "string": "8702 Lake Prairie chester"
                     }
                  }
               },
               "created_ts": {
                  "long.timestamp-millis": 1667416310634
               }
            }
         },
         "items": {
            "array": [
               {
                  "image_url": {
                     "string": ""
                  },
                  "description": {
                     "string": "Voluptas dolores voluptatem vel eos est aut et ut voluptatem."
                  },
                  "brand": {
                     "string": "Audi"
                  },
                  "full_price_per_unit": {
                     "string": "8.36"
                  },
                  "merchant_item_id": {
                     "string": "966394"
                  },
                  "byn_item_id": {
                     "string": "kQwaSugtFrg3ij5ZZZ9rtN"
                  },
                  "upc": {
                     "string": "264312991556"
                  },
                  "sku": {
                     "string": ""
                  },
                  "unit_type": {
                     "string": ""
                  },
                  "tags": {
                     "array": [
                        "etsy:|:put a bird on it",
                        "cred:|:gluten-free",
                        "raw denim:|:bespoke"
                     ]
                  },
                  "discount_price_per_unit": {
                     "string": "0.00"
                  },
                  "quantity": {
                     "string": "2.00"
                  },
                  "amount_paid": {
                     "string": "16.72"
                  }
               },
               {
                  "sku": {
                     "string": ""
                  },
                  "brand": {
                     "string": "Smart"
                  },
                  "amount_paid": {
                     "string": "47.79"
                  },
                  "discount_price_per_unit": {
                     "string": "0.00"
                  },
                  "unit_type": {
                     "string": ""
                  },
                  "full_price_per_unit": {
                     "string": "47.79"
                  },
                  "merchant_item_id": {
                     "string": "952662"
                  },
                  "byn_item_id": {
                     "string": "Rr9QbnzyVWyy5Nb4bb6zgR"
                  },
                  "upc": {
                     "string": "819547922411"
                  },
                  "image_url": {
                     "string": ""
                  },
                  "description": {
                     "string": "Minus ipsum commodi dolor et quia repellat rerum recusandae neque."
                  },
                  "quantity": {
                     "string": "1.00"
                  },
                  "tags": {
                     "array": [
                        "occupy:|:vegan"
                     ]
                  }
               },
               {
                  "brand": {
                     "string": "Subaru"
                  },
                  "amount_paid": {
                     "string": "25.89"
                  },
                  "full_price_per_unit": {
                     "string": "8.63"
                  },
                  "merchant_item_id": {
                     "string": "479316"
                  },
                  "description": {
                     "string": "Aut numquam quia repellat omnis unde voluptas ullam in voluptatum."
                  },
                  "discount_price_per_unit": {
                     "string": "0.00"
                  },
                  "sku": {
                     "string": ""
                  },
                  "image_url": {
                     "string": ""
                  },
                  "byn_item_id": {
                     "string": "xVJgiYKjhunKaAjTwNxTf"
                  },
                  "upc": {
                     "string": "447503722540"
                  },
                  "quantity": {
                     "string": "3.00"
                  },
                  "unit_type": {
                     "string": ""
                  },
                  "tags": {
                     "array": [
                        "seitan:|:pop-up",
                        "skateboard:|:pop-up",
                        "cardigan:|:fixie"
                     ]
                  }
               },
               {
                  "tags": {
                     "array": [
                        "lumbersexual:|:tote bag",
                        "post-ironic:|:cardigan",
                        "photo booth:|:intelligentsia",
                        "offal:|:plaid"
                     ]
                  },
                  "image_url": {
                     "string": ""
                  },
                  "upc": {
                     "string": "037384008514"
                  },
                  "brand": {
                     "string": "Opel"
                  },
                  "merchant_item_id": {
                     "string": "846840"
                  },
                  "byn_item_id": {
                     "string": "ArPMe2iM9TEYrfTXKUAKZd"
                  },
                  "sku": {
                     "string": ""
                  },
                  "description": {
                     "string": "Excepturi atque voluptas qui ipsum enim aut porro aliquid ut."
                  },
                  "discount_price_per_unit": {
                     "string": "0.00"
                  },
                  "quantity": {
                     "string": "2.00"
                  },
                  "amount_paid": {
                     "string": "20.48"
                  },
                  "full_price_per_unit": {
                     "string": "10.24"
                  },
                  "unit_type": {
                     "string": ""
                  }
               }
            ]
         },
         "purchase_ts": {
            "long.timestamp-millis": 1649929060991
         },
         "merchant_mid": {
            "string": "hFNbkYVftofduzLoBWoRWG"
         }
      },
      "transaction": {
         "received_ts": 1667416310634,
         "payment": {
            "com.banyan.datamodel.egress.transaction_payment": {
               "finx_mid": {
                  "string": "Av7GUfRUPeiMAHJ7taZLia"
               },
               "card_last_four": {
                  "string": "8208"
               },
               "arn": {
                  "string": "25674216341"
               },
               "scheme": {
                  "string": "Discover"
               },
               "bin": {
                  "string": "684872879"
               },
               "payment_type": {
                  "string": "credit"
               },
               "currency": {
                  "string": "NGN"
               },
               "auth_code": {
                  "string": "176024"
               },
               "total_amount": {
                  "string": "118.64"
               }
            }
         },
         "merchant": {
            "com.banyan.datamodel.egress.merchant": {
               "name": {
                  "string": "Center for Responsive Politics, LLC"
               },
               "display_name": {
                  "string": "Center for Responsive Politics"
               },
               "created_ts": {
                  "long.timestamp-millis": 1667416310634
               }
            }
         },
         "finx_transaction_id": {
            "string": "DeJKTCrAucNAqoBWsSDDQh"
         },
         "order_type": {
            "string": "in_store"
         },
         "byn_transaction_id": "ME8bHYVSvFJzHwuHJbZhs9",
         "purchase_ts": {
            "long.timestamp-millis": 1649929060991
         },
         "description": {
            "string": "DDCPddrlFXEXVvTAOTDVOWxfEHUGJvXtRqlCNOtttkuQEKwjzqrTCmaEjcoLqoWjxAtoMwkHRfByIEZRlgdXECf"
         },
         "finx_consumer_token": {
            "string": "8oGKsMDX5Yy2ebsi2NQ3iD"
         },
         "location": {
            "com.banyan.datamodel.egress.location": {
               "created_ts": {
                  "long.timestamp-millis": 1667416310634
               },
               "merchant_store_id": {
                  "string": ""
               },
               "name": {
                  "string": "StreetCred Software, Inc"
               },
               "display_name": {
                  "string": "StreetCred Software, Inc"
               },
               "phone_number": {
                  "string": "(057)934-6859"
               },
               "address": {
                  "com.banyan.datamodel.egress.address": {
                     "state": {
                        "string": "New Jersey"
                     },
                     "country": {
                        "string": "USA"
                     },
                     "postal_code": {
                        "string": "54300"
                     },
                     "created_ts": {
                        "long.timestamp-millis": 1667416310634
                     },
                     "address_line_one": {
                        "string": "8702 Lake Prairie chester"
                     },
                     "address_line_two": {
                        "string": ""
                     },
                     "city": {
                        "string": "Kilbackland"
                     }
                  }
               }
            }
         }
      }
   }
]