Stripe PaymentMethod — Complete Guide to Payment Processing

In this tutorial, you will learn about Stripe PaymentMethod. We cover key concepts, practical examples, and best practices to help you master this topic.

Stripe PaymentMethod API represents all payment methods (cards, wallets, bank debits) with a unified interface for creating, attaching, and charging across different payment types in a single integration.

What You'll Learn

• The unified PaymentMethod object and its types
• Creating and attaching payment methods to customers
• Using PaymentMethod with PaymentIntent and SetupIntent

Why It Matters

Before PaymentMethod API, each payment type (card, bank account, wallet) had a separate object and API. PaymentMethod unifies them into one consistent interface, simplifying integration.

Real-World Use

Durga Antivirus Pro accepts credit cards, SEPA debit, and iDEAL through a single PaymentMethod integration. The checkout shows available options based on customer country, and the same API handles all types.

flowchart LR
    A["PaymentMethod API"] --> B["Card"]
    A --> C["Bank Debit"]
    A --> D["Wallet"]
    A --> E["Buy Now Pay Later"]
    B --> F["Visa, MC, Amex"]
    C --> G["SEPA, ACH"]
    D --> H["Apple Pay, GPay"]
    style A fill:#dbeafe,stroke:#2563eb

Code Examples

import stripe
stripe.api_key = 'sk_test_...'

# Create a card payment method from token (server-side)
payment_method = stripe.PaymentMethod.create(
    type='card',
    card={'token': 'tok_visa'},
)
print(f"PaymentMethod: {payment_method.id}")

# Attach to customer
stripe.PaymentMethod.attach(
    payment_method.id,
    customer='cus_123',
)

# Set as default
stripe.Customer.modify(
    'cus_123',
    invoice_settings={'default_payment_method': payment_method.id},
)

Expected output: Card PaymentMethod created, attached to customer, and set as default for invoices.

// Creating PaymentMethod from frontend elements
const stripe = Stripe('pk_test_...');

async function createPaymentMethod() {
  const { paymentMethod, error } = await stripe.createPaymentMethod({
    type: 'card',
    card: elements.getElement('card'),
    billing_details: {
      name: 'John Doe',
      email: 'john@example.com',
    },
  });

  if (error) {
    console.error('Error:', error.message);
  } else {
    // Send paymentMethod.id to server
    fetch('/api/attach-payment-method', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ paymentMethodId: paymentMethod.id }),
    });
  }
}

Expected output: Frontend creates PaymentMethod and sends the ID to server for attachment to customer.

# Using different payment method types
import stripe
stripe.api_key = 'sk_test_...'

# Create SEPA Debit payment method
sepa_pm = stripe.PaymentMethod.create(
    type='sepa_debit',
    sepa_debit={'iban': 'DE89370400440532013000'},
    billing_details={'email': 'user@example.com'},
)

# Create iDEAL payment method
ideal_pm = stripe.PaymentMethod.create(
    type='ideal',
    ideal={'bank': 'ing'},
)

# Charge with PaymentMethod
payment_intent = stripe.PaymentIntent.create(
    amount=5000,
    currency='eur',
    payment_method=sepa_pm.id,
    confirm=True,
    customer='cus_123',
)

Expected output: Multiple payment method types created and used with a single PaymentIntent flow.

Common Mistakes

1. Using Deprecated Card and Bank Account APIs

The old Card and BankAccount objects are deprecated. Use PaymentMethod API for all new integrations.

2. Not Attaching PaymentMethod to Customer

A PaymentMethod without customer attachment cannot be reused. Always attach after creation.

3. Ignoring PaymentMethod Type-Specific Fields

Different types require different parameters (card token, IBAN for SEPA). Validate required fields per type.

4. Not Setting a Default PaymentMethod

Customers without a default payment method fail on subscription renewal. Set it during onboarding.

5. Forgetting Billing Details

PaymentMethod with billing_details improves success rates and provides information for receipts and disputes.

Practice Questions

1. What problem does the unified PaymentMethod API solve?
2. How do you attach a PaymentMethod to a customer?
3. What is the difference between creating a PaymentMethod client-side vs server-side?
4. Why should you set a default payment method for customers?
5. What happens if you try to charge an unattached PaymentMethod?

Answers:

1. It unifies card, bank, wallet, and other payment types into one consistent API object.
2. Call PaymentMethod.attach() with the payment method ID and customer ID.
3. Client-side uses Stripe.js Elements (PCI-compliant); server-side uses tokens for already-collected data.
4. Subscription invoices and off-session payments use the default method automatically.
5. It works for the one-time charge but cannot be reused without customer attachment.

Challenge: Build a payment method management system that: accepts cards and SEPA debit, attaches to customer, sets default for subscriptions, displays saved methods with last-four and expiry, and handles method removal.

FAQ

Mini Project

Build a checkout page that: displays available payment methods based on customer country, creates PaymentMethod via Stripe Elements, attaches to customer, sets as default, and charges with PaymentIntent. Support cards, SEPA debit, and iDEAL.

What's Next

Explore Stripe PaymentIntent for charging payment methods, or learn about Stripe SetupIntent for saving methods without charging.