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

# Connect Stripe

> Link your Stripe account to AgentRef so affiliate conversions are tracked automatically from payment events.

AgentRef uses Stripe Connect (OAuth) to listen for payment events on your account. When a customer pays, AgentRef matches the payment to the affiliate who referred them and creates a conversion automatically.

No payment processing access is required. AgentRef only reads payment events.

## What happens during connection

When you click **Connect Stripe** in the dashboard (or call the API), the flow works like this:

```mermaid theme={null}
sequenceDiagram
    participant M as Merchant
    participant A as AgentRef
    participant S as Stripe

    M->>A: Click "Connect Stripe"
    A->>M: Redirect to Stripe OAuth page
    M->>S: Authorize AgentRef
    S->>A: OAuth callback with auth code
    A->>S: Exchange code for access token
    A->>A: Store connection, register webhooks
    A->>M: Redirect back to dashboard (connected)
```

<Steps>
  <Step title="Initiate connection">
    From the dashboard, go to **Program Settings > Stripe** and click **Connect Stripe**. You'll be redirected to Stripe's authorization page.

    Alternatively, use the API to get an OAuth URL:

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://www.agentref.co/api/v1/programs/PROGRAM_ID/connect-stripe \
        -H "Authorization: Bearer ak_live_YOUR_KEY" \
        -H "Content-Type: application/json" \
        -d '{"method": "oauth_url"}'
      ```

      ```javascript Node.js theme={null}
      import { AgentRef } from 'agentref';

      const client = new AgentRef({ apiKey: 'ak_live_YOUR_KEY' });

      const result = await client.programs.connectStripe('PROGRAM_ID', {
        method: 'oauth_url',
      });

      console.log(result.authUrl); // Redirect the merchant to this URL
      ```

      ```python Python theme={null}
      from agentref import AgentRef

      client = AgentRef(api_key="ak_live_YOUR_KEY")

      result = client.programs.connect_stripe("PROGRAM_ID", method="oauth_url")

      print(result.auth_url)  # Redirect the merchant to this URL
      ```
    </CodeGroup>

    The response includes an `authUrl` that you open in the browser to start the Stripe OAuth flow.
  </Step>

  <Step title="Authorize on Stripe">
    On the Stripe authorization page, review the permissions AgentRef is requesting and click **Connect**. If you have multiple Stripe accounts, select the one you want to use for this program.
  </Step>

  <Step title="Automatic webhook setup">
    After authorization, AgentRef automatically registers webhooks on your Stripe account. You do not need to configure anything manually in Stripe's dashboard.
  </Step>
</Steps>

## Permissions AgentRef receives

AgentRef requests **read-only** access to payment events. Here is exactly what it can and cannot do:

| Can do                                 | Cannot do                           |
| -------------------------------------- | ----------------------------------- |
| Listen for payment events via webhooks | Process payments on your behalf     |
| Read checkout session metadata         | Access your bank account or balance |
| Read invoice and subscription data     | Create charges or transfers         |
| Read refund events                     | Modify your Stripe settings         |

<Note>
  AgentRef uses Stripe Connect in **read-only mode**. It never touches your funds or payment processing. You can revoke access at any time from your Stripe dashboard under **Settings > Connected accounts**.
</Note>

## Webhook events AgentRef listens to

Once connected, AgentRef automatically subscribes to these Stripe webhook events:

| Event                           | Purpose                                                         |
| ------------------------------- | --------------------------------------------------------------- |
| `checkout.session.completed`    | Captures one-time purchases and new subscriptions from Checkout |
| `invoice.paid`                  | Tracks recurring subscription payments                          |
| `charge.succeeded`              | Captures direct charges (Payment Intents, legacy charges)       |
| `charge.refunded`               | Reverses commissions when a refund is issued                    |
| `customer.subscription.deleted` | Stops recurring commissions when a subscription is canceled     |

These webhooks are managed by AgentRef. You do not need to create or maintain them in Stripe's webhook settings.

<Warning>
  If you already have a webhook endpoint in Stripe pointing to AgentRef from a previous connection, the reconnect flow will reuse it. AgentRef does not create duplicate endpoints.
</Warning>

## Disconnect Stripe

If you need to disconnect Stripe from a program:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://www.agentref.co/api/v1/programs/PROGRAM_ID/connect-stripe \
    -H "Authorization: Bearer ak_live_YOUR_KEY"
  ```

  ```javascript Node.js theme={null}
  const result = await client.programs.disconnectStripe('PROGRAM_ID');
  console.log(result.success); // true
  ```

  ```python Python theme={null}
  result = client.programs.disconnect_stripe("PROGRAM_ID")
  print(result.success)  # True
  ```
</CodeGroup>

Disconnecting removes the webhook registration and stops conversion tracking for that program. Existing conversions and commissions are not affected.

## Troubleshooting

| Problem                       | Solution                                                                                                                            |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| OAuth flow fails or times out | Check that third-party cookies are enabled in your browser. Some ad blockers interfere with the OAuth redirect.                     |
| Webhooks not firing           | Verify the connection is active in **Program Settings > Stripe**. If needed, disconnect and reconnect.                              |
| Conversions not appearing     | Check that your tracking script passes `agentref_cid` metadata to Stripe. See [Install Tracking](/merchant-guide/install-tracking). |
| Multiple Stripe accounts      | Each program connects to one Stripe account. Use separate programs for separate Stripe accounts.                                    |

## What's next

<CardGroup cols={2}>
  <Card title="Create Program" icon="plus" href="/merchant-guide/create-program">
    Configure your commission rates, cookie duration, and program settings.
  </Card>

  <Card title="Install Tracking" icon="code" href="/merchant-guide/install-tracking">
    Add the tracking script to your website to capture affiliate clicks.
  </Card>
</CardGroup>