How to connect 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. Download PayPal Profile IDs
  5. Uploading your historical data to ChartMogul

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

Before you begin

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.

1. Create an app in PayPal

First, create a new app for ChartMogul in PayPal:

  1. Log in to 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

Keep the Client ID and Secret (we display 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
    Screenshot of the PayPal Data Source setup window with the Client ID and Secret fields
  6. Click Save

Note the WebHook URL — you’ll need to enable Instant Payment Notifications.

Screenshot highlighting the Webhook URL as we describe

3. Enable Instant Payment Notifications in PayPal

Next, enable Instant Payment Notifications (IPN) in PayPal:

  1. Log in to 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 PayPal Profile IDs

Importing your historical data from PayPal into ChartMogul involves a few steps:

  1. First, you’ll locate and download Profile IDs for your subscriptions. PayPal sometimes refers to 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. Next, you’ll upload the IDs as a CSV into ChartMogul.
  3. ChartMogul will then download subscription data for each ID from PayPal.

Once this process is complete, you’ll be ready to fully use ChartMogul.

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 Last 1 year, 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–7, setting Filter profiles by to Inactive profiles

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 have decided to store Subscription IDs in your database. If this is the case, we suggest working with your developer to access and download the IDs to a CSV file.

5. Upload Historical Data

Upload the CSV file(s) you created in the previous step:

  1. Return to the PayPal Data Source configuration window in ChartMogul
  2. In the Import historic data from PayPal section, click Choose File, select the CSV file for active profiles, then click Upload List
    Screenshot showing a portion of the PayPal Data Source configuration window with the Upload CSV file section highlighted
  3. ChartMogul will then display the Profile IDs from your CSV file in a table. Check the table to confirm it contains the list of IDs you’re expecting to import. If it looks correct, click Import Data
    Screenshot of a table with example PayPal Billing Agreement IDs that were uploaded by CSV
  4. Repeat steps 2–4 for inactive profiles

After you click Import Data, ChartMogul retrieves subscription data from PayPal for each Profile ID you uploaded. Once complete, you’ll see your PayPal data in ChartMogul. If you enabled instant payment notifications, PayPal will send new Profile IDs to ChartMogul so it stays up-to-date.

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 uploading historical data (as we outline above) to ChartMogul or performing a re-import between 00:00 and 05:00 UTC. During this time, we’ve found PayPal doesn’t 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. 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?