9.8 KiB

Raw Blame History

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:

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:

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:

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:

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:

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:

account_type: enum                    # standard, express, custom
application_fee_percent: float        # Platform fee %
# OR
application_fee_amount: integer       # Fixed fee in cents

Payment Flow:

// 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:

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:

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:

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

9.8 KiB Raw Blame History

Stripe Payment Types Reference

Payment Types Catalog

ONE_TIME_PAYMENT

SUBSCRIPTION

METERED_BILLING

TIERED_PRICING

MARKETPLACE_PAYMENT

PAYMENT_LINK

INVOICE

SAVED_PAYMENT_METHOD

CUSTOMER_PORTAL

Payment Methods Catalog

Cards

Bank Payments

Regional Methods

Buy Now, Pay Later

Wallets

Webhook Events Reference

Payment Events

Checkout Events

Subscription Events

Invoice Events

Connect Events

Quick Decision Tree

Version History

9.8 KiB

Raw Blame History