> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pagos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect to Braintree

This guide outlines the necessary steps to connect your Pagos and Braintree accounts. For more information on connecting Pagos to other payment processors, see our [Connecting Your Payment Processors to Pagos](/importing-data/connecting-your-payment-processors-to-pagos) guide.

## Step 1 - Create a Limited Access Role in Your Braintree Account

For added security of your data, we recommend that you log into your Braintree admin account and create a brand new limited access API key for use with Pagos:

<Steps>
  <Step>
    Log into your Braintree [production environment](https://www.braintreegateway.com/login) as an Admin and follow the process outlined in Braintree's documentation to [create a new role](https://developer.paypal.com/braintree/articles/control-panel/users-roles/managing-users-roles#creating-and-editing-roles). Name it something specific to its use, like *Pagos Dashboard*.
  </Step>

  <Step>
    Under **Rights Granted** for this new role, enable only the following permissions:

    * **Transactions**
      * Download Transactions with Masked Payment Data
    * **Reporting**
      * Create, Run, and Download Reports
      * View Dashboard Graphs
    * **Recurring Billing**
      * Download Subscription Records
      * View Modifications
      * View Subscription Plans
      * View Subscriptions
      * Search Subscriptions
    * **Dispute Management**
      * View, manage and contest disputes
    * **Webhooks**
      * Manage Webhooks (Add/Edit/Delete)
    * **Statements**
      * View Statements
    * **Read-Only Access**
      * View Merchant Accounts
      * View Payment Methods
      * View Transactions
      * View Verifications
      * Download Files
    * **Search**
      * Search Transactions
      * Search Verifications
  </Step>

  <Step>
    Click **Create Role**.
  </Step>
</Steps>

## Step 2 - Create an API User in Your Braintree Account

After you create a limited access role, create an API user in your Braintree dashboard:

<Steps>
  <Step>
    Follow the process outlined in Braintree's documentation to [create a new user](https://developer.paypal.com/braintree/articles/control-panel/users-roles/managing-users-roles#creating-users) with a shared alias or distribution group email that your team controls.

    <Warning>
      Using a shared alias or distribution group email ensures multiple people can access the credentials if needed. We highly recommend not creating an API user with an individual's email address.
    </Warning>
  </Step>

  <Step>
    Under **API Access**, click the checkbox beside **API Access**.
  </Step>

  <Step>
    Under **Roles**, click the checkbox beside your new limited access role.
  </Step>

  <Step>
    Under **Merchant Accounts** click the checkbox beside all of the merchant accounts for which you want data to flow to Pagos.
  </Step>

  <Step>
    Click **Create User**.
  </Step>

  <Step>
    <Warning>
      Do not skip this step!
    </Warning>

    Log out of your admin account, then log back in as your read-only user account.
  </Step>

  <Step>
    Locate and save the following values for future use:

    * [Merchant ID](https://developer.paypal.com/braintree/articles/control-panel/important-gateway-credentials#merchant-id)

    * [Public key](https://developer.paypal.com/braintree/articles/control-panel/important-gateway-credentials#public-key)

    * [Private key](https://developer.paypal.com/braintree/articles/control-panel/important-gateway-credentials#private-key)
  </Step>
</Steps>

## Step 3 - Add a New Data Connection to Your Pagos Account

To pull in Braintree data to Pagos, you'll need to add a new data connection in your Pagos account:

<Steps>
  <Step>
    [Log into your Pagos account](https://secure.pagos.ai/sign-in).
  </Step>

  <Step>
    Click the **settings** icon in the top-right corner of the page.
  </Step>

  <Step>
    Under **Data Connections**, click **Connections**.
  </Step>

  <Step>
    Click **Add Data Connection**.
  </Step>

  <Step>
    In the side panel that opens, click the **Provider** drop-down, then select **Braintree**.
  </Step>

  <Step>
    Fill in the following fields using the saved values from [Step 2](#step-2-create-an-api-user-in-your-braintree-account):

    * **Data Connection Name** - This value is used for display and identification on charts, and can be whatever you prefer
    * **Merchant ID**
    * **Public Key**
    * **Private Key**
  </Step>

  <Step>
    Click **Add Data Connection** icon.
  </Step>
</Steps>

## Step 4 - Create a Webhook

<Warning>
  **Sensitive Data Warning**:

  Never include sensitive customer data in the metadata fields passed to Pagos via webhook.
</Warning>

After you enter your Braintree details in the **Data Connections** page and click **Add Data Connection**, you'll be prompted to create a webhook:

<Steps>
  <Step>
    Click the **copy** icon beside **Webhook Destination**, then click **Complete Webhook Set-Up**.
  </Step>

  <Step>
    Log into your Braintree limited access user account and follow the process outlined in Braintree's documentation to [create a webhook](https://developer.paypal.com/braintree/articles/control-panel/webhooks).
  </Step>

  <Step>
    On the **New Webhook** screen, paste the destination URL you copied from your Pagos account into the **Destination URL** field.
  </Step>

  <Step>
    Under **Notifications** on that same screen, click the checkbox beside each notification event option.
  </Step>
</Steps>

## Step 5 (Optional) - Create a User for Sending Fee Data to Pagos

To send your Braintree fee data to Pagos, you’ll need to create another Braintree role and user specifically for this purpose:

<Steps>
  <Step>
    Follow the instructions under [Step 1](#step-1-create-a-limited-access-role-in-your-braintree-account) to create a second role.
  </Step>

  <Step>
    Under **Rights Granted** for this new role, enable only the following permissions:

    * **Statements**
      * View Statements
    * **Read-Only Access**
      * Download Files
    * **Reporting**
      * Create, Run, and Download Reports
  </Step>

  <Step>
    Name the role something specific to its use, like *Fee Data*, and save it.
  </Step>

  <Step>
    [Create a new user](https://developer.paypal.com/braintree/articles/control-panel/users-roles/managing-users-roles#creating-users) that you can share with Pagos.
  </Step>

  <Step>
    Under **Roles**, click the checkbox beside your Fee Data role, and under **Merchant Accounts** click the checkbox beside all of the merchant accounts for which you want data to flow to Pagos.
  </Step>

  <Step>
    Work with your Pagos account manager to give us access to this new user.
  </Step>
</Steps>

## Step 6 - Allowlist the Pagos IPs (If Necessary)

If you have network restrictions in place on your Braintree account, you’ll need to allowlist the Pagos IP addresses so we can receive your payments data without interruption. Following the instructions in [Braintree’s documentation](https://developer.paypal.com/braintree/articles/risk-and-security/allowlisting), allowlist the following IP addresses:

* 3.224.240.39

* 52.3.60.58

* 54.210.17.78

* 52.55.42.147