Skip to main content
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:
1

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"}'
The response includes an authUrl that you open in the browser to start the Stripe OAuth flow.
2

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.
3

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 doCannot do
Listen for payment events via webhooksProcess payments on your behalf
Read checkout session metadataAccess your bank account or balance
Read invoice and subscription dataCreate charges or transfers
Read refund eventsModify 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:
EventPurpose
checkout.session.completedCaptures one-time purchases and new subscriptions from Checkout
invoice.paidTracks recurring subscription payments
charge.succeededCaptures direct charges (Payment Intents, legacy charges)
charge.refundedReverses commissions when a refund is issued
customer.subscription.deletedStops 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"
Disconnecting removes the webhook registration and stops conversion tracking for that program. Existing conversions and commissions are not affected.

​
Troubleshooting

ProblemSolution
OAuth flow fails or times outCheck that third-party cookies are enabled in your browser. Some ad blockers interfere with the OAuth redirect.
Webhooks not firingVerify the connection is active in Program Settings > Stripe. If needed, disconnect and reconnect.
Conversions not appearingCheck that your tracking script passes agentref_cid metadata to Stripe. See Install Tracking.
Multiple Stripe accountsEach program connects to one Stripe account. Use separate programs for separate Stripe accounts.

​
What’s next

Create Program

Configure your commission rates, cookie duration, and program settings.

Install Tracking

Add the tracking script to your website to capture affiliate clicks.