Integrations

Instead of calling the REST API yourself, you can connect a
payment provider directly. PartnerBee receives the provider's webhook, verifies
the signature, reads the affiliate referral from the event metadata, and records
the conversion for you.

Supported providers

{organizationId} is your PartnerBee organization id. Configure the URL in the
provider's dashboard as a webhook endpoint.

How it works

1. Customer checks out    -> you store the affiliate ref in the provider metadata
2. Provider charges card  -> provider sends a webhook to PartnerBee
3. PartnerBee             -> verifies signature, reads ref, records the conversion

Step 1: carry the referral in metadata

For a webhook to attribute a sale, the affiliate referral must travel with the
payment. Store the referral value (the ba_aff cookie set by the
JavaScript snippet, i.e. the link slug or click
cookie_id) in the provider's metadata at checkout, under the key
ref_bee_affiliate.

For example, on a Stripe Checkout Session:

const session = await stripe.checkout.sessions.create({
  // ... your line items, mode, success_url ...
  metadata: { ref_bee_affiliate: req.cookies.ba_aff },
});

PartnerBee reads that value from the event and resolves the affiliate and
program.

Step 2: point the webhook at PartnerBee

In the provider's dashboard, add the webhook URL for your provider (see the table
above) with your organizationId. Enable the payment or subscription events
(created, paid, refunded).

Delivery and retries

Webhook events are queued and processed asynchronously, so a transient failure
retries instead of dropping the sale. Conversions are idempotent on the
provider's event/order reference, so a redelivered event never double-counts. See
Errors and idempotency.

Verify it works

After configuring the webhook, make a test purchase carrying a known referral,
then confirm the conversion landed:

curl "https://api.partnerbee.app/api/conversions?days=1" \
  -H "Authorization: beeaff-<your-key>"

Recurring subscriptions

For subscriptions, the webhook reports every charge. PartnerBee keeps crediting
the original affiliate on renewals, up to the program's commission window. See
Recurring revenue.