Connect Stripe

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:

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:

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"}'

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

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

The response includes an authUrl that you open in the browser to start the Stripe OAuth flow.

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.

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.

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

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.

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.

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.

Disconnect Stripe

If you need to disconnect Stripe from a program:

curl -X DELETE https://www.agentref.co/api/v1/programs/PROGRAM_ID/connect-stripe \
  -H "Authorization: Bearer ak_live_YOUR_KEY"

const result = await client.programs.disconnectStripe('PROGRAM_ID');
console.log(result.success); // true

result = client.programs.disconnect_stripe("PROGRAM_ID")
print(result.success)  # True

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.
Multiple Stripe accounts	Each program connects to one Stripe account. Use separate programs for separate Stripe accounts.

Getting Started

Merchant Guide

Agent Integration

Tracking

Integration Guides

Webhooks

For Affiliates

Resources

What happens during connection

Permissions AgentRef receives

Webhook events AgentRef listens to

Disconnect Stripe

Troubleshooting

What’s next

Create Program

Install Tracking

​What happens during connection

​Permissions AgentRef receives

​Webhook events AgentRef listens to

​Disconnect Stripe

​Troubleshooting

​What’s next

Create Program

Install Tracking

What happens during connection

Permissions AgentRef receives

Webhook events AgentRef listens to

Disconnect Stripe

Troubleshooting

What’s next