# Stripe Payment Types Reference

Quick reference for all Stripe payment types and their configurations.

---

## Payment Types Catalog

### ONE_TIME_PAYMENT

**ID**: `one_time_payment`

**Description**: Single, non-recurring payments for products or services.

**Use Cases**:
- E-commerce purchases
- One-time donations
- Service fees
- Digital product sales

**Stripe Objects**:
- `PaymentIntent` or `Checkout Session (mode: 'payment')`

**Required Fields**:
```yaml
amount: integer          # Amount in cents
currency: string         # ISO currency code (usd, eur, jpy)
description: string      # Payment description
```

**Documentation**: https://docs.stripe.com/payments/accept-a-payment

---

### SUBSCRIPTION

**ID**: `subscription`

**Description**: Recurring payments at fixed intervals.

**Use Cases**:
- SaaS subscriptions
- Membership sites
- Newsletter subscriptions
- Recurring donations

**Stripe Objects**:
- `Product`, `Price`, `Subscription`
- `Checkout Session (mode: 'subscription')`

**Required Fields**:
```yaml
price_id: string         # Stripe Price ID
interval: enum           # day, week, month, year
interval_count: integer  # Every N intervals
trial_days: integer      # Optional trial period
```

**Billing States**:
| State | Description |
|-------|-------------|
| `trialing` | In free trial period |
| `active` | Paid and active |
| `past_due` | Payment failed, in retry |
| `canceled` | Subscription ended |
| `unpaid` | All retries exhausted |
| `paused` | Temporarily paused |

**Documentation**: https://docs.stripe.com/billing/subscriptions/overview

---

### METERED_BILLING

**ID**: `metered_billing`

**Description**: Usage-based billing calculated at end of period.

**Use Cases**:
- API call billing
- Storage usage
- Compute time
- Message/SMS charges

**Stripe Objects**:
- `Price (usage_type: 'metered')`
- `UsageRecord`

**Required Fields**:
```yaml
price_id: string              # Metered price ID
aggregate_usage: enum         # sum, last_during_period, last_ever, max
billing_scheme: per_unit      # Per unit pricing
```

**Usage Reporting**:
```typescript
await stripe.subscriptionItems.createUsageRecord(
  subscriptionItemId,
  { quantity: 100, timestamp: 'now' }
);
```

**Documentation**: https://docs.stripe.com/billing/subscriptions/usage-based

---

### TIERED_PRICING

**ID**: `tiered_pricing`

**Description**: Volume-based pricing with different rates at quantity thresholds.

**Use Cases**:
- Bulk discounts
- Volume licensing
- Enterprise pricing tiers

**Stripe Objects**:
- `Price (billing_scheme: 'tiered')`

**Tier Modes**:
| Mode | Description |
|------|-------------|
| `volume` | All units at highest tier reached |
| `graduated` | Each tier priced separately |

**Required Fields**:
```yaml
tiers:
  - up_to: 10
    unit_amount: 1000      # $10 per unit
  - up_to: 100
    unit_amount: 800       # $8 per unit
  - up_to: inf
    unit_amount: 500       # $5 per unit
tiers_mode: volume|graduated
```

**Documentation**: https://docs.stripe.com/billing/subscriptions/tiers

---

### MARKETPLACE_PAYMENT

**ID**: `marketplace_payment`

**Description**: Multi-party payments with platform fees (Stripe Connect).

**Use Cases**:
- Multi-vendor marketplaces
- Service platforms (Uber-like)
- Crowdfunding
- Affiliate payments

**Account Types**:
| Type | Control | Onboarding | Dashboard |
|------|---------|------------|-----------|
| `standard` | Low | Full Stripe | Full |
| `express` | Medium | Simplified | Limited |
| `custom` | Full | Your UI | None |

**Required Fields**:
```yaml
account_type: enum                    # standard, express, custom
application_fee_percent: float        # Platform fee %
# OR
application_fee_amount: integer       # Fixed fee in cents
```

**Payment Flow**:
```typescript
// Direct charge with fee
await stripe.paymentIntents.create({
  amount: 10000,
  currency: 'usd',
  application_fee_amount: 1000,  // $10 platform fee
  transfer_data: {
    destination: 'acct_connected_account',
  },
});
```

**Documentation**: https://docs.stripe.com/connect

---

### PAYMENT_LINK

**ID**: `payment_link`

**Description**: No-code shareable payment URLs.

**Use Cases**:
- Quick sales via email/SMS
- Social media selling
- Invoice payments
- Simple checkout without website

**Stripe Objects**:
- `PaymentLink`

**Required Fields**:
```yaml
price_id: string         # Product price
quantity_adjustable: boolean
allow_promotion_codes: boolean
```

**Documentation**: https://docs.stripe.com/payment-links

---

### INVOICE

**ID**: `invoice`

**Description**: Send invoices for payment (B2B, services).

**Use Cases**:
- B2B billing
- Professional services
- Custom quoted work
- Net-30/60/90 terms

**Stripe Objects**:
- `Invoice`, `InvoiceItem`

**Required Fields**:
```yaml
customer_id: string
due_days: integer           # Days until due
collection_method: enum     # charge_automatically, send_invoice
```

**Documentation**: https://docs.stripe.com/invoicing

---

### SAVED_PAYMENT_METHOD

**ID**: `saved_payment_method`

**Description**: Store payment methods for future use.

**Use Cases**:
- One-click checkout
- Subscription updates
- Recurring manual charges

**Stripe Objects**:
- `SetupIntent`, `PaymentMethod`, `Customer`

**Required Fields**:
```yaml
customer_id: string
payment_method_types: array    # ['card', 'us_bank_account']
usage: enum                    # on_session, off_session
```

**Documentation**: https://docs.stripe.com/payments/save-and-reuse

---

### CUSTOMER_PORTAL

**ID**: `customer_portal`

**Description**: Self-service subscription management.

**Use Cases**:
- Subscription upgrades/downgrades
- Payment method updates
- Invoice history
- Cancellation flow

**Stripe Objects**:
- `BillingPortal.Session`, `BillingPortal.Configuration`

**Portal Features**:
- Update payment method
- View invoices
- Cancel subscription
- Change plan

**Documentation**: https://docs.stripe.com/customer-management/portal-deep-dive

---

## Payment Methods Catalog

### Cards

| Method | ID | Regions |
|--------|-----|---------|
| Visa/Mastercard/Amex | `card` | Global |
| Apple Pay | `apple_pay` | Global (iOS/Safari) |
| Google Pay | `google_pay` | Global (Android/Chrome) |
| Link | `link` | US |

### Bank Payments

| Method | ID | Regions |
|--------|-----|---------|
| ACH Direct Debit | `us_bank_account` | US |
| SEPA Direct Debit | `sepa_debit` | EU |
| BACS Direct Debit | `bacs_debit` | UK |
| Pre-authorized Debit | `acss_debit` | Canada |

### Regional Methods

| Method | ID | Regions |
|--------|-----|---------|
| iDEAL | `ideal` | Netherlands |
| Bancontact | `bancontact` | Belgium |
| giropay | `giropay` | Germany |
| Sofort | `sofort` | EU |
| Przelewy24 | `p24` | Poland |
| EPS | `eps` | Austria |
| Boleto | `boleto` | Brazil |
| OXXO | `oxxo` | Mexico |
| Konbini | `konbini` | Japan |
| PayNow | `paynow` | Singapore |
| PromptPay | `promptpay` | Thailand |
| FPX | `fpx` | Malaysia |

### Buy Now, Pay Later

| Method | ID | Regions |
|--------|-----|---------|
| Afterpay/Clearpay | `afterpay_clearpay` | US, UK, AU, NZ, CA |
| Klarna | `klarna` | US, EU, UK |
| Affirm | `affirm` | US, CA |
| Zip | `zip` | US, AU |

### Wallets

| Method | ID | Regions |
|--------|-----|---------|
| Alipay | `alipay` | China |
| WeChat Pay | `wechat_pay` | China |
| GrabPay | `grabpay` | Singapore, Malaysia |
| PayPal | `paypal` | Global |

---

## Webhook Events Reference

### Payment Events

| Event | When | Action |
|-------|------|--------|
| `payment_intent.succeeded` | Payment successful | Fulfill order |
| `payment_intent.payment_failed` | Payment failed | Notify customer |
| `charge.refunded` | Refund processed | Update order status |
| `charge.dispute.created` | Chargeback initiated | Review dispute |

### Checkout Events

| Event | When | Action |
|-------|------|--------|
| `checkout.session.completed` | Checkout finished | Fulfill order |
| `checkout.session.expired` | Session expired | Clean up |
| `checkout.session.async_payment_succeeded` | Async payment success | Fulfill order |
| `checkout.session.async_payment_failed` | Async payment failed | Notify customer |

### Subscription Events

| Event | When | Action |
|-------|------|--------|
| `customer.subscription.created` | New subscription | Provision access |
| `customer.subscription.updated` | Plan changed | Update access level |
| `customer.subscription.deleted` | Subscription ended | Revoke access |
| `customer.subscription.trial_will_end` | Trial ending soon | Send reminder |
| `customer.subscription.paused` | Subscription paused | Pause access |
| `customer.subscription.resumed` | Subscription resumed | Resume access |

### Invoice Events

| Event | When | Action |
|-------|------|--------|
| `invoice.paid` | Invoice paid | Update records |
| `invoice.payment_failed` | Payment failed | Retry/notify |
| `invoice.upcoming` | Invoice coming | Notify customer |
| `invoice.finalized` | Invoice ready | Send to customer |

### Connect Events

| Event | When | Action |
|-------|------|--------|
| `account.updated` | Account changed | Check status |
| `account.application.authorized` | Connect authorized | Enable features |
| `account.application.deauthorized` | Connect removed | Disable features |
| `payout.paid` | Payout sent | Update records |
| `payout.failed` | Payout failed | Investigate |

---

## Quick Decision Tree

```
What payment model do you need?

├─ Single purchase?
│  ├─ Simple checkout → PAYMENT_LINK or ONE_TIME_PAYMENT (Checkout)
│  └─ Custom UI → ONE_TIME_PAYMENT (Payment Intent + Elements)
│
├─ Recurring billing?
│  ├─ Fixed price → SUBSCRIPTION
│  ├─ Usage-based → METERED_BILLING
│  └─ Volume discounts → TIERED_PRICING
│
├─ Multi-party payments?
│  └─ Platform fees → MARKETPLACE_PAYMENT (Connect)
│
├─ B2B invoicing?
│  └─ Custom terms → INVOICE
│
└─ Customer self-service?
   └─ Manage subscriptions → CUSTOMER_PORTAL
```

---

## Version History

- v1.0.0 - Initial payment types catalog