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

# Connect Stripe, Paystack, or Other Payment Providers

> Route payment and subscription webhook events from Stripe, Paystack, Flutterwave, Paddle, or LemonSqueezy to Refairn for automatic commission triggering.

Connecting your payment provider is the fastest path to fully automated commission triggering. Instead of adding event calls to your backend code, you configure your payment provider to forward transaction events directly to Refairn. When a payment succeeds, a subscription renews, or a charge is refunded, your provider notifies Refairn in real time—and Refairn matches the payment to the right agent and queues the commission automatically.

This method requires no code changes to your SaaS application. All configuration happens in your payment provider's dashboard.

<Note>
  Payment provider webhooks handle payment events. They do not capture customer signups. To attribute customers at the moment they register—before they pay—add the `customer-created` API call to your signup flow as well. See [API Integration](/integrations/api-integration) for details.
</Note>

## How it works

1. You add Refairn's webhook URL as an endpoint in your payment provider dashboard.
2. You select the events Refairn needs to receive.
3. Your payment provider sends those events to Refairn whenever they occur.
4. Refairn verifies the event signature, looks up the customer's agent attribution by email, and triggers commission logic.

Your Refairn webhook URL follows this format:

```text theme={null}
https://app.refairn.com/webhooks/{provider}/{businessId}
```

Replace `{provider}` with your payment provider's name (lowercase) and `{businessId}` with your Refairn business ID, found in **Settings → Integrations** in your dashboard.

***

## Provider setup

<Tabs>
  <Tab title="Stripe">
    Stripe is the most common payment provider for SaaS businesses. Refairn supports the full Stripe webhook event set for subscription lifecycle management.

    **Your webhook URL:**

    ```text theme={null}
    https://app.refairn.com/webhooks/stripe/YOUR_BUSINESS_ID
    ```

    **Events to enable:**

    | Event                           | What it triggers in Refairn                                         |
    | ------------------------------- | ------------------------------------------------------------------- |
    | `checkout.session.completed`    | Customer subscribed — triggers initial commission                   |
    | `invoice.payment_succeeded`     | Subscription renewed — triggers recurring commission                |
    | `customer.subscription.deleted` | Subscription cancelled — stops future recurring commission          |
    | `charge.refunded`               | Payment refunded — voids or reduces the associated commission       |
    | `charge.dispute.created`        | Dispute opened — holds the associated commission pending resolution |

    **Setup steps:**

    <Steps>
      <Step title="Open your Stripe Dashboard">
        Log in to [dashboard.stripe.com](https://dashboard.stripe.com) and navigate to **Developers → Webhooks**.
      </Step>

      <Step title="Add an endpoint">
        Click **Add endpoint**. Paste your Refairn webhook URL:

        ```text theme={null}
        https://app.refairn.com/webhooks/stripe/YOUR_BUSINESS_ID
        ```
      </Step>

      <Step title="Select events">
        Under **Events to send**, add the following events:

        * `checkout.session.completed`
        * `invoice.payment_succeeded`
        * `customer.subscription.deleted`
        * `charge.refunded`
        * `charge.dispute.created`
      </Step>

      <Step title="Save and verify">
        Click **Add endpoint**. Stripe will show a signing secret—Refairn uses this automatically to verify that events are genuinely from Stripe. You do not need to configure this secret in Refairn.
      </Step>

      <Step title="Send a test event">
        Use Stripe's **Send test webhook** button to fire a `checkout.session.completed` event. Check your Refairn dashboard under **Customers** to confirm the event was received and processed.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Paystack">
    Paystack is widely used for SaaS products serving customers in Nigeria and across Africa. Refairn supports Paystack's charge and subscription event webhooks.

    **Your webhook URL:**

    ```text theme={null}
    https://app.refairn.com/webhooks/paystack/YOUR_BUSINESS_ID
    ```

    **Events to enable:**

    | Event                    | What it triggers in Refairn                                |
    | ------------------------ | ---------------------------------------------------------- |
    | `charge.success`         | Payment confirmed — triggers commission calculation        |
    | `subscription.create`    | New subscription created — records subscription start      |
    | `subscription.disable`   | Subscription cancelled — stops future recurring commission |
    | `invoice.payment_failed` | Renewal payment failed — no commission generated           |

    **Setup steps:**

    <Steps>
      <Step title="Open your Paystack Dashboard">
        Log in to your Paystack dashboard and navigate to **Settings → API Keys & Webhooks**.
      </Step>

      <Step title="Add the webhook URL">
        In the **Webhook URL** field, paste your Refairn webhook URL:

        ```text theme={null}
        https://app.refairn.com/webhooks/paystack/YOUR_BUSINESS_ID
        ```

        Paystack sends all events to a single endpoint—there is no per-event selection. Refairn filters for the events it needs.
      </Step>

      <Step title="Save and test">
        Save your settings. Use the **Test Webhook** option in the Paystack dashboard to send a sample `charge.success` event. Verify it appears in your Refairn **Customers** tab.
      </Step>
    </Steps>

    <Note>
      Paystack sends all event types to a single webhook URL. Refairn processes only the events listed above and silently ignores all others. You do not need to filter events before they reach Refairn.
    </Note>
  </Tab>

  <Tab title="Flutterwave">
    Flutterwave supports SaaS businesses serving customers across multiple African markets. Refairn accepts Flutterwave's transaction and subscription webhook events.

    **Your webhook URL:**

    ```text theme={null}
    https://app.refairn.com/webhooks/flutterwave/YOUR_BUSINESS_ID
    ```

    **Events to enable:**

    | Event                    | What it triggers in Refairn                                |
    | ------------------------ | ---------------------------------------------------------- |
    | `charge.completed`       | Payment confirmed — triggers commission calculation        |
    | `subscription.activated` | New subscription activated — records subscription start    |
    | `subscription.cancelled` | Subscription cancelled — stops future recurring commission |
    | `transfer.failed`        | Payment failed — no commission generated                   |

    **Setup steps:**

    <Steps>
      <Step title="Open your Flutterwave Dashboard">
        Log in to your Flutterwave dashboard and go to **Settings → Webhooks**.
      </Step>

      <Step title="Add the webhook URL">
        Enter your Refairn webhook URL in the **Webhook URL** field:

        ```text theme={null}
        https://app.refairn.com/webhooks/flutterwave/YOUR_BUSINESS_ID
        ```
      </Step>

      <Step title="Set a secret hash">
        Flutterwave allows you to set a **Secret Hash** value for webhook verification. Set this to any secure random string, then contact Refairn support to configure the same value on the Refairn side for your business.
      </Step>

      <Step title="Save and verify">
        Save your webhook settings and trigger a test transaction to verify the integration is receiving events.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Paddle">
    Paddle operates as a merchant of record, which means it handles tax and compliance on your behalf. Refairn accepts Paddle webhook events for subscription and payment lifecycle tracking.

    **Your webhook URL:**

    ```text theme={null}
    https://app.refairn.com/webhooks/paddle/YOUR_BUSINESS_ID
    ```

    **Events to enable:**

    | Event                    | What it triggers in Refairn                                  |
    | ------------------------ | ------------------------------------------------------------ |
    | `subscription.activated` | New subscription started — triggers initial commission       |
    | `subscription.renewed`   | Subscription renewed — triggers recurring commission         |
    | `subscription.cancelled` | Subscription cancelled — stops future recurring commission   |
    | `transaction.completed`  | One-time payment confirmed — triggers commission calculation |
    | `transaction.refunded`   | Refund issued — voids or reduces the associated commission   |

    **Setup steps:**

    <Steps>
      <Step title="Open your Paddle Dashboard">
        Log in to your Paddle dashboard and navigate to **Developer Tools → Notifications**.
      </Step>

      <Step title="Create a new notification destination">
        Click **New destination**. Select **Webhook** as the notification type. Enter your Refairn webhook URL:

        ```text theme={null}
        https://app.refairn.com/webhooks/paddle/YOUR_BUSINESS_ID
        ```
      </Step>

      <Step title="Select events">
        Add the events listed in the table above. Paddle's notification system lets you select events individually.
      </Step>

      <Step title="Save and test">
        Save the destination. Use Paddle's test notification feature to send a sample `subscription.activated` event and confirm receipt in your Refairn dashboard.
      </Step>
    </Steps>
  </Tab>

  <Tab title="LemonSqueezy">
    LemonSqueezy is a merchant of record platform popular with indie SaaS founders. Refairn supports LemonSqueezy's webhook events for order and subscription tracking.

    **Your webhook URL:**

    ```text theme={null}
    https://app.refairn.com/webhooks/lemonsqueezy/YOUR_BUSINESS_ID
    ```

    **Events to enable:**

    | Event                    | What it triggers in Refairn                                  |
    | ------------------------ | ------------------------------------------------------------ |
    | `order_created`          | New purchase completed — triggers commission calculation     |
    | `subscription_created`   | New subscription created — records subscription start        |
    | `subscription_updated`   | Subscription renewed or changed — updates commission records |
    | `subscription_cancelled` | Subscription cancelled — stops future recurring commission   |
    | `subscription_expired`   | Subscription access ended — confirms cancellation            |

    **Setup steps:**

    <Steps>
      <Step title="Open your LemonSqueezy Dashboard">
        Log in to your LemonSqueezy store and go to **Settings → Webhooks**.
      </Step>

      <Step title="Add a webhook">
        Click **Add webhook**. Enter your Refairn webhook URL:

        ```text theme={null}
        https://app.refairn.com/webhooks/lemonsqueezy/YOUR_BUSINESS_ID
        ```
      </Step>

      <Step title="Select events">
        Enable the events listed in the table above. LemonSqueezy lets you choose which events trigger the webhook.
      </Step>

      <Step title="Set a signing secret">
        LemonSqueezy generates a signing secret for each webhook. Refairn uses this automatically to verify event authenticity. Copy the secret from LemonSqueezy and paste it into the **LemonSqueezy Webhook Secret** field in **Settings → Integrations** in your Refairn dashboard.
      </Step>

      <Step title="Save and verify">
        Save the webhook. LemonSqueezy will send a test ping—check your Refairn dashboard to confirm the endpoint is reachable.
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## What happens after a webhook arrives

When Refairn receives a webhook from your payment provider, it:

1. **Verifies the signature** using the provider's signing mechanism to confirm the event is authentic.
2. **Extracts the customer email** from the event payload.
3. **Looks up the agent attribution** for that email in your Refairn program.
4. **Creates or updates a commission record** based on your program's commission rules.
5. **Applies the hold period** before the commission is eligible for approval and payout.

If no agent attribution exists for a customer email when a payment event arrives, Refairn records the payment in your transaction log but does not create a commission. You can manually assign attribution later from the **Customers** section of your dashboard.

<Note>
  Automated payout disbursement—where Refairn initiates transfers directly to agent bank or mobile money accounts after commissions are approved—is planned for a future release. Today, approved commissions appear in your payout ledger and you initiate disbursements manually from the dashboard.
</Note>