Stripe Cards API: Complete Guide to Card Management

Managing Customer Cards

Customer cards enable your business to store payment methods for returning customers, automating billing, and creating seamless checkout experiences.

Creating Cards on Customers

There are two primary methods for adding cards to customer objects. The first uses the Payment Intents API with Setup Intents to securely collect and store card details. The second uses the legacy Sources API for backward compatibility. Modern integrations should prefer the Payment Intents approach with Stripe Elements or Payment Element.

To create a card through a Setup Intent, your frontend collects card details using Stripe Elements, then confirms the Setup Intent to store the card for future use. The Setup Intent handles 3D Secure authentication if required and returns the created payment method attached to the customer. This pattern ensures you never handle raw card data directly, maintaining PCI compliance while providing a secure card storage mechanism for off-session payments and recurring billing.

Retrieving Stored Cards

Cards attached to a customer can be retrieved through the Payment Methods API, which provides comprehensive listing and filtering capabilities. You can retrieve all cards, get a specific card by ID, or list cards with pagination. The list endpoint supports various filters including created date ranges, endingBefore/startingAfter for cursor-based pagination, and limit controls for page size. This enables efficient management interfaces where users can browse and select from their stored cards.

Updating Card Details

While you cannot modify the core card data like number, brand, or expiration date (those require re-issuing), you can update billing details, metadata, and set a card as the default payment method. This flexibility allows you to keep customer information current without requiring them to re-add their entire card. The default payment method setting is particularly important for subscription billing, as Stripe Billing will automatically attempt to charge the default card when invoices are due.

Deleting Cards

When customers want to remove a payment method or you need to clean up unused cards, you detach the payment method from the customer. This removes the association but does not delete the underlying card token from Stripe's systems. Detaching is reversible--you can reattach the same card to the same or different customer if needed. This provides flexibility for account merging, customer support scenarios, and user-requested changes.

Stripe Issuing Cards

Stripe Issuing transforms how businesses manage spending and disbursements. Create virtual and physical cards with programmable spending controls.

Creating Cardholders

Before issuing cards, you must create cardholder objects representing the individuals who will receive cards. Cardholders undergo identity verification as part of Stripe's compliance requirements. Each cardholder can have multiple cards, making it efficient to manage employee or vendor spending programs. The verification process ensures compliance with financial regulations while providing a streamlined experience for card recipients.

Creating Issuing Cards

Issue virtual cards for immediate digital use or physical cards shipped to recipients. Set spending limits, category restrictions, and merchant controls at the card level. Virtual cards are particularly useful for marketplace payouts and gig economy payments where immediate access to funds is essential. Physical cards suit employee expense management programs and corporate spending where traditional point-of-sale transactions are common.

Managing Card Controls

Spending controls provide granular control over how cards can be used. You can set amount limits per transaction, daily, weekly, or monthly, restrict certain merchant categories, and block specific merchants or types of purchases. Cards can be temporarily frozen by setting their status to inactive, providing a quick way to suspend spending when needed. Reactivate cards instantly when circumstances change.

Card Lifecycle

Monitor card status, fetch transactions, and manage the complete lifecycle from creation through expiration or cancellation. Stripe handles expiration automatically based on card settings, but you can also programmatically manage card status. Transaction monitoring enables expense reporting, fraud detection, and compliance verification throughout the card's active period.

Security and PCI Compliance

Stripe's architecture minimizes PCI compliance burden for merchants using their card products.

Handling Card Data Securely

By using Stripe Elements, Payment Element, or mobile SDKs, card data never touches your servers directly. The sensitive information is transmitted to Stripe, tokenized, and returned as a reference that can be safely stored and used. Never log, store in plain text, or transmit raw card numbers through your systems. Even storing the last four digits requires careful consideration of data handling practices. Use Stripe's client-side libraries for all card collection and rely on payment method IDs for subsequent operations.

Radar Fraud Prevention

Stripe Radar integrates with card processing to provide fraud detection and prevention. For customer cards, Radar analyzes transaction patterns and can block high-risk payments automatically. For Issuing cards, Radar monitors authorized transactions for suspicious activity. Custom rules can be created to block cards with excessive fraud counts or unusual spending patterns, providing proactive protection for your payment ecosystem.

3D Secure Authentication

3D Secure adds an authentication layer for card payments, shifting liability for fraud to the card issuer in many cases. Stripe automatically handles 3D Secure when required by the card or issuer, redirecting the cardholder to complete verification. This authentication step is crucial for liability protection and is integrated seamlessly into the payment flow through the Payment Intents API. When 3D Secure is applied, the risk of fraudulent chargebacks significantly decreases, protecting both your business and your customers.

Integration Patterns

Subscription Billing

When combining customer cards with Stripe Billing, subscriptions automatically charge the default payment method on the invoice due date. Failed payments trigger retry logic according to your settings, and customers can update their payment method through the self-service billing portal. This integration eliminates the need to build custom billing infrastructure while maintaining full control over subscription management, pricing, and customer communication.

Marketplace Disbursements

Marketplaces can use Stripe Issuing to pay sellers immediately. Instead of waiting for ACH transfers that take several days, issue virtual cards to sellers who can use them immediately for purchases or transfer funds to their bank accounts. This approach accelerates seller onboarding and provides immediate access to earned funds. The spending limits feature ensures sellers cannot exceed their payout amounts, protecting your platform from overexpenditure.

Expense Management

Build expense management workflows by combining Issuing card controls with transaction monitoring. Fetch transaction data regularly, categorize purchases, and generate expense reports automatically. The transaction object includes merchant data, purchase categories, and receipt information that can feed directly into accounting systems. This integration transforms Issuing from a simple disbursement tool into a comprehensive expense management platform.

Best Practices

Card Storage Optimization

Store only the minimum information needed for your business operations. The payment method ID is sufficient for most operations--avoid storing additional card details in your database. If you need to display card information to users, use the truncated card number and brand rather than storing these values. Consider implementing a card management UI that allows users to add, remove, and update their payment methods without contacting support.

Error Handling and Retries

Card operations can fail for various reasons including insufficient funds, card expired, fraud blocks, and authentication requirements. Implement comprehensive error handling that maps Stripe error codes to user-friendly messages and appropriate retry logic. Key error codes to handle include card_declined, expired_card, and incorrect_cvc. Each requires a distinct user experience--from prompting for a new card to simply asking for updated security information.

Webhook Integration

For reliable card management, implement webhooks to stay synchronized with Stripe. Card objects can change due to expiration updates, fraud prevention actions, or customer-initiated updates. Webhooks ensure your local records stay current.

// Handle card-related webhook events
const handleWebhook = async (event) => {
 switch (event.type) {
 case 'payment_method.attached':
 // New card added to customer
 await syncCardToDatabase(event.data.object);
 break;
 case 'payment_method.detached':
 // Card removed from customer
 await removeCardFromDatabase(event.data.object.id);
 break;
 case 'payment_method.updated':
 // Card details changed
 await updateCardInDatabase(event.data.object);
 break;
 case 'issuing.card.created':
 // New Issuing card created
 await syncIssuingCard(event.data.object);
 break;
 case 'issuing.card.updated':
 // Issuing card status changed
 await updateIssuingCard(event.data.object);
 break;
 }
};```

Sources

1. Stripe API Reference - Cards
2. Stripe Card Issuing APIs 101