---
Title: Stripe
URL Source: https://company-skill.com/p/stripe
Language: en
Last-Modified: 2026-06-14T06:19:05.235826+00:00
Description: Stripe is a comprehensive payments and financial infrastructure platform that enables businesses to accept payments, manage billing, handle disputes, process payouts, and comply with financial regulat
---

# Stripe

> Stripe is a comprehensive payments and financial infrastructure platform that enables businesses to accept payments, manage billing, handle disputes, process payouts, and comply with financial regulations. This skill covers all Stripe domains including payment processing, customer management, billing & subscriptions, financial accounts, issuing, terminal hardware, tax calculation, reporting, security/compliance, and more.

## Featured GEO article

Stripe is a comprehensive payment processing platform that enables developers to configure shipping rates, customize checkout experiences, manage billing portals, handle disputes and refunds, and maintain financial data compliance. By leveraging its synchronous RESTful APIs and dashboard interfaces, businesses can automate transaction lifecycles, enforce brand consistency, and adhere to global regulatory standards.

## Key facts
- Shipping rate `display_name` fields support a maximum of 100 characters.
- The standard tax code for shipping configurations is `txcd_92010001`.
- Shipping rate queries support pagination via `limit`, `starting_after`, and `ending_before` parameters.
- Payment form visual styling via the Appearance API is restricted to Custom Checkout and does not apply to hosted Stripe Checkout.
- Dispute and refund API operations require secret API keys (`sk_`) and reject publishable keys (`pk_`).
- Evidence submission for disputes can be staged using `submit=false` before finalizing.
- The platform supports Visa Compelling Evidence 3.0 through structured `enhanced_evidence` parameters.

## How to Configure Shipping Rates
You can create, list, update, and manage shipping rates by calling the Stripe Shipping Management API endpoints or configuring them through the Delivery Management API.
1. Choose your integration path based on volume and complexity: use the comprehensive Shipping API for full CRUD operations, the dedicated Shipping Rate Management API for paginated listing, or the Delivery Management API to bind standard tax codes.
2. Send a `POST /v1/shipping_rates` request to create a new rate, specifying the `fixed_amount` in the smallest currency unit, a `display_name` under 100 characters, and your preferred `tax_behavior`.
3. Set the `active` status to control visibility and attach `metadata` for internal order tracking.
4. Retrieve or paginate existing rates using `GET /v1/shipping_rates` with `limit`, `starting_after`, or `ending_before` parameters to manage large catalogs efficiently.

## How to Customize Payment Form Appearance
You can align the payment form with your brand by applying the Appearance API for dynamic styling, adjusting the container via CSS, or handling interactive events for loading and focus states.
1. Determine your styling scope: use the Appearance API for real-time visual adjustments, CSS for the outer container, or event listeners for interactive feedback.
2. Implement the Appearance API by calling `changeAppearance` and `loadFonts` to dynamically set properties like `fontFamily`, `colorPrimary`, and `borderRadius` within Custom Checkout.
3. If you only need to adjust layout and borders, apply standard CSS rules to the `container div` containing `.StripeElement`.
4. Attach event listeners for `loaderror` or `ready` states to display spinners or error messages, and use `element.blur()` to programmatically remove focus from fields when validation timing requires it.

## How to Handle Payment Disputes and Refunds
You can manage chargebacks and issue refunds programmatically through the Stripe Disputes and Refunds API or manually via the Stripe Dashboard depending on your transaction volume.
1. Select your workflow: use the API for automated, high-volume processing or the Dashboard for manual review of fewer than five disputes per month.
2. Authenticate all API requests using a secret key (`sk_`), as publishable keys are not permitted for dispute operations.
3. Retrieve dispute details with `Dispute.retrieve`, update evidence using `Dispute.modify`, or concede a case with `Dispute.close`.
4. Stage evidence before final submission by setting `submit=false`, and process Visa Compelling Evidence 3.0 cases by providing structured `enhanced_evidence` parameters.
5. Issue full or partial refunds by calling `Refund.create` against the associated `payment_intent` or `charge` object.

## Frequently Asked Questions

**Q: how do I how to set shipping rates**
A: Create a new rate by sending a `POST /v1/shipping_rates` request and defining the `fixed_amount`, `display_name`, `tax_behavior`, and `active` status.

**Q: what's the best way to configure shipping costs**
A: Use the comprehensive Shipping API for full CRUD control, or route through the Delivery Management API if you need to bind the standard tax code `txcd_92010001` as part of a broader delivery strategy.

**Q: how do I customize payment form**
A: Apply the Appearance API to dynamically adjust colors, fonts, and spacing, or modify the outer `container div` with standard CSS to match your site layout.

**Q: what's the best way to style elements**
A: Use the Appearance API for real-time, code-driven styling, noting that it only functions within Custom Checkout and does not support hosted Stripe Checkout.

**Q: how do I how to manage chargebacks**
A: Automate the process by calling `Dispute.retrieve`, `Dispute.modify`, and `Dispute.close` via the API, or handle them manually through the Stripe Dashboard if your volume is low.

**Q: what's the best way to issue refund**
A: Call `Refund.create` against the target `payment_intent` or `charge` object for programmatic processing, or use the Dashboard interface for occasional manual refunds.

**Q: how do I how to redact personal data**
A: Manage data privacy and redaction workflows by utilizing the financial data compliance and privacy skill, which is designed to handle GDPR and CCPA requirements alongside PSD3 regulations.

**Q: what's the best way to gdpr compliance**
A: Implement the dedicated compliance management workflow to systematically address GDPR/CCPA obligations and PSD3 regulatory standards within your payment infrastructure.

**Q: how do I how to configure customer billing portal**
A: Use the Billing Portal Management API to configure portal sessions and self-service billing configurations for your customers.

**Q: what's the best way to customer portal setup**
A: Deploy the `stripe-billing-portal` API to establish and manage customer portal sessions, enabling subscribers to handle billing and account management independently.

## Key terms
- `fixed_amount` is the shipping cost value specified in the smallest unit of the selected currency.
- `tax_behavior` is a configuration setting that determines whether shipping costs are treated as inclusive, exclusive, or unspecified for tax calculations.
- `enhanced_evidence` is a structured parameter set used to submit documentation for Visa Compelling Evidence 3.0 disputes.
- Custom Checkout is a client-side integration mode that supports dynamic appearance modifications and interactive event handling.
- `sk_` is a secret API key prefix required for authenticating backend operations like dispute management and refund processing.

## Sources
The authoritative source for all configurations, endpoints, and compliance workflows is the official Stripe documentation.

Stripe is available as agent-callable skills via DaaS. Route any question to the best skill with `POST https://company-skill.com/api/route` `{"query": "...", "product": "stripe"}`.

## What you can do

### [Configure rates](https://company-skill.com/p/stripe/stripe-configure-rates.md)

## What You Want to Do

You want to create, list, update, or manage `fixed_amount` shipping rates (`shipping_rates`) in Stripe. This may involve setting `display_name`, `tax_behavior`, `tax_code` (e.g., `txcd_92010001`), `active` status, or `metadata`.

**Typical User Questions**:
- How do I set up shipping rates?
- Can I manage multiple shipping options?
- How do I set different shipping rates for different regions?
- How do I retrieve and update shipping rates?

## Decision Tree

Pick the path that best matches your situation:

- **If** you need to call `POST /v1/shipping_rates` to create new rates with full control over `tax_behavior`, `metadata`, and `active` status → use **Manage via the comprehensive Shipping API** (jump to *stripe/stripe-shipping*)
- **If** you primarily call `GET /v1/shipping_rates` to list rates and rely on `limit`, `starting_after`, or `ending_before` for paginated queries → use **Use the dedicated Shipping Rate Management API** (jump to *stripe/stripe-shipping*)
- **If** you need to bind shipping rates to the standard tax code `txcd_92010001` and manage them as part of an overall delivery strategy → use **Configure through the Delivery Management API** (jump to *stripe/stripe-shipping*)
- **Otherwise (default)** → **Manage via the comprehensive Shipping API**, since it provides full CRUD capability and fits most development scenarios.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|--------------|
| Manage via the comprehensive Shipping API | Developers needing full CRUD operations (create, read, update, delete) on shipping rates. | medium | Yes | Yes | Supports setting `metadata`, `tax_behavior`, and `active` status | `stripe/api/stripe-shipping` |
| Use the dedicated Shipping Rate Management API | Scenarios focused on listing and managing existing shipping rates with relatively simple operations. | low | Yes | Yes | Supports `GET /v1/shipping_rates` pagination parameters: `limit`, `starting_after`, `ending_before` | `stripe/api/stripe-shipping` |
| Configure through the Delivery Management API | Integrations that manage shipping as part of an overall delivery strategy. | medium | Yes | Yes | Supports binding the standard tax code `txcd_92010001` and setting `tax_behavior` | `stripe/api/stripe-shipping` |

## Path Details

### Path 1: Manage via the comprehensive Shipping API

**Best For**: Developers who need full CRUD operations (create, read, update, delete) on shipping rates.

**Brief Description**: Use the synchronous RESTful endpoints of the Stripe Shipping Management API (e.g., `POST /v1/shipping_rates` and `POST /v1/shipping_rates/:id`) to manage `shipping_rates` objects. Supports setting `fixed_amount` (in the smallest currency unit), `display_name` (≤100 characters), `tax_behavior`, `metadata`, and `active` status.

**When to Use**:
- You need full CRUD operations (create, read, update, delete) to manage shipping rates
- You need to set metadata on shipping rates for internal order tracking
- You need precise control over tax behavior (inclusive/exclusive/unspecified) and tax code (txcd_92010001)
- You need to programmatically manage multiple shipping options and integrate them into a CI/CD pipeline

**When NOT to Use**:
- You only need to view or lightly manage existing shipping rates without create/update operations
- You want to manage shipping as part of a broader delivery strategy rather than as standalone shipping rate objects
- You have no backend development capability and cannot call REST APIs

**Known Limitations**:
- Only supports `fixed_amount` shipping calculation; does not support rates based on weight, distance, or other dynamic factors
- Shipping amounts must be integers in the smallest currency unit (e.g., 500 means 5.00 USD)
- `display_name` has a maximum length of 100 characters
- Only supports secret API keys (starting with `sk_test_` or `sk_live_`); publishable keys (`pk_...`) are not supported

### Path 2: Use the dedicated Shipping Rate Management API

**Best For**: Scenarios focused on listing and managing existing shipping rates with relatively simple operations.

**Brief Description**: Focuses on the `GET /v1/shipping_rates` endpoint for retrieving and filtering `shipping_rates`. Supports filtering by `active` status, `currency`, and creation time, and pagination via `limit`, `starting_after`, and `ending_before`.

**When to Use**:
- You primarily list and retrieve existing shipping rates with relatively simple operations
- You need to filter the shipping rates list by `active` status, `currency`, or creation time
- You need paginated retrieval of large numbers of shipping rates (supports `limit`, `starting_after`, `ending_before` parameters)
- You already have shipping rates configured and only need periodic auditing or data export

**When NOT to Use**:
- You need to create new shipping rates or fully reconfigure existing ones
- You want to manage shipping as part of an overall delivery strategy
- You have no backend development capability and cannot call REST APIs

**Known Limitations**:
- Only supports `fixed_amount` shipping calculation; does not support rates based on weight, distance, or other dynamic factors
- Shipping amounts must be integers in the smallest currency unit (e.g., 500 means 5.00 USD)
- `display_name` has a maximum length of 100 characters
- Only supports secret API keys (starting with `sk_test_` or `sk_live_`); publishable keys (`pk_...`) are not supported
- Although you can list and retrieve rates, modifications still require calling the update_shipping_rate endpoint

### Path 3: Configure through the Delivery Management API

**Best For**: Integrations that manage shipping as part of an overall delivery strategy.

**Brief Description**: Use the full Shipping API (including `POST /v1/shipping_rates`) to create `shipping_rates`, with emphasis on tax-system integration. Supports setting `tax_behavior` and the standard tax code `txcd_92010001`, and associating internal delivery rules through `metadata`.

**When to Use**:
- You manage shipping as part of an overall delivery strategy that needs to coordinate with other delivery logic
- You need to set tax behavior (`tax_behavior=exclusive/inclusive`) and the standard tax code (`txcd_92010001`) at rate creation time
- You need to associate shipping rates with an internal delivery-rule system via `metadata`
- You need full control over the shipping rate lifecycle (including activation/deactivation)

**When NOT to Use**:
- You only need to list or view existing shipping rates without full management capabilities
- You have no backend development capability and cannot call REST APIs
- You expect to configure rates directly through the Stripe Dashboard UI without writing code

**Known Limitations**:
- Only supports `fixed_amount` shipping calculation; does not support rates based on weight, distance, or other dynamic factors
- Shipping amounts must be integers in the smallest currency unit (e.g., 500 means 5.00 USD)
- `display_name` has a maximum length of 100 characters
- Only supports secret API keys (starting with `sk_test_` or `sk_live_`); publishable keys (`pk_...`) are not supported
- The documentation does not mention deep integration with delivery strategies (e.g., delivery zones, carrier integrations); only standalone shipping-rate objects are managed

## FAQ

Q: Which path should I start with?
A: If you're unsure, start with **Manage via the comprehensive Shipping API** — it offers the most complete control and fits most development needs.

Q: What if I need dynamic weight-based shipping rates and pick any of these paths?
A: You'll hit a limit: all paths **only support `fixed_amount`** and cannot calculate rates based on weight, distance, or other dynamic factors.

Q: What if I want to call the shipping API from frontend JavaScript?
A: It will fail: all paths **require a secret API key (sk_...)** and cannot use a publishable key (pk_...), so they cannot be called safely from the client.

Q: What happens if my `display_name` exceeds 100 characters?
A: The API request will be rejected — all paths enforce a 100-character maximum on `display_name`.

Q: Can I configure shipping rates through the Stripe Dashboard UI?
A: All current paths require calling the REST API (e.g., `POST /v1/shipping_rates`); **there is no UI configuration option**. If you can't write code, none of these paths fit.

Q: If I only need to display available shipping options to users, do I still need the full API?
A: No. Use **Use the dedicated Shipping Rate Management API** — call `GET /v1/shipping_rates` and filter for `active=true`, avoiding unnecessary write operations.

### [Customize experience](https://company-skill.com/p/stripe/stripe-customize-experience.md)

## What You Want to Do

You want your Stripe payment form to align with your site's brand or user experience — visually or behaviorally. This may include adjusting colors, fonts, layout, loading-state feedback, or focus control.

**Typical User Questions**:
- How do I style Stripe Elements to match my brand?
- Can I handle user interactions like focus/blur on payment fields?

## Decision Tree

Pick the path that best matches your situation:

- **If** you need to dynamically set properties like `fontFamily`, `colorPrimary`, or `borderRadius` via code → use [Use the Appearance API for visual styling] (jump to *stripe/stripe-ui*)
- **If** you only want to control the appearance of the `container div` containing `.StripeElement` via CSS (borders, background, focus states) → use [Customize the payment form container via the guide] (jump to *stripe/stripe-customization*)
- **If** you need to listen to `loaderror` or `ready` events to show a loading spinner or error message → use [Respond to payment element loading and error events] (jump to *stripe/stripe-interactivity*)
- **If** you need to call `element.blur()` for programmatic focus removal or listen to blur events → use [Handle form focus and blur events] (jump to *stripe/stripe-interactions*)
- **Otherwise (default)** → start with [Use the Appearance API for visual styling], since it covers the most common brand-consistency needs and supports dynamic updates.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|--------------|
| Use the Appearance API for visual styling | Brand-consistency needs focused on payment element appearance (colors, fonts, spacing). | low | Yes | Yes | Only works with Custom Checkout; not supported in hosted Stripe Checkout | `stripe/api/stripe-ui` |
| Customize the payment form container via the guide | Frontend developers who need to adjust the payment form's overall layout and container styling. | medium | Yes | Yes | Only the container appearance can be controlled — not the element internals or interaction behavior | `stripe/guide/stripe-customization` |
| Respond to payment element loading and error events | Advanced integrations that need to handle loading errors, ready states, and similar interactive feedback. | medium | Yes | Yes | Only provides ready and loaderror events, not the full set of user interactions | `stripe/api/stripe-interactivity` |
| Handle form focus and blur events | Scenarios needing precise control over user navigation and validation timing within payment fields. | medium | Yes | Yes | Only controls focus state — cannot simulate clicks, input, or other interactions | `stripe/api/stripe-interactions` |

## Path Details

### Path 1: Use the Appearance API for visual styling

**Best For**: Brand-consistency needs focused on payment element appearance (colors, fonts, spacing).

**Brief Description**: Stripe Payment UI Customization is a set of client-side JavaScript APIs for adjusting the visual appearance of payment elements in real time within Custom Checkout. The core methods are `changeAppearance` and `loadFonts`, which configure `appearance` `variables` (such as `colorPrimary`, `fontFamily`, `borderRadius`) to match your brand.

**Key technical facts**:
- Auth: publishable API key embedded in frontend code

**When to Use**:
- You need precise control over payment form colors, fonts, and corner radii via code
- You want to update styles dynamically without remounting elements
- The project already uses Custom Checkout (not hosted Checkout)

**When NOT to Use**:
- You only need basic branding (logo, primary color) and use hosted Checkout
- You have no frontend development resources to implement a JavaScript integration
- You only need container-level CSS styling, not element-internal customization

**Known Limitations**:
- Only works with Custom Checkout; not supported in hosted Stripe Checkout
- Must be implemented in frontend code; cannot be configured via the Dashboard
- Some font changes may require a page reload to apply (if not preloaded correctly)

### Path 2: Customize the payment form container via the guide

**Best For**: Frontend developers who need to adjust the payment form's overall layout and container styling.

**Brief Description**: Stripe Payment Form Customization is a Dashboard-guided workflow that walks developers through styling the `container div` of payment elements via CSS classes (e.g., `.StripeElement--focus`, `.StripeElement--invalid`). You define rules in your own CSS files and ensure they apply after calling `createElement` and `mount`.

**Key technical facts**:
- Prerequisites: Stripe account with API keys, Web application with HTML/CSS/JS integration, Elements library loaded in the page

**When to Use**:
- You only need to adjust the payment form container's overall appearance (borders, background, focus effects)
- You prefer pure CSS without depending on a JavaScript API
- You already have a CSS system and want to integrate Stripe elements with it

**When NOT to Use**:
- You need deep customization of element internals (e.g., styling the card-number field separately)
- The project uses hosted Checkout instead of embedded Elements
- You need to react dynamically to user interactions (ready state, loading errors)

**Known Limitations**:
- Styles must be implemented in your own CSS files; the Stripe Dashboard does not provide a live preview or editor
- Only the container appearance can be controlled — not the element internals or interaction behavior
- Developers must manually handle styles for different states (focused, invalid)

### Path 3: Respond to payment element loading and error events

**Best For**: Advanced integrations that need to handle loading errors, ready states, and similar interactive feedback.

**Brief Description**: Stripe UI Interactivity is a set of client-side JavaScript APIs for listening to payment element lifecycle events. By attaching `callback function`s to element instances, you can access `event.elementType` and `event.error` to control loading spinners or implement user-friendly error handling.

**Key technical facts**:
- Auth: publishable API key embedded in frontend code
- Prerequisites: Stripe.js integration, created Element instance, mounted Element

**When to Use**:
- You need to hide a loading spinner once the payment form has fully loaded
- You want to capture and display user-friendly error messages when an element fails to load
- You're building a robust checkout flow that enables the submit button only after elements are ready

**When NOT to Use**:
- You only need basic form functionality without load-state feedback
- You use hosted Checkout (which does not expose underlying element events)
- The project does not need to handle network or configuration error scenarios

**Known Limitations**:
- Only a limited set of event types is provided (mainly ready and loaderror); not all possible user interactions
- Error messages may not be detailed enough; additional logging may be needed for debugging
- Listeners must be attached immediately after element creation, or events may be missed

### Path 4: Handle form focus and blur events

**Best For**: Scenarios needing precise control over user navigation and validation timing within payment fields.

**Brief Description**: Stripe Payment Form Interactions is a set of client-side JavaScript APIs that let developers programmatically control payment element focus state. The core method is `element.blur()`, paired with a `blur event listener` for focus management — useful for complex user-interface behaviors.

**Key technical facts**:
- Auth: publishable API key embedded in frontend code
- Prerequisites: Stripe.js integration, created and mounted Element instance

**When to Use**:
- You need to programmatically remove focus from the payment element when the user cancels an action
- You want precise focus-management timing in custom validation flows
- You're building complex form-navigation logic (e.g., multi-step checkout)

**When NOT to Use**:
- You only need basic form submission without focus control
- You use hosted Checkout (which does not expose underlying element methods)
- The project does not need to handle focus-related UX details

**Known Limitations**:
- Only focus state can be controlled; other user interactions (clicks, input) cannot be simulated
- `element.blur()` must be called per-element instance; there is no batch operation
- Calling `programmatically blur` on an unmounted element has no effect (though it doesn't error)

## FAQ

Q: Which path should I start with?
A: If your main goal is matching brand colors and fonts, start with [Use the Appearance API for visual styling]; if you only need container styling, choose [Customize the payment form container via the guide].

Q: What if my project uses hosted Stripe Checkout but I pick the Appearance API?
A: It won't work — `changeAppearance` and `loadFonts` only apply to Custom Checkout; hosted Checkout does not support these APIs.

Q: What if I only want to adjust the `.StripeElement` border color but use the interaction-state API?
A: You won't reach your goal — `callback function` and `event.error` handle loading/error states and cannot modify any visual style. Use the CSS rules approach instead.

Q: Can I use both the Appearance API and CSS container customization together?
A: Yes, but the Appearance API takes precedence. Use the Appearance API for internal styling and CSS for outer container layout.

Q: Why does calling `element.blur()` have no effect?
A: The element may not yet be mounted to the DOM container, or you called the method on an unmounted instance — no error, but no `blur event listener` fires either.

Q: My font changes don't appear after the update — what's wrong?
A: If you didn't preload the custom font via `loadFonts`, some browsers may need a page refresh to apply `fontFamily` changes.

Q: What if my project uses hosted Checkout but I pick "Respond to payment element loading and error events"?
A: You won't be able to listen to any events — hosted Checkout does not expose underlying element events. This path only applies to embedded Elements in Custom Checkout.

Q: What if I only need container-level CSS styling but pick the Appearance API?
A: You may have done unnecessary JavaScript integration — the Appearance API is for styling element internals, while container styling can be achieved with pure CSS, no `changeAppearance` needed.

### [Handle refunds](https://company-skill.com/p/stripe/stripe-handle-refunds.md)

## What You Want to Do

You want to respond to customer-initiated payment disputes (chargebacks), submit counter-evidence, or issue full/partial refunds for payments you've collected — and manage the lifecycle of these operations.

**Typical User Questions**:
- How do I handle a customer payment dispute?
- How do I issue a refund?
- How do I submit dispute evidence?
- Can I automate dispute responses?

## Decision Tree

Pick the path that best matches your situation:

- **If** you need to process disputes in bulk, integrate with internal systems, or use APIs like `Dispute.retrieve` / `Dispute.modify` for automation → use [Manage disputes and refunds via the API] (jump to *stripe/stripe-dispute*)
- **If** you have fewer than 5 disputes per month, prefer a graphical interface, or need to manually review each case → use [Handle them manually through the Stripe Dashboard] (jump to *stripe/stripe-dispute*)
- **If** you need to handle Visa Compelling Evidence 3.0 disputes and provide structured `enhanced_evidence` parameters → use [Manage disputes and refunds via the API]
- **Otherwise (default)** → use [Handle them manually through the Stripe Dashboard], since most small merchants have low volume and no need for code

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|--------------|
| Manage disputes and refunds via the API | Automated systems that need to programmatically process disputes, submit evidence, and manage refund lifecycles. | high | Yes | Yes | Must use a secret API key (sk_); publishable keys (pk_) are not allowed | `stripe/api/stripe-dispute` |
| Handle them manually through the Stripe Dashboard | Merchants who handle disputes occasionally, prefer a graphical interface, or need to review each case manually. | low | No | No | Disputes cannot be automated — every case requires manual handling | `stripe/guide/stripe-dispute` |

## Path Details

### Path 1: Manage disputes and refunds via the API

**Best For**: Automated systems that need to programmatically process disputes, submit evidence, and manage refund lifecycles.

**Brief Description**: The Stripe Disputes and Refunds API is a synchronous HTTP service for programmatically retrieving, listing, updating, and closing payment disputes — and creating, canceling, and managing refunds. Core operations include `Dispute.retrieve` to fetch dispute details, `Dispute.modify` to update the `evidence` field, `Dispute.close` to proactively concede a dispute, and `Refund.create` to refund the associated `payment_intent` or `charge`.

**Key technical facts**:
- Auth: Bearer token authentication with secret API keys (sk_)

**When to Use**:
- You need to automate handling of large volumes of disputes
- You need to integrate dispute handling into existing backend systems or CI/CD pipelines
- You need precise control over evidence submission timing (using submit=false to stage evidence)
- You need to handle Issuing Disputes (issuer-side disputes)

**When NOT to Use**:
- The merchant is not familiar with programming or has no development resources
- Disputes are extremely rare and sporadic
- Each dispute requires manual case-by-case review
- You prefer a graphical interface over code

**Known Limitations**:
- Must use a secret API key (sk_); publishable keys (pk_) are not allowed
- Closing a dispute is irreversible and changes status from `needs_response` to `lost`
- When submitting evidence, updating any field of the evidence object submits the entire object for review
- Some advanced dispute types (e.g., Visa Compelling Evidence 3.0) require a specifically structured `enhanced_evidence` parameter

### Path 2: Handle them manually through the Stripe Dashboard

**Best For**: Merchants who handle disputes occasionally, prefer a graphical interface, or need to review each case manually.

**Brief Description**: The Stripe Dashboard provides a graphical interface to manually view, respond to, and manage payment disputes — including uploading evidence and submitting counterarguments. Browse all disputes on the **Dashboard > Disputes** page, click "Respond to disputes" to fill in **Counterargument** and **Evidence**, and click **Submit** to complete the response.

**Key technical facts**:
- Auth: Stripe Dashboard login credentials

**When to Use**:
- Disputes are rare and sporadic
- The merchant prefers a graphical interface
- Each dispute needs manual case-by-case review
- No development resources or programming capability

**When NOT to Use**:
- You need to handle large volumes of disputes
- You need to integrate dispute handling into automated systems
- You need precise control over evidence-submission parameters (e.g., Visa Compelling Evidence 3.0)
- You need programmatic batch operations on disputes

**Known Limitations**:
- Disputes cannot be automated — every case requires manual handling
- Not suitable for high-volume dispute processing
- Cannot precisely control underlying evidence-submission parameters (e.g., enhanced_evidence structure)
- No programmatic integration capability — cannot be embedded into existing business systems

## FAQ

Q: Which path should I start with?
A: If you have fewer than 5 disputes per month and no development team, default to **Handle them manually through the Stripe Dashboard**. Otherwise, prefer the API path.

Q: What if my dispute involves Visa Compelling Evidence 3.0 but I use the Stripe Dashboard?
A: You won't be able to provide the required structured `enhanced_evidence` parameter, which may render the evidence invalid and cause an automatic loss.

Q: What if I need to process hundreds of disputes per day but pick the Dashboard path?
A: You'll be forced to manually click through **Respond to disputes** → **Counterargument** → **Evidence** → **Submit** for every case — slow, error-prone, and impossible to scale.

Q: Can I stage evidence in the API without submitting it immediately?
A: Yes. When calling `Dispute.modify`, set `submit=false` to update `evidence` without submitting — useful for assembling materials in stages.

Q: What's the fundamental difference between refunds and disputes?
A: A refund is when you proactively return funds to the customer; a dispute is when the customer initiates a chargeback through their issuer, and you must respond before the deadline or lose by default.

Q: Can I cancel a refund that was issued but not yet processed via the API?
A: Yes — as long as the refund status is still `pending`, you can cancel via `Refund.cancel`. Once it reaches `succeeded`, it cannot be reversed.

Q: Can the Dashboard show the `payment_intent` or `charge` linked to a dispute?
A: Yes — the dispute detail page on **Dashboard > Disputes** shows the linked payment object, but you can't attach custom data via `metadata` like the API allows.

### [Manage compliance](https://company-skill.com/p/stripe/stripe-manage-compliance.md)

## What You Want to Do

You want to ensure your Stripe integration complies with financial and data privacy regulations such as GDPR, CCPA, and PSD3. This may involve automatically deleting user personal data or manually configuring payment authentication exemption rules.

**Typical User Questions**:
- How do I redact personal data for compliance?
- Can I automate data deletion requests?
- How do I handle PSD3 regulatory requirements?
- How do I configure SCA exemptions?

## Decision Tree

Pick the path that best matches your situation:

- **If** you need to programmatically batch-process GDPR/CCPA data subject deletion requests (e.g., from a script or background system) → use [Manage data redaction jobs via the API](#path-1-manage-data-redaction-jobs-via-the-api) (jump to *stripe/stripe-privacy*)
- **If** your business is in the EEA or UK and needs to configure SCA exemptions (such as TRA-based exemptions or Mark as MOTO) → use [Configure compliance settings through the console](#path-2-configure-compliance-settings-through-the-console) (jump to *stripe/stripe-compliance*)
- **If** you need to set up PSD3 funds segregation and have Stripe Connect enabled → use [Configure compliance settings through the console](#path-2-configure-compliance-settings-through-the-console)
- **Otherwise (default)** → if you're unsure or only need a one-time compliance setup, prefer **Configure compliance settings through the console** since it requires no coding and fits low-frequency operations.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|--------------|
| Manage data redaction jobs via the API | Automated compliance systems that need to programmatically create, validate, and run personal data deletion/redaction jobs. | high | Yes | Yes | Uses the Redaction Job API; you must explicitly call run redaction job to execute | `stripe/api/stripe-privacy` |
| Configure compliance settings through the console | Users who need to manually configure PSD3 compliance options or SCA exemption rules and prefer a graphical interface. | low | No | No | Only applies to EEA/UK businesses; MOTO exemption requires Stripe Support to enable | `stripe/guide/stripe-compliance` |

## Path Details

### Path 1: Manage data redaction jobs via the API

**Best For**: Automated compliance systems that need to programmatically create, validate, and run personal data deletion/redaction jobs.

**Brief Description**: The Stripe Privacy API is a RESTful interface for orchestrating personal-data removal from Stripe objects, supporting create, validate, run, and cancel operations on redaction jobs. Core components include the Redaction Job API (endpoint `https://api.stripe.com/v1/privacy/redaction_jobs`), which lets you control `validation_behavior` (error or fix mode) and handle `validation_errors`.

**Key technical facts**:
- Auth: Bearer Token using secret API key (`sk_test_` or `sk_live_`)

**When to Use**:
- You need to programmatically batch-process GDPR/CCPA data deletion requests
- You have an existing automated compliance system that needs to integrate Stripe data redaction
- You need precise control over the redaction job's validation behavior (error or fix mode)

**When NOT to Use**:
- Users prefer a graphical interface over writing code
- You only need a one-time compliance configuration rather than recurring redaction tasks
- You're not familiar with Stripe API authentication and parameter formats

**Known Limitations**:
- Only supported via API calls; no graphical interface option
- Redaction jobs require an explicit `run redaction job` call to execute; they do not auto-trigger
- On validation failure, you must manually handle `validation_errors` and re-validate before continuing
- Only supports redacting Stripe internal objects (e.g., customers); external data sources are not supported

### Path 2: Configure compliance settings through the console

**Best For**: Users who need to manually configure PSD3 compliance options or SCA exemption rules and prefer a graphical interface.

**Brief Description**: The Stripe Dashboard console provides a graphical interface for configuring PSD3 compliance options and SCA exemption rules — completing financial regulatory setup without writing code. Key paths include `Dashboard > Payments > Authentication` (for setting SCA Exemptions) and `Dashboard > Connect > Settings` (for Funds segregation under PSD3 Regulations). Supported operations include `Enable TRA-based exemptions`, `Mark as MOTO`, and selecting `Exemption Type`.

**Key technical facts**:
- Auth: Stripe Dashboard SSO
- Prerequisites: Business must be located in the EEA or UK; Cardholder's bank must be located in the EEA; Stripe account with access to SCA-ready products; For MOTO: PCI compliance and feature enablement via Stripe support; Stripe account with Connect enabled

**When to Use**:
- You need to quickly configure PSD3 funds segregation
- Your business is in the European Economic Area and needs to set SCA exemption rules
- You prefer a graphical interface over API integration
- One-time compliance configuration, not recurring tasks

**When NOT to Use**:
- You need to programmatically batch-process data redaction tasks
- Your business is outside the EEA/UK and cannot use SCA exemptions
- Stripe Connect is not enabled, so PSD3 compliance cannot be configured
- You need automated integration into an existing compliance system

**Known Limitations**:
- Only applies to SCA exemption configuration for EEA/UK businesses
- MOTO (mail order/telephone order) exemptions require an additional request to Stripe Support
- PSD3 compliance configuration requires Stripe Connect to be enabled
- Cannot be configured automatically via API; all operations require manual console actions

## FAQ

Q: Which path should I start with?
A: If you're configuring SCA exemptions or PSD3 settings for the first time and your business is in the EEA/UK, start with **Configure compliance settings through the console**. If you need to auto-respond to GDPR deletion requests, you must use **Manage data redaction jobs via the API**.

Q: What if my business isn't in the EEA or UK but I use the console path to configure SCA Exemptions?
A: You won't see or be able to enable the relevant options (such as `Enable TRA-based exemptions` or `Mark as MOTO`) — these features are only available to EEA/UK merchants.

Q: What if I need to process hundreds of GDPR deletion requests per day but pick the console path?
A: You won't be able to automate it, and you'd need to handle each one manually (and the console doesn't even support data redaction jobs), causing compliance delays or violations.

Q: I'm not familiar with APIs — what problems will I hit using the Redaction Job API?
A: You may misuse `sk_test_`/`sk_live_` keys, ignore `validation_errors`, or forget to call `run redaction job`, leaving jobs stuck in validation and unable to actually delete data.

Q: Can I configure PSD3 Funds segregation via the API?
A: No. PSD3-related settings (including Funds segregation) can only be configured manually under `Dashboard > Connect > Settings`, and require Stripe Connect to be enabled.

Q: Can a redaction job auto-fix validation failures?
A: No. You must inspect `validation_errors`, correct the inputs (e.g., customer ID format), and resubmit the request with the correct `validation_behavior`.

Q: What if I prefer a graphical interface but pick the API path?
A: You'll have to write and debug code to call the Redaction Job API. This path provides no graphical option, which can significantly increase implementation effort.

Q: What if my business isn't in the EEA/UK but I pick the console path?
A: You won't be able to access SCA exemption configuration features (such as TRA-based exemptions or Mark as MOTO) — those options are only shown to EEA/UK merchants.

### [Manage portal](https://company-skill.com/p/stripe/stripe-manage-portal.md)

## What You Want to Do

You want to let Stripe customers self-serve — viewing invoices, updating payment methods, managing subscriptions — while controlling the portal's feature scope and appearance. You'll create portal sessions via the API and may need to configure or update portal behavior.

**Typical User Questions**:
- How do I set up a billing portal for customers?
- Can customers update their payment methods themselves?
- How do I customize the billing portal's appearance and features?
- Can I restrict what customers can do in the billing portal?

## Decision Tree

Pick the path that best matches your situation:

- **If** you need fine-grained control over portal features (e.g., enable `features[invoice_history][enabled]` but disable subscription cancellation) or **deep link** to specific actions (e.g., payment_method_update) → use [Fully configure the billing portal via the API](#path-1-fully-configure-the-billing-portal-via-the-api) (jump to *stripe/stripe-portal*)
- **If** you only need basic self-service features (e.g., invoice history, customer info updates) and use the default portal configuration (`is_default: true`) → use [Use the simplified API to manage the portal](#path-2-use-the-simplified-api-to-manage-the-portal) (jump to *stripe/stripe-billing-portal*)
- **If** you already have a portal configuration ID (e.g., `bpc_...`) and just need to **update configuration** or **retrieve configuration** (e.g., dynamically modify `business_profile[privacy_policy_url]`) → use [Update configuration via the Billing Portal Management API](#path-3-update-configuration-via-the-billing-portal-management-api) (jump to *stripe/stripe-billing*)
- **Otherwise (default)** → use [Fully configure the billing portal via the API], since it supports the full feature set, multi-config management, and deep links — fitting most customization scenarios.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|--------------|
| Fully configure the billing portal via the API | Developers needing fine-grained control over portal configuration (enabling/disabling specific features) and creating sessions via API. | medium | Yes | Yes | Supports `metadata` and `deep link`; can manage multiple configurations (distinguished by `name`) | `stripe/api/stripe-portal` |
| Use the simplified API to manage the portal | Integrations that need only basic portal configuration and session creation, preferring a clean API. | low | Yes | Yes | Only supports basic features (e.g., `features[invoice_history][enabled]`); cannot manage multiple configurations | `stripe/api/stripe-billing-portal` |
| Update configuration via the Billing Portal Management API | Users already on Stripe Billing who want to manage portal configuration directly through billing-related APIs. | medium | Yes | Yes | Only supports **update configuration** and **retrieve configuration**; cannot create new configurations | `stripe/api/stripe-billing` |

## Path Details

### Path 1: Fully configure the billing portal via the API

**Best For**: Developers needing fine-grained control over portal configuration (enabling/disabling specific features) and creating sessions via API.

**Brief Description**: Use the `billing_portal/configurations` API to fully manage customer billing portal configurations, including `features` (e.g., subscription management, invoice history), `business_profile`, `default_return_url`, `login_page`, and `metadata`. Supports creating multiple configurations and generating customer access links via `portal session`, plus **deep link** support via `flow_data`.

**Key technical facts**:
- Auth: API key authentication via Authorization header (Bearer `<secret_key>`) or HTTP Basic Auth (`-u sk_test_...:`)

**When to Use**:
- You need fine-grained control over portal features (e.g., allow customers to update email/tax_id but disable subscription cancellation)
- You need to dynamically create multiple portals with different configurations (distinguished by `name`)
- You need **deep link** support to jump directly to specific actions (e.g., payment_method_update)
- You need to attach structured `metadata` for internal tracking

**When NOT to Use**:
- You only need basic portal features and prefer Dashboard UI configuration
- You have no server-side development capability (this path requires code implementation)
- You don't need multi-configuration management (the default configuration is sufficient)

**Known Limitations**:
- Must be called from server-side code (no pure-frontend implementation)
- POST request parameters must use `application/x-www-form-urlencoded` format (not JSON)
- **Deep link** functionality requires explicit `flow_data` parameters
- `business_profile` is required in older API versions (optional in newer versions)

### Path 2: Use the simplified API to manage the portal

**Best For**: Integrations that need only basic portal configuration and session creation, preferring a clean API.

**Brief Description**: Provides simplified **customer portal** configuration via `billing_portal/configurations` and `billing_portal/sessions`, supporting basic feature toggles (e.g., `features[invoice_history][enabled]`), `business_profile` settings, and `default_return_url`. Suited for quickly integrating a **self-service billing** UI.

**Key technical facts**:
- Auth: API key authentication via Authorization header (Bearer `<secret_key>`)

**When to Use**:
- You only need basic portal features (invoice history, customer info updates)
- You prefer a clean API surface (fewer parameters)
- You use the default portal configuration (no multi-config management needed)
- Quick integration of a self-service billing UI

**When NOT to Use**:
- You need fine-grained control over specific features (e.g., disable subscription cancellation but enable quantity adjustment)
- You need **deep link** support
- You need to manage multiple portal configurations
- You need to attach structured `metadata` for internal tracking

**Known Limitations**:
- Only supports basic portal configuration (lacks advanced features like `adjustable_quantity`)
- Must be called from server-side code (no pure-frontend implementation)
- POST request parameters must use form-encoded format (not JSON)
- Cannot manage multiple portal configurations (mainly targets the `is_default` config)

### Path 3: Update configuration via the Billing Portal Management API

**Best For**: Users already on Stripe Billing who want to manage portal configuration directly through billing-related APIs.

**Brief Description**: Focuses on **update configuration** and **retrieve configuration** for existing portal settings, including `business_profile[privacy_policy_url]`, `default_return_url`, `features`, `metadata`, and `active` status. Suited for scenarios with an existing `portal configuration`.

**Key technical facts**:
- Auth: API key authentication via HTTP Basic Auth (`-u "sk_test_...:"`)

**When to Use**:
- You have an existing Stripe Billing portal configuration and need to update business-profile URLs
- You need to dynamically toggle portal features (e.g., temporarily disable subscription cancellation)
- You need to update configurations periodically via automated scripts
- You only need to **retrieve configuration** details for auditing

**When NOT to Use**:
- You need to create new portal configurations
- You need to manage multiple configurations or list all of them
- You need to create a **portal session**
- You don't have an existing portal configuration ID

**Known Limitations**:
- Only supports update/retrieve operations (cannot create new configurations)
- Requires an existing portal configuration (must first be created another way)
- POST request parameters must use form-encoded format
- Configuration ID must be specified explicitly (no batch operations)

## FAQ

Q: Which path should I start with?
A: If unsure, start with **Fully configure the billing portal via the API**. It supports the full feature set, multi-configuration, and deep links — even if you currently only need basics, future expansion won't require migration.

Q: What if I need to send customers directly to the "update payment method" page but use **Use the simplified API to manage the portal**?
A: You won't be able to implement **deep link** — that path doesn't support `flow_data`, so customers can only land on the portal home page rather than a specific action.

Q: What if I don't have an existing portal configuration ID but use **Update configuration via the Billing Portal Management API**?
A: The API call will fail — that path requires a valid configuration ID (e.g., `bpc_...`) and cannot create new configurations.

Q: Can I call these APIs directly from frontend JavaScript to create a portal session?
A: No. All paths **must be called from server-side code** (since they require a Secret Key); the frontend can only redirect to the generated **portal session** URL.

Q: I want to temporarily disable the customer "cancel subscription" feature — which paths support this?
A: **Fully configure the billing portal via the API** or **Update configuration via the Billing Portal Management API**. The former lets you set this when creating the configuration; the latter lets you dynamically update the existing configuration's `features`.

Q: Is `business_profile` required?
A: It's required in older API versions, optional in newer ones. Setting fields like `business_profile[privacy_policy_url]` is recommended to build customer trust.

Q: Can the same configuration serve multiple customers?
A: Yes. **Portal session**s generated by all paths are bound to a specific customer ID, but the underlying `portal configuration` (defined by `billing_portal/configurations`) can be reused across many customers.

Q: What if you need **deep link** functionality but pick **Use the simplified API to manage the portal**?
A: You won't be able to implement deep links — that path doesn't support `flow_data` and can't navigate to specific action pages.

Q: What if you have no server-side development capability but pick **Fully configure the billing portal via the API**?
A: You won't be able to call the API — all paths require server-side code (no pure-frontend support).


## Frequently asked questions

### When should I use the API vs. the Stripe Dashboard?

Use the API for programmatic integration, automation, and custom workflows. Use the Dashboard for manual operations, monitoring, and one-off tasks.

### How do I get started with Stripe API integration?

First obtain your API keys from the Dashboard (Developers > API keys), then install the appropriate SDK for your programming language and authenticate requests using your secret key.

### What's the difference between test mode and live mode?

Test mode allows you to simulate payments and operations without processing real transactions. Switch to live mode only when ready for production use.

### How do I handle webhooks for real-time notifications?

Configure webhook endpoints in your Dashboard (Developers > Webhooks) to receive event notifications. Always verify webhook signatures for security.

### Where can I find my API keys and how should I secure them?

API keys are in the Dashboard under Developers > API keys. Never expose secret keys in client-side code or public repositories. Use environment variables and consider restricted keys for enhanced security.

### How do I set up and configure shipping rates for my orders?

You can set up and manage shipping rates for your products using Stripe's dedicated shipping configuration tools. The platform supports creating, updating, retrieving, and comprehensively listing these rates for your orders.

### How can I customize the appearance and styling of my payment forms and elements?

You can style and customize Stripe Elements to match your brand using the platform's payment form customization guides. These tools allow you to adjust the appearance, behavior, and interactive states of your payment interfaces.

### How do I manage payment disputes, chargebacks, and process refunds?

You can manage chargebacks, disputes, and process refunds through Stripe's dedicated dispute and refund handling workflows. The platform provides specific paths for executing payment reversals and managing related financial transactions.

### How do I handle GDPR compliance and manage financial data privacy?

You can manage financial data compliance and privacy by utilizing Stripe's tools for handling GDPR, CCPA, and PSD3 regulatory requirements. These features ensure your integration meets necessary data protection standards while securely processing customer information.

## Cross-product integrations

- [A/B Test Compliant Checkout Flows](https://company-skill.com/p/_combos/a-b-test-compliant-checkout-flows-917b83.md) (vercel)
- [Branded SaaS Auth-to-Payment Onboarding Flow](https://company-skill.com/p/_combos/branded-saas-auth-to-payment-onboarding-flow-048510.md) (clerk)
- [Branded SaaS Onboarding with Custom Stripe Elements](https://company-skill.com/p/_combos/branded-saas-onboarding-with-custom-stripe-eleme-eab729.md) (clerk + ecs + oss + terraform + es)
- [Cross-Channel GDPR Data Deletion Pipeline](https://company-skill.com/p/_combos/cross-channel-gdpr-data-deletion-pipeline-b3ae33.md) (twilio)
- [Cross-Platform GDPR Compliance Orchestration](https://company-skill.com/p/_combos/cross-platform-gdpr-compliance-orchestration-3de6b2.md) (eb + twilio)
- [Event-Orchestrated GDPR Deletion Audit Pipeline](https://company-skill.com/p/_combos/event-orchestrated-gdpr-deletion-audit-pipeline-0c113f.md) (eb)
- [Feature-Flag Controlled Payment Rollout](https://company-skill.com/p/_combos/feature-flag-controlled-payment-rollout-817e59.md) (vercel + alinux + ecs + terraform + oss)
- [Fully Branded SaaS Auth and Payment](https://company-skill.com/p/_combos/fully-branded-saas-auth-and-payment-1e5957.md) (clerk)

## Use with an AI agent

```bash
curl -s https://company-skill.com/api/route \
  -H 'Content-Type: application/json' \
  -d '{"query": "...", "product": "stripe"}'
```

MCP server: https://company-skill.com/api/mcp/stripe.py

---
Machine-readable: https://company-skill.com/llms.txt · https://company-skill.com/sitemap.xml