Troubleshoot Stripe Affiliate Webhooks

Stripe webhooks deliver the payment events AffiliateBase uses to attribute sales and create commissions. This guide is for AffiliateBase merchants. Use it when Stripe deliveries fail, arrive in the wrong mode, or succeed without creating an attributed conversion.

How webhooks work

Customer pays → Stripe processes → Webhook fires →
AffiliateBase receives → Conversion created

AffiliateBase uses these Stripe events for affiliate attribution:

• payment_intent.succeeded
• invoice.paid / invoice.payment_succeeded
• checkout.session.completed / checkout.session.async_payment_succeeded
• refund.updated / charge.refunded
• charge.dispute.created, charge.dispute.updated, and charge.dispute.closed

Check webhook status

AffiliateBase receives your Stripe events through its Stripe app connection. The endpoint belongs to AffiliateBase, not to your Stripe account, so you won’t see an AffiliateBase endpoint under Developers -> Webhooks, and you can’t view, resend, re-enable, or change its signing secret there.

In AffiliateBase

1. Go to Settings -> General
2. Find the Stripe connection row
3. Check the status

In the Stripe Dashboard

1. Go to the Stripe Dashboard
2. Go to Developers -> Events
3. Find the payment event (for example checkout.session.completed or invoice.paid)
4. Confirm it was created in the mode you expect (test or live)

Common issues and solutions

Issue: Webhook endpoint not found

Symptom: You can’t find an AffiliateBase webhook in Stripe.

Cause: This is expected. AffiliateBase receives events through its Stripe app connection, not through an endpoint in your account.

Solution:

1. Go to AffiliateBase Settings -> General
2. Check the Stripe connection status
3. If it shows Not connected, choose Connect Stripe. If it shows Reconnect required, choose Reconnect Stripe
4. Complete the authorization flow

Issue: Events missing in AffiliateBase

Symptom: A payment appears in Stripe, but AffiliateBase shows no matching sale.

Causes:

• Stripe is not connected, or needs to be reconnected
• A test mode vs live mode mismatch
• A delivery to AffiliateBase failed

Solutions:

1. Check the connection:

   • Go to Settings -> General
   • Reconnect Stripe if the status is not connected or shows Reconnect required

2. Check mode:

   • Test payments on a live-mode connection are not attributed and do not create commissions
   • Live payments on a test-mode connection are not attributed until you reconnect in live mode

3. Contact support with the Stripe event ID from Developers -> Events.

Issue: Webhook signature verification failed

AffiliateBase manages Stripe’s signing secret for you, so there is nothing to configure in your Stripe account. If you suspect events are being rejected, contact support.

Issue: Events received but no conversion created

Symptom: The payment appears in Stripe, but no conversion appears in AffiliateBase.

Causes:

• client_reference_id is missing from checkout
• client_reference_id contains a public ?via link token instead of the generated referral ID
• The referral wasn’t found
• The visitor didn’t sign up or pay before the referral expired
• The affiliate was rejected, disabled, banned, or archived, which stops new sales and renewals
• A test-mode payment on a live-mode connection, which creates no commission

Note: If Enable self-referral fraud detection is on (Setup -> Portal and payout defaults) and the customer is the affiliate (same login email or the affiliate’s own Stripe customer), the sale still appears, but its commission is held for your review.

Solutions:

1. Check the event payload:

   • In Stripe, go to Developers -> Events and open the event
   • Find the client_reference_id field in the payload

2. If client_reference_id is empty:

   • Review your checkout code
   • Make sure it passes the referral to Stripe

3. If client_reference_id starts with ref_ or setup_:

   • Your checkout is sending the public affiliate link token from ?via
   • Stripe needs the generated AffiliateBase referral ID created by the tracking script
   • For Payment Links, remove custom code that copies ?via into Stripe and let the AffiliateBase script update the link
   • For backend-created Checkout Sessions, submit the generated referral_id from the browser to your server, then set Stripe client_reference_id

4. If client_reference_id exists and does not start with ref_ or setup_:

   • Check that the referral exists in AffiliateBase
   • Confirm the visitor signed up or paid before the referral expired

Events AffiliateBase listens for

AffiliateBase receives payment intent, invoice, Checkout Session, refund, and dispute events (the ten event types named in the “How webhooks work” section) from your connected Stripe account. No other event types are used for attribution.

Test webhooks

Test with a real payment

1. Make a test purchase in the same mode as your Stripe connection (a test-mode purchase on a live-mode connection won’t create a commission)
2. Confirm the event in Stripe under Developers -> Events
3. Check AffiliateBase for the conversion

Resend failed webhooks

You can’t resend events to AffiliateBase from your Stripe Dashboard. Contact AffiliateBase support with the affected Stripe event IDs or time window.

Monitoring

Recommended monitoring

1. Check regularly: Confirm the Stripe connection status in Settings -> General
2. Test regularly: Run test conversions weekly

Advanced troubleshooting

View raw events

In the Stripe Dashboard:

1. Go to Developers -> Events
2. Find the event
3. View the full payload
4. Check data.object for details

Check the event payload

Look for these fields in the event:

{
  "data": {
    "object": {
      "client_reference_id": "your-referral-id",
      "customer": "cus_xxxxx",
      "amount_total": 9900
    }
  }
}

The value should be the generated AffiliateBase referral ID for that visitor. If it begins with ref_ or setup_, Stripe received the public affiliate link token instead, and AffiliateBase won’t create an attributed conversion from that webhook.

When to contact support

Contact AffiliateBase support if:

• A payment appears in Stripe but never reaches AffiliateBase
• Conversions aren’t created despite a correct client_reference_id
• Stripe payments repeatedly don’t reach AffiliateBase

Contact Stripe support if:

• Events don’t appear at all in Developers -> Events
• You have API or dashboard issues

Prevention

Best practices

1. Monitor regularly - check the Stripe connection status weekly
2. Keep Stripe connected - reconnect if the status shows Reconnect required
3. Test after changes - run a test conversion after checkout changes

Next steps

• Troubleshooting Common Issues
• Connect Stripe
• Stripe Checkout and Payment Links