Stripe Integration Guide

    Learn how we integrate with Stripe and how its implemented across Partner.io and the Partner Portal.

    Table of Contents

    🎯 Overview

    • Overview - Understanding the main purposes of the Stripe integration

    💰 Lead Attribution

    💸 Partner Payouts

    💱 Currency Handling

    🔧 Troubleshooting

    Overview

    Partner.io uses Stripe for two main purposes:

    1. Lead Attribution (Integration) - Integration with your Stripe account to track payments and attribute revenue to the correct partners
    2. Partner Payouts - Using Partner.io's Stripe infrastructure to facilitate commission payments to your partners

    It's important to note that these are two separate systems. Lead attribution uses your Stripe integration, while partner payouts use Partner.io's own Stripe account as a payment facilitator. This guide will walk you through how both systems work, common issues you might encounter, and how to resolve them.

    Lead Attribution

    How It Works

    When a payment comes through your Stripe account, Partner.io uses a two-step process to attribute it to the correct lead and partner:

    Primary Attribution Method: Stripe Customer ID

    1. Payment from your Stripe account arrives with a Customer ID (e.g., cus_ABC123xyz)
    2. Partner.io searches for a lead where customer_id = 'cus_ABC123xyz'
    3. If found: Payment is attributed ✅
    4. If not found: Falls back to email matching

    Fallback Attribution Method: Email Matching

    1. Partner.io attempts to match using the customer_email from your Stripe invoice
    2. Searches for a lead with a matching email address
    3. If found:
      • Payment is attributed to the lead
      • Stripe Customer ID is saved to the lead for future payments
    4. If not found: Automatic attribution fails ❌

    Manual Attribution

    If both methods fail, you can manually assign the Stripe Customer ID to the lead record in Partner.io. This will ensure future payments are automatically attributed.

    Manual Customer ID Assignment Process

    1. Find the lead in Partner.io that should receive attribution
    2. Locate the Stripe Customer ID from your Stripe account
    3. Update the lead record with the Customer ID in Partner.io
    4. Future payments will be automatically attributed

    Partner Payouts

    Setup Requirements

    For Partners

    1. Stripe Connected Account: Partners complete Stripe onboarding to create a connected account under Partner.io's Stripe infrastructure for receiving payouts.
    2. Bank details: For manual off-platform payments Partners can add their bank details which will appear on the invoice.

    For Companies

    Add a payment card in Partner.io for processing stripe commission payments. Navigate to Settings > Payment Settings to configure your payment method.

    ⚠️ IMPORTANT: Your payment card is stored as a customer in Partner.io's Stripe account and is only used for commission payments through our platform.

    Payment Process

    1. Commission Calculation: System calculates owed commissions based on attributed revenue
    2. Invoice Generation: Invoices are created automatically based on schedule settings
    3. Payment Options:
      • Stripe Payment: Click "Pay" button to process payment from your stored card to the partner's connected account
      • Mark as Paid: Mark invoice as paid if payment was processed outside of Partner.io

    ⚠️ IMPORTANT: All invoice payments require manual review and approval in Partner.io, either to process the payment or to mark it as paid

    Currency Handling

    • Partner.io Interface: Always displays amounts in your company currency, defaults to USD but can be changed on request.
    • Lead Attribution: Revenue tracking processes payments in the currency of the Stripe invoice, usually the currency in which you invoice customers
    • Partner Payouts: Invoices are generated in the partner's organizational currency, and Stripe payment intents process in that same currency

    Troubleshooting

    Common Attribution Issues

    Stripe Email Mismatch Problem

    Scenario: User signs up with one email but pays with a different email

    Example:

    • John signs up for free trial with john@techstartup.com (creates lead in Partner.io)
    • Company finance team processes payment with billing@techstartup.com
    • Partner.io cannot match payment to original lead

    Why This Happens:

    • Lead record has john@techstartup.com
    • Stripe payment has billing@techstartup.com
    • No Stripe Customer ID on lead record yet
    • Email matching fails

    Solution

    Ensure consistent email usage between signup and payment from customers. If mismatch occurs, manually link Stripe Customer ID to the lead record.

    Payments Not Being Attributed to Lead

    Scenario: Payment comes through your Stripe integration but isn't linked to any lead

    Example:

    • A customer signs up for a free trial through a partner referral (creates lead in Partner.io)
    • When the trial ends, they upgrade to paid through your Stripe checkout
    • Partner.io receives the payment webhook from your Stripe integration
    • Partner.io cannot match the Stripe payment to the existing lead

    Why This Happens:

    • Lead was created with one email but customer paid with different email
    • Stripe Customer ID is not linked to any lead record
    • Customer used different payment details than signup details

    Solution

    • Verify lead exists with correct email in Partner.io
    • Check if Stripe Customer ID is set on the lead record
    • Confirm payment appears in your Stripe account with correct customer email
    • Look for email mismatches between lead record and Stripe customer
    • Manually link Stripe Customer ID to lead record if necessary

    Payout Issues

    Partner Not Receiving Commission

    Verification Steps:

    Step 1: Check Attribution (Integration Issues)

    1. ✅ Confirm payment was attributed to the correct lead in partner.io
    2. ✅ Verify lead is linked to the correct partner
    3. ✅ Check that revenue appears correctly from your Stripe integration

    Step 2: Check Payment Processing (Partner.io's Payout System)

    1. ✅ Ensure partner has connected their Stripe account in the portal settings
    2. ✅ Verify partner has added valid bank account details in the partner portal
    3. ✅ Confirm you have added a payment card in Partner.io's Payment Settings
    4. ✅ Check invoice status and payment history in Partner.io
    5. ✅ Confirm your invoice schedule settings are configured correctly

    Frequently Asked Questions

    Does adding a Stripe Customer ID retroactively add payments to the lead?

    No, it only ensures future payments are attributed correctly.

    Can I bulk update Stripe Customer IDs for multiple leads?

    Currently, Customer IDs must be updated individually per lead record. If you need to update many leads at once, contact support for assistance with bulk operations.

    What happens if a customer refunds or cancels their subscription?

    Partner.io tracks individual payments, not subscription states. Refunds and cancellations in Stripe don't automatically adjust commissions - you'll need to handle these manually in your commission calculations.

    What data does Partner.io receive from Stripe webhooks?

    We receive payment amounts, customer emails, customer IDs, invoice details, and transaction metadata. We don't store or access sensitive payment method information.