Braintree Integration Guide

If you're new to ChartMogul, learn how we import subscription data to generate metrics.

You’ll need to be an Admin in ChartMogul and have the Account Admin role in Braintree to complete the steps outlined in this article.

Braintree is one of ChartMogul’s supported billing systems, allowing you to import customer, subscription, and transaction data to generate subscription analytics and cash flow metrics.

Here’s what we cover in his article:

Overview

The following table provides details on key aspects of how ChartMogul integrates with Braintree.

Customer import event ChartMogul imports customers when they start a subscription in Braintree.
Leads Braintree does not track the date a lead is created. So, ChartMogul calculates Lead created at by taking the customer’s first billing date, subtracting the trial duration, and adjusting the result to your time zone. Learn more about tracking leads and trials.
Free trials ChartMogul imports free trial dates.
Custom attributes ChartMogul does not import custom attributes. It is, however, possible for you to create and populate custom attributes manually. Learn more.
Historical data After adding Braintree as a source, ChartMogul imports all existing customer, subscription, and transaction data.
Credits Credits in Braintree are not imported by ChartMogul.
Reviewing subscription data in-app using our Data Platform For select billing systems, ChartMogul gives complete visibility into your data as it exists in our platform through a series of data tables. These data tables are, unfortunately, not currently available for Braintree.
Tax handling Braintree does not separate taxes into separate invoice line items. As a result, ChartMogul is unable to determine the tax amount of the transaction, and tax is included in subscription revenue.
Automated tags ChartMogul does not add any automated tags to customers. Instead, learn how to add tags in-app or using our API.
Voided transactions Voided transactions in Braintree are imported by ChartMogul.
Update frequency Real-time. Learn more.
Maintained by This integration is built and maintained by ChartMogul. Contact our support team for assistance.

Data Settings

The following table provides details on how ChartMogul’s data settings work with your billing system.

Smart Activity Classification Fully supported. Learn more.
Auto-churn of Delinquent Subscriptions Fully supported. Learn more.
Churn Recognition Fully supported. Learn more.
Free Customer Handling Fully supported. Learn more.
Refund Handling ChartMogul does not deduct refunded transactions from Monthly Recurring Revenue (MRR).
Transaction Fee Handling ChartMogul does not import transaction fees from Braintree, and as a result, transaction fees are automatically excluded from MRR calculations. 

Source configuration

Each Braintree source in ChartMogul consists of the following configuration elements:

  • Environment — the Braintree environment ChartMogul imports data from.
  • Public Key — the public key assigned to the read-only user you create in Step 1.
  • Private Key — the private key assigned to the read-only user you create in Step 1.
  • Merchant ID — the unique identifier for your entire Braintree payment gateway account.
  • Fixed term add-on — an option to exclude fixed-term add-ons from recurring revenue in ChartMogul. Fixed-term add-ons have a set number of billing cycles in Braintree (i.e., they are not billed in perpetuity).
  • Webhook URL — the webhook URL assigned by ChartMogul to your Braintree source. Used as part of Step 3 to keep data in ChartMogul synced with Braintree.
  • Name — a unique name for your Braintree source that enables you to identify where data in ChartMogul is coming from.

Before you begin

Please review these details before completing the following steps.

  • Select which Braintree environment ChartMogul will import data from, either Sandbox or Production. Learn more.
  • Locate your Braintree Merchant ID.

Connecting Braintree to ChartMogul

Step 1 — Create a read-only API key

ChartMogul uses API keys to connect Braintree to ChartMogul. For added security, we recommend creating a read-only user in Braintree and using the API keys from this user to grant ChartMogul access to your Braintree account.

  1. Log in as admin to your Braintree account, navigate to Settings > Team > Roles, then click + New Role.
  2. Name the role, e.g., ChartMogul Read-only.
  3. Grant the role the following permissions:
    • Transactions > Download Transactions with Masked Payment Data
    • Customer Management > Download Vault Records with Masked Payment Data
    • Recurring Billing
      • Download Subscription Records
      • View Modifications
      • View Subscription Plans
      • View Subscriptions
      • Search Subscriptions
    • Read-Only Access (check all permissions)
    • Search (check all permissions)
  4. Next, go to Settings > Team > Users and click + New user.
  5. Enter an email address for the new account in the Email field. (Braintree will send an activation email link address.)
    • Under API Access, select API Access.
    • Under Roles, select the read-only role (e.g., ChartMogul Read-only) you created in Step 1
    • Assign access to your merchant account(s) (typically All).
  6. Click Create User.
  7. Log out of Braintree, activate the new read-only user you just created (using the activation link you should have received from Braintree), and log back in as the new user.
  8. Next, navigate to Account > My User.
  9. Under API Keys, Tokenization Keys, Encryption Keys, click View Authorizations.
  10. Under API Keys, note the Public Key and Private Key. You'll need these in Step 2 when adding Braintree as a source in ChartMogul.
  11. Log out of Braintree.

Step 2 — Add Braintree as a source

Next, add Braintree as a source in ChartMogul:

  1. Within ChartMogul, navigate to Data Platform > Sources.
  2. Click ADD A SOURCE and select Braintree.
  3. Enter a unique name for your source in the Name field and click Next.
  4. From the Environment drop-down, select either Sandbox or Production.
  5. In the fields provided, enter the Public Key and Private Keys assigned to the read-only user you created in Step 1.
  6. Enter your Merchant ID in the field provided.
  7. Click SAVE.
  8. ChartMogul will then generate a Webhook URL that you'll need in Step 3.

Step 3 — Add a webhook in Braintree to keep your data synced

  1. Log in to Braintree using your Account Admin credentials.
  2. Navigate to Settings > API > Webhooks.
  3. Click + CreateNew Webhook, then paste in the Webhook URL from Step 2 in the Destination URL field.
  4. Under Notifications, check the following options:
    • Canceled
    • Charged Successfully
    • Charged Unsuccessfully
    • Expired
    • Went Active
    • Went Past Due
  5. Finally, click Create Webhook.

Step 4 — Import your Braintree data

In ChartMogul, click IMPORT DATA. This will connect the Braintree webhook to ChartMogul and start your data import.

The import can take some time, depending on the number of customers. After the import has concluded, ChartMogul will update automatically with any new activity from Braintree.

ChartMogul automatically imports all data once you’ve successfully connected it to Braintree. No further action is needed to import historical data.

Manually re-syncing data

Re-syncing your Braintree source will not cause any changes you’ve subsequently made to customers and their subscriptions inside ChartMogul — such as manually editing MRR, merging customers, adding custom attributes, or connecting subscriptions — to be lost.

Here’s how to manually re-sync data when needed:

  1. Within ChartMogul, navigate to Data Platform > Sources.
  2. Find your Braintree source and click the Settings  icon.
  3. Click RE-SYNC DATA.

ChartMogul will start re-importing your data and let you know where it’s at with a progress bar.

Next Steps

Was this article helpful?

We’re sorry to hear that. Would you like to share more feedback?


Thanks for your feedback!