Connecting PayPal to ChartMogul

You’ll need to be an Admin in both ChartMogul and PayPal to complete the following steps

This article covers the steps involved with connecting PayPal to ChartMogul:

  1. Creating an app in PayPal
  2. Adding a data source in ChartMogul
  3. Enabling Instant Payment Notifications in PayPal
  4. Downloading Profile IDs from PayPal
  5. Uploading Profile IDs to ChartMogul
  6. Configuring Transaction Fee Handling in ChartMogul

Please also review the Additional Notes section of this article before setting up this integration.

Before you begin

Compatibility with PayPal offerings

It’s important to understand PayPal offers several payment services for both subscription and non-subscription products.

ChartMogul supports the following PayPal payment solutions for products and services sold on a subscription basis:

Unfortunately, we don’t currently support the following:

If you’re using other PayPal payment solutions — or aren’t sure which solution you’re using — please contact us to find out if our integration will support your needs.

How your data gets from PayPal into ChartMogul

Getting your PayPal data into ChartMogul mainly involves downloading Profile IDs from PayPal and uploading them into ChartMogul:

  1. You’ll first need to locate and download Profile IDs for your subscriptions. PayPal sometimes refers to them as Subscription or Billing Agreement IDs, depending on the payment solution you’re using. Also, the steps involved with downloading Profile IDs differ for each payment solution.
  2. Then, you’ll upload the IDs into ChartMogul.

From there, ChartMogul does the heavy lifting of importing all of the customer, subscription, and transaction data for each ID — in effect, importing your historical data from PayPal. This process can take a few hours to complete, but once it does, you’ll be ready to use ChartMogul.

1. Create an app in PayPal

First, create a new app for ChartMogul in PayPal:

  1. Log into PayPal’s Developer Dashboard.
  2. Switch to Live mode and select Create App.
    Screenshot of PayPay’s interface for creating a REST API app
  3. Enter a name for the app (e.g., ChartMogul) and click Create App.
    Screenshot of PayPay’s interface for entering a name for the app
  4. Keep the Client ID and Secret (under Live API Credentials) handy. You’ll enter these into ChartMogul as part of creating the data source for PayPal.
    Screenshot of PayPal’s interface for creating an app with the Client ID and Secret values highlighted

2. Add a data source in ChartMogul

Using the Client ID and Secret from the previous section, add a data source for PayPal in ChartMogul:

  1. Go to Data Platform.
  2. Under Data Sources, select Add a Data Source.
    Screenshot of the Data Sources page as described
  3. From the list of data sources, select PayPal.
    Screenshot of showing the list of data sources available in ChartMogul
  4. Enter a name for your data source (e.g., PayPal) and click Next.
    Screenshot of data source name field
  5. Copy the Client ID and Secret provided by PayPal into the corresponding fields in ChartMogul.
    PayPal_Add_Data_Source.png
  6. Click Save.
  7. Note the WebHook URL — you’ll need it to enable Instant Payment Notifications.
    PayPal_Add_IPN.png

3. Enable Instant Payment Notifications in PayPal

Enabling Instant Payment Notifications (IPN) in PayPal creates an automatic data sync between PayPal and ChartMogul so that you don't have to export and upload Profile IDs manually going forward. Here's how to set it up:

  1. Log into PayPal and navigate to Account Settings > Notifications (under Business Profile).
  2. For Instant payment notifications, choose Update.
    Screenshot of PayPal’s interface showing how to access the Instant payment notification settings we describe
  3. Click Edit Settings.
  4. Enter the Webhook URL from ChartMogul into the Notification URL field in PayPal.
  5. Choose the Receive IPN messages (Enabled) option.
    Screenshot of PayPal’s Edit Instant Payment Notification (IPN) settings screen
  6. Click Save.
PayPal supports setting up a single IPN per account. If you're already using IPN for another service, you’ll need to forward notifications to ChartMogul.

4. Download Profile IDs from PayPal

Billing Agreements and Billing Plans (deprecated by PayPal)

Download Profile IDs for your active and inactive customers:

  1. Go to PayPal Billing Agreement Report.
  2. Set Filter profile by to Active profiles, Date Range to Year to Date, and click Create Report.
    Screenshot of PayPal’s recurring payments report interface
  3. PayPal will then display a table with your data (i.e., Active profiles or Inactive profiles).
  4. Click Download report and choose CSV.
    Screenshot of PayPal’s download report menu with CSV highlighted
  5. Save the CSV file locally.
  6. Edit the CSV file to remove the title row (e.g., Active profiles or Inactive profiles) and any blank rows that may be present. Do not, however, remove the header row:
    "Profile ID","Description","Payer Name","Status","Amount Last Paid","Outstanding Balance","Next Bill date"
  7. Repeat steps 2–6 three more times with the following report parameters:
    • Filter profiles by = Inactive profiles and Date Range = Year to Date
    • Filter profiles by = Active profiles and Date Range = Last 1 year
    • Filter profiles by = Inactive profiles and Date Range = Last 1 year

After completing these steps, you should have four separate CSV files, which you’ll upload to ChartMogul.

If the report contains no customers (i.e., No data available), you may be storing Billing Agreement IDs in your database. In this case, we suggest working with your developer to access and download the IDs to a CSV file. Billing Agreement IDs have the format I-123450XX.

Subscription API and Smart Payment Buttons

You can find the list of Profile IDs (i.e., Subscription IDs) on the Pay & Get Paid -> Subscriptions page.

At the time of writing this article, PayPal did not provide a way to export all Subscription IDs. Given this, you may be storing Subscription IDs in your database. If this is the case, we suggest working with your developer to download the IDs to a CSV file.

5. Upload Profile IDs to ChartMogul

Upload the CSV files containing the Profile IDs you created in the previous section:

  1. Return to the PayPal Data Source configuration window in ChartMogul.
  2. In the Import Profile IDs from PayPal section, click Choose File, select a CSV file for active profiles, then click Upload List. ChartMogul will then add the IDs from the file to your Profile ID List.
    PayPal_Import_ProfileIDs.png
  3. Repeat step 2 for each of the CSV files you created in the previous section.
  4. Check the Profile ID List to confirm it contains all of the Profile IDs that you want to save and work with in ChartMogul — including the IDs you just uploaded. If the Profile ID List looks correct, click Import Data.
    PayPal_ProfileIDs_List.png

After you click Import Data, ChartMogul retrieves from PayPal customer, subscription, and transaction data for all Profile IDs in your Profile ID List. This process can take a few hours to complete.

Set up the automatic data sync between PayPal and ChartMogul, so you don’t have to manually export, upload, or manage Profile IDs going forward. It’s easy to do — and we highly recommend it.

6. Configure Transaction Fee Handling

As the final step of configuring your new PayPal data source, you’ll need to decide whether ChartMogul should deduct transaction fees from MRR and cash flow metrics.

Screenshot of the Transaction fee handling setting with options for deducting and not deducting fees from MRR and cash flow metrics

Learn more about configuring transaction fee handling.

Additional Notes

There are a few additional details you should understand about how ChartMogul integrates with PayPal:

  • There is a lag of approximately three hours for importing data from PayPal into ChartMogul due to limitations with the PayPal API.
  • PayPal’s API returns transactions for the previous three years, which means ChatMogul can only import your most recent three years of data. Keep this in mind if you choose to re-import data for your PayPal data source in the future.
  • We don’t recommend clicking Import Data or performing a re-import between 00:00 and 05:00 UTC. During this time, we’ve found PayPal doesn’t always make all transactions available, resulting in missing data in ChartMogul.
  • ChartMogul tracks refunds for PayPal. However, PayPal doesn't provide the date of the refund. As such, we use the date of the transaction as the refund date.
  • ChartMogul does not support partial refunds.
  • ChartMogul does not support trials.
  • ChartMogul currently supports IPN transaction types with the recurring_* and subscr_* prefixes. Read more about IPN transaction types.
  • Taxes billed through PayPal do not follow ChartMogul's default tax handling behavior. As such, ChartMogul doesn’t break out taxes into separate line items. Instead, they’re included in the following recurring revenue metrics: MRR, ARR, MRR movements, Average revenue per account, and Average sale price. Likewise, ChartMogul doesn’t exclude taxes from your Cash flow metrics, such as Net cash flow and Non-recurring revenue. Learn more about tax handling in ChartMogul.
  • PayPal allows billing plans to have multiple payment definitions. ChartMogul imports each payment definition as a separate plan.
  • ChartMogul imports failed transactions, but these transactions don’t generate MRR for the customer.
Was this article helpful?