> ## 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 Stripe

This guide outlines the necessary steps to connect your Pagos and Stripe accounts. There are two ways to connect:

* [**OAuth**](#oauth-method-recommended) (recommended)
* [**API Key**](#api-key-method)

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.

<Warning>
  **Sensitive Data Warning**:

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

## OAuth Method (Recommended)

Stripe OAuth is the easiest and recommended way to connect your Stripe and Pagos accounts. This method uses Stripe's secure authorization flow, so you don't need to create or manage API keys manually.

<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 **Processor** drop-down menu, then click **Stripe**.

    <img src="https://mintcdn.com/pagossolutionsinc/MRgvayZXvnT3UGnq/images/connect-stripe/StripeOAuth1.png?fit=max&auto=format&n=MRgvayZXvnT3UGnq&q=85&s=9abc74279b6052239ddd09e318aaa4d1" alt="Stripe-Pagos Authorization" style={{height: "350px"}} className="rounded-lg" width="1090" height="974" data-path="images/connect-stripe/StripeOAuth1.png" />
  </Step>

  <Step title="Name your data connection">
    Enter a **Data Connection Name** of your choice; this value is used for display and identification on data visualizations within Pagos Insights.
  </Step>

  <Step title="Connect with Stripe.">
    Click the **Stripe OAuth** box, then click **Connect with Stripe** in the bottom-left corner of the side panel. You'll be redirected to Stripe's authorization page.
  </Step>

  <Step title="Authorize Pagos in Stripe.">
    Log into your Stripe account (if you're not already logged in) and authorize Pagos to access your account. Once authorized, you'll be redirected back to Pagos and the connection will be complete.

    <img src="https://mintcdn.com/pagossolutionsinc/MRgvayZXvnT3UGnq/images/connect-stripe/StripeOAuth2.png?fit=max&auto=format&n=MRgvayZXvnT3UGnq&q=85&s=eed7ec391ae3b2d99115a59e26af5c8a" alt="Stripe-Pagos Authorization" style={{height: "650px"}} className="rounded-lg" width="786" height="1834" data-path="images/connect-stripe/StripeOAuth2.png" />
  </Step>
</Steps>

## API Key Method

You can also connect your Stripe and Pagos accounts using a restricted API key. This method requires you to manually create an API key in the Stripe dashboard and enter it in Pagos.

### Step 1 – Create a Restricted API Key in Your Stripe Account

For added data security, use a restricted API key to connect your Stripe and Pagos accounts. If you don't already have one, you'll need to create one in the Stripe dashboard:

<Steps>
  <Step title="Navigate to the API Keys page">
    Log into your Stripe account, click **Developers**, then click **API keys** to [locate your API keys in the Dashboard](https://support.stripe.com/questions/locate-api-keys-in-the-dashboard).

    <img src="https://mintcdn.com/pagossolutionsinc/0wBAoiHt18m4tiLa/images/connect-stripe/Stripe1.png?fit=max&auto=format&n=0wBAoiHt18m4tiLa&q=85&s=485c059e011a027135e38c6abb3f098c" alt="" width="3524" height="1706" data-path="images/connect-stripe/Stripe1.png" />
  </Step>

  <Step title="Create a restricted key">
    In the **Restricted keys** section of the API keys page, click **Create restricted key**.

    <img src="https://mintcdn.com/pagossolutionsinc/0wBAoiHt18m4tiLa/images/connect-stripe/Stripe2.png?fit=max&auto=format&n=0wBAoiHt18m4tiLa&q=85&s=c28981f58f0484ce6368324d16922f1c" alt="" width="3564" height="1746" data-path="images/connect-stripe/Stripe2.png" />
  </Step>

  <Step title="Select your integration type">
    Click **Powering an integration you built**, then click **Continue**.

    <img src="https://mintcdn.com/pagossolutionsinc/0wBAoiHt18m4tiLa/images/connect-stripe/Stripe3.png?fit=max&auto=format&n=0wBAoiHt18m4tiLa&q=85&s=bc81ab046ea3d9a2139fa8e2ac499bfb" alt="" width="3564" height="1746" data-path="images/connect-stripe/Stripe3.png" />
  </Step>

  <Step title="Choose a permission template">
    Click **Choose your own**.

    <img src="https://mintcdn.com/pagossolutionsinc/0wBAoiHt18m4tiLa/images/connect-stripe/Stripe4.png?fit=max&auto=format&n=0wBAoiHt18m4tiLa&q=85&s=9d01b7c17fd1f62ca90363ced58e3f42" alt="" width="3560" height="1742" data-path="images/connect-stripe/Stripe4.png" />
  </Step>

  <Step title="Name your API key">
    Use the **Key name** field to name your API key.
  </Step>

  <Step title="Set read permissions">
    Change the permissions for the following resources to **Read**:

    * Balance
    * Balance Transaction Sources
    * Balance Transfers
    * Charges and Refunds
    * Events
    * Files
    * Payment Disputes
    * Payment Intents
    * Payment Methods
    * Payouts
    * Products
    * Setup Intents
    * Sources
    * Tokens
    * Credit notes
    * Subscriptions
    * Terminal SKUs
    * Financial Reports
  </Step>

  <Step title="Set webhook permissions">
    Change the permissions for **Webhook Endpoints, Event Destinations** to **Write**, then click **Create key**.
  </Step>

  <Step title="Copy your key details.">
    After you create the new restricted key, copy the following details for use in the next step:

    * **Name**
    * **Token**
  </Step>
</Steps>

### Step 2: Add a New Data Connection to Your Pagos Account

To pull in Stripe 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 **Processor** drop-down, then select **Stripe**.
  </Step>

  <Step title="Name your data connection">
    Enter a **Data Connection Name**. This value is used for display and identification on charts, and can be whatever you prefer.
  </Step>

  <Step title="Enter your API key">
    Enter the restricted **API key** from [Step 1](#step-1-create-a-restricted-api-key-in-your-stripe-account) above.
  </Step>

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

## Troubleshooting Tips

* If you have already configured a webhook for your Stripe account to connect to Pagos, you will receive an error and will need to remove the old webhook so a new one can be generated.
* After importing your data from Stripe, confirm all BIN number and bank name data appears as expected in your Pagos account. If any data is missing, contact Stripe support and request they enable details on all webhooks.