# Stripe Integration

Tillage uses Stripe for secure payment processing. This guide covers setup, configuration, and how payments work.

## Overview

Stripe powers all payment processing in Tillage:
- Credit and debit card payments
- ACH bank transfers
- Saved payment methods
- Automatic recurring billing

## Setup Options

### Free Plan: Stripe Express

Quick setup for new businesses:

1. Go to Settings > Payments
2. Click "Connect with Stripe"
3. Complete Stripe's guided onboarding
4. Verify your identity and business
5. Add bank account for payouts

**Takes about 5 minutes.**

### Premium Plan: Connect Existing Account

Link your existing Stripe account:

1. Go to Settings > Payments
2. Click "Connect Existing Account"
3. Log into your Stripe account
4. Authorize Tillage
5. Start accepting payments immediately

**Benefit:** 0% Tillage platform fee (vs 1% on free plan)

## Payment Methods

### Credit and Debit Cards

Accept all major cards:
- Visa
- Mastercard
- American Express
- Discover

**Fees:** 2.9% + $0.30 per transaction

### ACH Bank Transfers

Accept direct bank payments:
- Lower fees than cards
- Best for larger invoices
- 1-3 business days to process

**Fees:** 0.8% capped at $5 per transaction

### Apple Pay & Google Pay

Supported automatically when clients pay on mobile devices.

## Fee Comparison

| Payment Method | Fee | On $5,000 Invoice |
|----------------|-----|-------------------|
| Credit Card | 2.9% + $0.30 | $145.30 |
| ACH | 0.8% (max $5) | $5.00 |

**Note:** On the Free plan, add 1% Tillage fee to above.

## Platform Fees

### Free Plan

- 1% Tillage platform fee
- Plus Stripe processing fees
- Paid from each transaction

### Premium Plan

- 0% Tillage platform fee
- Only Stripe processing fees
- $49/month subscription

## Payouts

### Schedule

- Standard: 2 business days
- Automatic daily payouts
- Funds deposited to your bank

### Viewing Payouts

- In Tillage: Overview in dashboard
- In Stripe: Full details in Stripe Dashboard

## Convenience Fees (Premium)

Pass processing costs to clients:

### Configuration

1. Settings > Payments
2. Enable "Convenience Fees"
3. Set fee type:
   - **Percentage** (e.g., 3%)
   - **Fixed amount** (e.g., $5)
4. Save settings

### How It Works

- Applies to credit card payments only
- ACH payments remain fee-free
- Client sees fee before paying

**Example:**
- Invoice: $1,000
- Convenience fee (3%): $30
- Client pays: $1,030
- You receive: ~$1,000 (after Stripe fees)

### Per-Invoice Override

Set custom fees on specific invoices:
1. Edit invoice
2. Enable "Custom convenience fee"
3. Set rate for this invoice
4. Overrides team default

## Saved Payment Methods

### How Clients Save Methods

1. Client pays an invoice
2. Option to save payment method
3. Stored securely by Stripe
4. Available for future payments

### Security

- Tillage never stores card numbers
- Tokenized by Stripe
- PCI-compliant processing
- Client can delete anytime

## Automatic Payments

### For Recurring Invoices

1. Client saves payment method
2. Client grants auto-pay consent
3. Recurring invoices charge automatically
4. Confirmations sent to both parties

### Consent Levels

- **Never** - Manual payments only
- **Recurring only** - Auto-pay subscriptions
- **All invoices** - Auto-pay everything

### Safety Features

- Maximum amount limit per invoice
- Client controls consent settings
- Can revoke anytime
- Notifications before charging

## Failed Payments

### Automatic Retry

When a payment fails:
1. First retry in 1 day
2. Second retry in 3 days
3. Third retry in 7 days
4. Escalation if still failing

### Notifications

- You're notified of failures
- Client prompted to update payment method
- Invoice status reflects issue

### Common Failure Reasons

- Insufficient funds
- Card expired
- Card declined
- Invalid account number (ACH)

## Refunds

### Processing Refunds

Refunds are handled through Stripe:

1. Log into Stripe Dashboard
2. Find the payment
3. Click "Refund"
4. Choose full or partial refund
5. Confirm

### In Tillage

- Refund status syncs automatically
- Invoice reflects refund
- Payment history updated

## International Payments

### Supported Countries

Stripe available in 40+ countries. Tillage supports payments wherever Stripe operates.

### Currency

- Set your currency in Settings
- Clients pay in your currency
- Cross-border fees may apply

### International Card Fees

Additional 1.5% for:
- Cards issued outside your country
- Currency conversion

## Security

### PCI Compliance

- Stripe is PCI Level 1 certified
- Tillage doesn't store card data
- Secure payment forms by Stripe

### Fraud Protection

- Stripe Radar for fraud detection
- 3D Secure for high-risk transactions
- Machine learning fraud prevention

### Encryption

- All data encrypted in transit
- HTTPS-only connections
- Secure token-based payment links

## Troubleshooting

### "Stripe not connected"

1. Go to Settings > Payments
2. Check connection status
3. Reconnect if needed

### "Payment failed"

- Check failure reason in Stripe Dashboard
- Common: Card declined, expired, insufficient funds
- Contact client to update payment method

### "Payout delayed"

- New accounts may have holds
- Verify identity in Stripe Dashboard
- Contact Stripe support if needed

## Best Practices

1. **Enable ACH** - Lower fees, better for large invoices
2. **Use convenience fees** - Cover costs on cards
3. **Encourage saved methods** - Faster recurring payments
4. **Monitor failed payments** - Address quickly
5. **Verify payout account** - Ensure funds reach you

---

*Related: [Payments](/llms/features/payments.txt) | [Pricing](/llms/pricing.txt) | [Invoicing](/llms/features/invoicing.txt)*