Beautiful Transaction Feed
#
OverviewMaking a bank transaction feed look beautiful is one of the core applications of Heron Data. The key outcomes we help our customers achieve are:
- Cleaner, shorter transaction descriptions
- A logo or icon for each merchant
- A unique identifier per merchant, which can be used as a basis for further logic
- [Optional] Categories to show your customer where they are spending.
This helps with an application interface that builds trust and engagement with customers.
If you have bank transaction data for a consumer, jump here.
If you have bank transaction data for a business proceed with the next section!
#
Enrich business dataHeron Data is optimized for high coverage and accuracy on SMB merchants and categories. Follow this flow to achieve optimal outcomes.
#
Create an end user and enrich transactions- Create an end_user: Begin by creating an end_user in Heron’s systems that corresponds to a company in your systems. You do this by sending a POST
end_users
request.- For the
end_user_id
field, use a unique canonical reference/identifier for the company - Note: If you are sending transactions for a company that you’ve already sent to Heron before, skip this step.
- For the
- Post transactions. Once you have created the end_user, you can start POST’ing transactions for that end_user. Make sure that the
end_user_id
in the payload matches theend_user_id
you created in 1). You do this by sending POST/transactions
requests.- As noted, please batch to 1000 transactions or fewer
- Note: If you receive transactions directly from Plaid or Ocrolus, we allow you to just pass on the json file without any manipulation. This replaces using the
/transactions
endpoint in this step. The endpoints you can use are:
- Process Transactions: When you are done sending us transactions for a company, please send a PUT
end_users
request, indicating that the end_user isready
for processing. - Listen to webhook: We will notify you via a webhook when the
end_user_id
isprocessed
and available for you to retrieve. You can configure your webhook in the dashboard. - Get transactions: Once you have received the webhook, you can send a GET
/transactions
request to retrieve the enriched data. Most customers use theend_user_id
parameter to ensure they only pull transactions for theend_user_id
that was just enriched.- Note: If you getting transactions for a company that you’ve already sent to Heron before, you can use the
last_updated_min
filter to only get transactions where labels have changed since the value of the filter.
- Note: If you getting transactions for a company that you’ve already sent to Heron before, you can use the
You now have enriched data for a given company. Proceed by looking at best practises to display back information!
#
Enrich consumer datacaution
For this use case, please limit batch sizes to 249 transactions maximum.
- Post Transactions: Send POST
/transactions
requests. Make sure that theend_user_id
in the payload matches a canonical identifier for the consumer from your systems.- Note that in the payload, only
amount
anddescription
are required. For best results, we recommend also sendingtimestamp
ordate
andend_user_id
- Note that in the payload, only
- Parse response: In the response to this
POST
request, you will receive back all items you need for a beautiful transaction feed!
#
How to display the enriched transactionsDescription/name
- You should display back the
merchant.name
where available. - If no
merchant.name
is available, display back either thepayment_processor
or thedescription_clean
.payment_processor
is the name of the company that processed the payment, like Square, Stripe, Shopify, etc.description_clean
will always be a substring of thedescription
, but without information about payment methods, store numbers, transaction dates, amounts, etc.
Example
If you send a description like SQ* 01203433383 ESPRESSO CIELO SANTA MONICA CA
, you receive back:
Which one you choose to display back depends on your use case. Note that payment_processor
will always have a logo/icon attached.
Logo/icon
- You will receive back either a
logo_url
, anicon_url
or both - The logo is generally rectangular, and the icon is a square
- Both are either in
png
orsvg
format - The icon/logo are hosted in one of our Google Cloud Storage buckets, and the URL is static with format:
- Icon:
https://storage.googleapis.com/heron-merchant-assets/icons/{merchant_heron_id}.{png|svg}
- Logo:
https://storage.googleapis.com/heron-merchant-assets/logos/{merchant_heron_id}.{png|svg}
- Icon:
Unique identifier
- You will receive back a unique identifier, the
heron_id
, for each merchant. You can use this identifier as a basis for further logic. For example:- Allow your users to choose a custom category for a specific merchant, based on that merchant's
heron_id
. - Show your users all spend with one merchant by aggregating all spend on one merchant
heron_id
.
- Allow your users to choose a custom category for a specific merchant, based on that merchant's
Categories [optional]
tip
If you do not currently receive categories but would like to receive them, please contact Heron!
If categories are enabled for you, you will receive them back as a dictionary in the transactions object (see here). You can display back the
label
to your customer, or assign a static logo to each category instead.For more use cases around business data categories, please follow the SMB Analytics Tutorial.
#
FeedbackWe want to receive feedback on incorrect merchants and categories whenever possible, so we can make improvements. There are two ways you can share feedback with us:
- Manual: You can send us free-form feedback in our shared Slack channel. We also share spreadsheets with customers that enable them to share feedback with us, which we can also make available via Slack.
- Automated: You can implement the
transactions/{heron_id}/feedback
endpoint so that your users or your operations staff can transmit feedback to us in an automated manner. You can use this endpoint both to send us corrected categories and/or corrected merchants.