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

# Stripe integration

> Automatically track payments and subscriptions from Stripe

## Overview

Connect Stripe to automatically track payments, subscriptions, and refunds. Commissions are calculated and attributed to partners in real time.

## Features

* **Automatic transaction tracking** - All Stripe payments create transactions
* **Subscription support** - Track recurring payments for ongoing commissions
* **Refund handling** - Commissions are reversed on refunds
* **Customer syncing** - Stripe customers are synced to Partnero

## Setup

### Step 1: Connect Stripe

1. Go to **Program Settings → Integrations**
2. Click **Connect Stripe**
3. Authorize Partnero to access your Stripe account

<Note>
  You'll need admin access to your Stripe account to complete the connection.
</Note>

### Step 2: Configure Webhook

Partnero automatically sets up webhooks, but verify they're working:

1. In Stripe Dashboard, go to **Developers → Webhooks**
2. Verify a webhook exists for `https://api.partnero.com/v1/integrations/stripe/{your_program_id}/webhook`
3. Ensure these events are enabled:
   * `checkout.session.completed`
   * `invoice.paid`
   * `charge.refunded`
   * `customer.subscription.created`
   * `customer.subscription.updated`
   * `customer.subscription.deleted`

### Step 3: Map Products (Optional)

Set specific commission rates for different products:

1. Go to **Program Settings → Commissions**
2. Click **Add Product Rule**
3. Select Stripe products and set commission rates

## How It Works

### Payment Tracking

When a Stripe payment is processed:

```mermaid theme={null}
flowchart LR
    A[Stripe Payment] --> B[Webhook Sent]
    B --> C[Partnero Receives]
    C --> D[Customer Matched]
    D --> E[Partner Attributed]
    E --> F[Commission Created]
```

### Customer Attribution

Customers are attributed to partners via:

1. **Referral Cookie** - Customer clicked a partner's referral link
2. **Coupon Code** - Customer used a partner's coupon at checkout
3. **Metadata** - `partner_key` passed in Stripe metadata

### Passing Partner Attribution

Include partner information in Stripe Checkout:

```javascript theme={null}
const session = await stripe.checkout.sessions.create({
  line_items: [{ price: 'price_xxx', quantity: 1 }],
  mode: 'subscription',
  success_url: 'https://yoursite.com/success',
  cancel_url: 'https://yoursite.com/cancel',
  metadata: {
    partnero_partner: 'PARTNER_CODE' // Pass the partner code
  }
});
```

Or using client-side referral data:

```javascript theme={null}
// Get referral info from Partnero
const referralInfo = po('getReferralInfo');

// Include in checkout
const session = await stripe.checkout.sessions.create({
  // ... other options
  metadata: {
    partnero_partner: referralInfo.partner_key
  }
});
```

## Subscription Handling

### New Subscriptions

When a subscription is created:

* Transaction created for initial payment
* Commission calculated and attributed
* Recurring flag set for future payments

### Recurring Payments

Each subscription renewal:

* New transaction created automatically
* Commission calculated (if recurring commissions enabled)
* Partner continues earning

### Subscription Changes

* **Upgrades** - Additional commission on increased amount
* **Downgrades** - Commission adjusted accordingly
* **Cancellations** - Future commissions stop

## Refunds & Disputes

### Automatic Refund Handling

When a refund is processed in Stripe:

1. Partnero receives the refund webhook
2. Original transaction is marked as refunded
3. Commission is reversed/cancelled
4. Partner balance is adjusted

### Partial Refunds

For partial refunds, commission is adjusted proportionally:

```
Original: $100 → $20 commission
Refund: $50 (50%)
Adjusted Commission: $10
```

## Stripe Checkout Integration

### Using Stripe Checkout

If you use Stripe Checkout, add tracking before redirect:

```javascript theme={null}
// Track the checkout initiation
po('trackCheckoutStarted', {
  customer_email: customerEmail
});

// Then redirect to Stripe Checkout
window.location.href = checkoutSessionUrl;
```

### Passing Referral Data

Ensure referral data flows to Stripe:

```javascript theme={null}
async function createCheckout() {
  // Get referral info
  const ref = po('getReferralInfo');
  
  // Call your backend
  const response = await fetch('/create-checkout', {
    method: 'POST',
    body: JSON.stringify({
      priceId: 'price_xxx',
      partnerKey: ref?.partner_key,
      couponCode: ref?.coupon_code
    })
  });
  
  // Redirect to checkout
  const { url } = await response.json();
  window.location.href = url;
}
```

## Testing

### Test Mode

Connect your Stripe test mode account to test the integration:

1. Toggle to **Test Mode** in Stripe Dashboard
2. Connect Stripe in test mode from Partnero
3. Use Stripe test cards to simulate payments

### Test Cards

| Card Number        | Scenario           |
| ------------------ | ------------------ |
| `4242424242424242` | Successful payment |
| `4000000000000002` | Declined payment   |
| `4000000000003220` | 3D Secure required |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Transactions not appearing">
    * Verify webhook is configured correctly
    * Check webhook logs in Stripe Dashboard
    * Ensure customer has referral attribution
  </Accordion>

  <Accordion title="Commission not calculated">
    * Verify commission rules are configured
    * Check if partner is active
    * Confirm customer is attributed to partner
  </Accordion>

  <Accordion title="Webhook errors">
    * Check webhook signing secret is correct
    * Verify endpoint URL is accessible
    * Review error logs in Stripe Dashboard
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configure Commissions" icon="percent" href="/guides/rewards/commissions">
    Set up commission structures
  </Card>

  <Card title="Transactions API" icon="code" href="/api-reference/transactions/list">
    API for transaction management
  </Card>
</CardGroup>