Merchant Data Onboarding Guide

Banyan provides the infrastructure for merchants to send receipt level data directly to financial institutions and fintechs without having to enter into contracts directly with each one. Financial institutions can then use the receipt data to better serve the consumer by enhanced fraud detection, issuing more relevant card linked offers, or displaying line item information for each transaction in the banking or budgeting application.

Integrate your receipt level and taxonomy data with control and transparency using one of the many ingestion options that Banyan provides:

Batch Push

Our preference is to receive fresh data at least once per day, but we can work with whatever cadence makes sense for your business. We have a Google Cloud Storage data lake that we will provision access to where you will have a dedicated bucket to write daily data. In addition, if you prefer writing via SFTP, we will have that option available and Banyan will copy the data over programmatically into the data lake.


We currently support sending one by one submissions of receipt data according to our schema using a POST call. Please see the reference doc for what we need within each call:

Please contact your representative for an API key if this is your preferred method of sharing data. In the near future we will also support sending batches of data via the POST call.

Preferred Data Formats

Parquet (compressed with snappy)
TSV/CSV (compressed with gzip/lzo)

Batch Data Model Options

We understand that your purchase data may be dispersed among many warehouses or tables. We are happy to do the work of joining your data for you. If you already are sending this data to another partner and have it pre-joined, we will accept that as well.

Example Unflattened Data Layout

What to Expect During the Setup Process

There are several steps to complete before programmatic data transfer can begin:

  1. Complete the data onboarding questionnaire (hyperlink to questionnaire)
  2. Send over representative sample data, preferably 8 days of transactions
  3. This may involve some back and forth with Banyan data engineers and change requests of the feed before going live

As part of the provisioning process you will receive the following from Banyan:

  • A set of required, preferred, and optional fields to include in your data transfer
  • Keys for Cloud or SFTP Storage


How long does onboarding typically take?
The entire process typically takes 2-3 weeks. The portion of the process that can lengthen this timeframe is the Data QA which may uncover work to be done by the merchant to pull in additional fields.

How should I represent split tenders?
The file should include n number of rows per transaction/item for n number of cards used. The tender type should show the difference if this is split between cash and card or if more than one card is used, the last4 should show which amount is associated with each card.

How should I represent returned items?
Returned items should have the same transaction id with a negative value for total amount to indicate that money was returned to the customer. A corresponding item(s) record also with a negative value for amount should also be sent to Banyan.

What if I don't have access to a required field within my data warehouse?
If one of our preferred, but not required fields is unavailable, no additional action needs to be taken. If it is one of our required fields we may need to work with you to figure out where in your processing pipeline we can extract the necessary information.

Should I include PII with transaction information?
No. Banyan does not accept any PII in its data feeds.

What do you consider to be PII?
Any information that can help identify the customer: customer email, customer address, customer phone number, and customer name are examples of PII that we will not accept. If you have questions on whether some of the information you're sending over is PII, please contact your Banyan representative with the question before sending your data.

Should I send you only credit card transactions or all transactions?
Send Banyan all transactions and if possible include what the tender type was with each transaction (including gift cards and/or purchases with loyalty points used).

Did this page help you?