Stripe Skill

Last validated: 2026-10-14 | API version: 2026-09-30.endive (latest stable) REST base URL: https://api.stripe.com/v1/ Assumed product: Stripe Payments + Billing. Stripe Connect (multi-account platform) is covered in the Auth and Recipes sections.

⚠️ Changed 2026-09-30: Stripe opened the Endive release train (2026-09-30.endive), succeeding Dahlia (last Dahlia version: 2026-08-26.dahlia, additive only). Breaking changes in 2026-09-30.endive that affect server-side integrations (changelog):

• payment_method_types is no longer writable on PaymentIntent create/update/confirm, SetupIntent create/update, or Checkout Session create — passing it returns 400 payment_method_types_no_longer_supported. Use dynamic payment methods (automatic_payment_methods[enabled]=true, as the recipes below already do), optionally with excluded_payment_method_types, or allowed_payment_method_types for an explicit list. The field remains read-only on the object.
• billing_cycle_anchor on subscription update/resume and invoices/create_preview now takes an object: billing_cycle_anchor[type]=now instead of billing_cycle_anchor=now.
• Connect: the generic fraud rejection reason is replaced by specific fraud reasons, platform-initiated rejections are distinguished from Stripe's, and errors are returned for eventually-due requirements — treat these as open enums.
• The rest (Financial Connections countries → country, PayTo field removals, SEPA billing-address enforcement, BLIK decline codes, Reserve enums, Stripe.js payment request button deprecation) don't touch the REST calls in this doc.

Also new (non-breaking): subscriptions can be paused on demand (POST /v1/subscriptions/{id}/pause, flexible billing mode only) — paused status is no longer only a trial-end outcome; check status_details.

⚠️ Changed 2026-03-25: Stripe opened the Dahlia release train (2026-03-25.dahlia), succeeding Clover. Only the first version in a train carries breaking changes; later Dahlia versions (2026-04-22, 2026-05-27, 2026-06-24, 2026-07-29) are additive. Breaking changes in 2026-03-25.dahlia that affect server-side integrations:

• Connect / Capabilities API: risk requirements added to capability objects — code that enumerates requirement types must tolerate the new entries.
• Subscriptions: a new retention_policy cancellation reason can now appear on cancellation_details.reason. Treat the reason field as an open enum.
• Event destinations: the events_from parameter now takes string values.
• Issuing: the Visa card reference ID is now optional on token card references.
• The remaining breaking changes are in Stripe.js / Elements (renamed initCheckout() → initCheckoutElements(), initEmbeddedCheckout() → createEmbeddedCheckoutPage(), elements.update() now returns a Promise) and affect browser code, not the REST calls in this doc.

Older versions (2026-07-29.dahlia, 2026-02-25.clover) still work — Stripe supports old versions indefinitely for existing accounts — but examples below pin 2026-09-30.endive.

What this skill enables

• Collect one-time payments and save cards for future use without handling raw card data (PCI-compliant via Stripe.js / Payment Element).
• Create and manage recurring subscriptions with automatic billing, dunning, and trial periods.
• Issue full or partial refunds and query payment history programmatically.
• Build hosted checkout flows (Checkout Sessions) that Stripe renders — no front-end payment UI required.
• Handle post-payment events reliably via webhooks: fulfil orders, provision access, update CRM records.
• Operate as a platform (Stripe Connect): onboard connected accounts, route payments, split revenue.
• Test the full payment lifecycle with Stripe's sandbox — no real money, no bank involvement.

Best-fit use cases

Key concepts & data model

Core objects

PaymentIntent lifecycle

requires_payment_method → requires_confirmation → requires_action → processing → succeeded
                                                                               ↘ canceled

Subscription lifecycle

Amounts and currencies

All monetary amounts are in the smallest currency unit — cents for USD, pence for GBP, yen for JPY (which has no subunit, so 100 = ¥100). Always store and pass amounts as integers.

Expandable fields

Any field that returns an ID (e.g., "customer": "cus_xxx") can be expanded to the full object by passing expand[]=customer in the request. Nest with dots: expand[]=latest_invoice.confirmation_secret.

Metadata

Every Stripe object has a metadata dictionary for storing arbitrary key/value pairs (e.g., your internal IDs). Limits: 50 keys per object, key ≤ 40 chars, value ≤ 500 chars.

Authentication & permissions

API key types

Create restricted keys in Dashboard → Developers → API keys → Create restricted key. Assign None / Read / Write per resource (Customers, PaymentIntents, Subscriptions, etc.).

Authentication header

Stripe uses HTTP Basic auth with the secret key as the username and an empty password. All major HTTP clients also accept Authorization: Bearer sk_...:

# Basic auth (canonical Stripe style)
curl https://api.stripe.com/v1/customers \
  -u "sk_test_51Abc123...:

# Bearer token (equivalent)
curl https://api.stripe.com/v1/customers \
  -H "Authorization: Bearer sk_test_51Abc123..."

API version pinning

Always pin the API version explicitly to avoid unexpected behaviour when Stripe releases a new default:

curl https://api.stripe.com/v1/payment_intents \
  -u "sk_test_...:" \
  -H "Stripe-Version: 2026-09-30.endive" \
  -d amount=2000 \
  -d currency=usd

Set a default version for your account in Dashboard → Developers → API version. The SDK reads your account default unless you override per-request.

Stripe Connect — acting on behalf of a connected account

Pass Stripe-Account: acct_xxx to perform an API call in the context of a connected account using your platform key:

curl https://api.stripe.com/v1/customers \
  -u "sk_live_platform...:" \
  -H "Stripe-Account: acct_1ABCxyzConnected"

Idempotency keys

Use Idempotency-Key on every POST request to safely retry without double-charging:

curl https://api.stripe.com/v1/payment_intents \
  -u "sk_test_...:" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d amount=2000 \
  -d currency=usd

• Keys are strings up to 255 characters; UUIDs v4 are recommended.
• Results are cached for 24 hours. Reusing a key after expiry generates a new request.
• Reusing a key with different parameters returns a 409 Conflict idempotency_error.
• Only use on POST — GET and DELETE are inherently idempotent.

Common workflows (recipes)

1. Create a one-time payment (PaymentIntent flow)

Server-side — create PaymentIntent:

curl https://api.stripe.com/v1/payment_intents \
  -u "sk_test_...:" \
  -H "Idempotency-Key: order-42-$(date +%s)" \
  -d amount=4999 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]=true" \
  -d "metadata[order_id]=order_42"

Response (key fields):

{
  "id": "pi_3OxAbc2eZvKYlo2C1hb8mT9k",
  "object": "payment_intent",
  "amount": 4999,
  "currency": "usd",
  "status": "requires_payment_method",
  "client_secret": "pi_3OxAbc...hb8mT9k_secret_Xyz",
  "metadata": { "order_id": "order_42" }
}

Client-side — confirm with Stripe.js:

const { error } = await stripe.confirmPayment({
  elements,                      // Stripe Elements instance
  clientSecret: pi.client_secret,
  confirmParams: {
    return_url: "https://example.com/order/complete"
  }
});

Fulfil on webhook payment_intent.succeeded — see Recipes #7.

2. Save a card for future use

# Step 1 — create or retrieve the Customer
curl https://api.stripe.com/v1/customers \
  -u "sk_test_...:" \
  -d email="alice@example.com" \
  -d "metadata[user_id]=usr_99"

# Step 2 — create a SetupIntent (confirm later via Stripe.js)
curl https://api.stripe.com/v1/setup_intents \
  -u "sk_test_...:" \
  -d customer=cus_PAbcXyz \
  -d "automatic_payment_methods[enabled]=true"

After the client confirms the SetupIntent, the PaymentMethod is attached to the Customer. To charge it later:

curl https://api.stripe.com/v1/payment_intents \
  -u "sk_test_...:" \
  -d amount=2000 \
  -d currency=usd \
  -d customer=cus_PAbcXyz \
  -d payment_method=pm_1ABCdefGhIjKlMnO \
  -d confirm=true \
  -d off_session=true

off_session=true signals that the customer is not present — Stripe will attempt to complete without 3DS if allowed by the card issuer.

3. Create a subscription

# Step 1 — ensure Customer has a default PaymentMethod
curl https://api.stripe.com/v1/customers/cus_PAbcXyz \
  -u "sk_test_...:" \
  -X POST \
  -d invoice_settings[default_payment_method]=pm_1ABCdefGhIjKlMnO

# Step 2 — create the Subscription
curl https://api.stripe.com/v1/subscriptions \
  -u "sk_test_...:" \
  -d customer=cus_PAbcXyz \
  -d "items[0][price]=price_1ABCdefGhIjKlMnO" \
  -d payment_behavior=default_incomplete \
  -d "expand[]=latest_invoice.confirmation_secret"

payment_behavior=default_incomplete starts the subscription in incomplete status — confirm payment client-side using latest_invoice.confirmation_secret.client_secret before it expires (23 hours).

⚠️ Changed 2025-03-31: Since 2025-03-31.basil (and therefore on the 2026-09-30.endive version pinned here), the Invoice object no longer has payment_intent (nor charge / paid) — an invoice can have multiple payments, listed in invoice.payments (expandable; each entry is an InvoicePayment). To collect the first payment, expand latest_invoice.confirmation_secret instead of latest_invoice.payment_intent. current_period_start / current_period_end also moved off the Subscription onto each subscription item: read items.data[].current_period_end. (invoice change, period change)

Response (key fields):

{
  "id": "sub_1ABCdef...",
  "status": "incomplete",
  "items": {
    "data": [
      {
        "id": "si_1ABCdef...",
        "current_period_start": 1737400000,
        "current_period_end": 1740000000
      }
    ]
  },
  "latest_invoice": {
    "id": "in_1ABCdef...",
    "confirmation_secret": {
      "client_secret": "pi_...secret_...",
      "type": "payment_intent"
    }
  }
}

4. Create a hosted Checkout Session

No front-end payment form — Stripe hosts and renders it:

curl https://api.stripe.com/v1/checkout/sessions \
  -u "sk_test_...:" \
  -d mode=payment \
  -d "line_items[0][price]=price_1ABCdefGhIjKlMnO" \
  -d "line_items[0][quantity]=1" \
  -d success_url="https://example.com/success?session_id={CHECKOUT_SESSION_ID}" \
  -d cancel_url="https://example.com/cancel" \
  -d customer_email="alice@example.com"

Redirect the browser to session.url. Stripe handles the payment UI and redirects to success_url on completion. Confirm fulfilment via checkout.session.completed webhook — do not trust the redirect URL alone.

For a subscription Checkout Session, change mode=subscription and pass a recurring Price.

5. Issue a full refund

curl https://api.stripe.com/v1/refunds \
  -u "sk_test_...:" \
  -H "Idempotency-Key: refund-ch_1ABC-$(date +%s)" \
  -d charge=ch_1ABCdefGhIjKlMnO

Partial refund — add amount in cents:

curl https://api.stripe.com/v1/refunds \
  -u "sk_test_...:" \
  -d charge=ch_1ABCdefGhIjKlMnO \
  -d amount=500

Response (key fields):

{
  "id": "re_1ABCdef...",
  "object": "refund",
  "amount": 500,
  "status": "succeeded",
  "charge": "ch_1ABCdef..."
}

Watch for charge.refunded webhook for async confirmation.

6. Handle a failed subscription payment

import stripe

stripe.api_key = "sk_live_..."

# Called from your webhook handler when invoice.payment_failed fires
def handle_payment_failed(invoice_id: str) -> None:
    invoice = stripe.Invoice.retrieve(invoice_id, expand=["subscription"])
    sub = invoice.subscription

    if sub.status == "past_due":
        # Notify the customer to update their payment method
        send_dunning_email(sub.customer, invoice.hosted_invoice_url)

    # Stripe will automatically retry according to your retry schedule
    # (Dashboard → Settings → Billing → Retry schedule)
    # To trigger an immediate retry:
    # stripe.Invoice.pay(invoice_id)

When the customer updates their payment method:

# Attach the new PaymentMethod to the Customer
curl https://api.stripe.com/v1/payment_methods/pm_NEW.../attach \
  -u "sk_live_...:" \
  -d customer=cus_PAbcXyz

# Attempt to pay the open invoice immediately
curl https://api.stripe.com/v1/invoices/in_OPEN.../pay \
  -u "sk_live_...:" \
  -X POST

7. Webhook receiver — verify and dispatch

import stripe
from flask import Flask, request, jsonify

app = Flask(__name__)
stripe.api_key = "sk_live_..."
WEBHOOK_SECRET = "whsec_..."

@app.post("/stripe/webhook")
def webhook():
    sig = request.headers.get("Stripe-Signature")
    try:
        event = stripe.Webhook.construct_event(
            payload=request.data,      # raw bytes — do NOT parse JSON first
            sig_header=sig,
            secret=WEBHOOK_SECRET,
        )
    except stripe.error.SignatureVerificationError:
        return jsonify(error="invalid signature"), 400

    match event["type"]:
        case "payment_intent.succeeded":
            handle_payment_succeeded(event["data"]["object"])
        case "invoice.paid":
            handle_invoice_paid(event["data"]["object"])
        case "customer.subscription.deleted":
            handle_subscription_cancelled(event["data"]["object"])
        case "checkout.session.completed":
            handle_checkout_complete(event["data"]["object"])

    # Must return 2xx within ~30 seconds or Stripe retries
    return jsonify(ok=True), 200

Critical rules:

• Always verify the Stripe-Signature header before processing.
• Read raw request body — any JSON parsing before construct_event may corrupt the signature.
• Return 200 before triggering long-running work (enqueue a job instead).
• Make handlers idempotent — Stripe may deliver the same event more than once. Use event.id to deduplicate.

8. Stripe Connect — charge on a connected account (destination charge)

# Create a PaymentIntent where funds go to the connected account
# Platform retains application_fee_amount
curl https://api.stripe.com/v1/payment_intents \
  -u "sk_live_platform...:" \
  -d amount=5000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]=true" \
  -d transfer_data[destination]=acct_1ConnectedAcct \
  -d application_fee_amount=500

Direct charge (create on the connected account itself):

curl https://api.stripe.com/v1/payment_intents \
  -u "sk_live_platform...:" \
  -H "Stripe-Account: acct_1ConnectedAcct" \
  -d amount=5000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]=true"

Create a connected account (Express onboarding):

# Step 1 — create the account
curl https://api.stripe.com/v1/accounts \
  -u "sk_live_platform...:" \
  -d type=express \
  -d country=US \
  -d email="seller@example.com"
# → { "id": "acct_1ABCdef...", ... }

# Step 2 — generate onboarding link
curl https://api.stripe.com/v1/account_links \
  -u "sk_live_platform...:" \
  -d account=acct_1ABCdef \
  -d "refresh_url=https://example.com/reauth" \
  -d "return_url=https://example.com/onboarded" \
  -d type=account_onboarding
# → { "url": "https://connect.stripe.com/setup/e/..." }

9. Retrieve customer payment history (list charges)

import stripe

stripe.api_key = "sk_live_..."

def get_customer_charges(customer_id: str, limit: int = 100) -> list:
    charges = []
    params = {
        "customer": customer_id,
        "limit": 100,
    }
    while True:
        page = stripe.Charge.list(**params)
        charges.extend(page.data)
        if not page.has_more:
            break
        params["starting_after"] = page.data[-1].id
    return charges

10. Cancel a subscription (at period end)

# Cancel at the end of the current billing period (no proration)
curl https://api.stripe.com/v1/subscriptions/sub_1ABCdef... \
  -u "sk_live_...:" \
  -X POST \
  -d cancel_at_period_end=true

# Cancel immediately
curl https://api.stripe.com/v1/subscriptions/sub_1ABCdef... \
  -u "sk_live_...:" \
  -X DELETE

Listen for customer.subscription.deleted webhook to revoke access.

Query patterns & filtering

Cursor-based pagination

All list endpoints return a consistent envelope:

{
  "object": "list",
  "data": [ ... ],
  "has_more": true,
  "url": "/v1/charges"
}

Parameters:

starting_after and ending_before are mutually exclusive.

Date range filters

All list endpoints support created[gte] / created[lte] (Unix timestamps):

# All charges from the last 7 days
curl "https://api.stripe.com/v1/charges?limit=100&created[gte]=$(date -v-7d +%s)" \
  -u "sk_live_...:"

Other common filter parameters:

Auto-pagination (Python SDK)

# Iterates all pages automatically
for charge in stripe.Charge.list(customer="cus_xxx", limit=100).auto_paging_iter():
    process(charge)

Search API

Stripe has a structured Search API for Customers, PaymentIntents, Charges, Subscriptions, and Invoices:

curl "https://api.stripe.com/v1/customers/search?query=email:'alice@example.com'" \
  -u "sk_live_...:"

Search is rate-limited to 20 read operations per second (stricter than list endpoints).

Reliability: rate limits, retries, idempotency

Rate limits

Endpoint-specific limits (stricter):

Rate limit response

HTTP 429 with header:

Stripe-Rate-Limited-Reason: global-rate

Possible values: global-concurrency, global-rate, endpoint-concurrency, endpoint-rate, resource-specific.

Retry with exponential backoff + jitter

import time, random, stripe

def stripe_call_with_retry(fn, *args, max_retries=5, **kwargs):
    for attempt in range(max_retries):
        try:
            return fn(*args, **kwargs)
        except stripe.error.RateLimitError:
            if attempt == max_retries - 1:
                raise
            wait = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait)
        except stripe.error.APIConnectionError:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

Python SDK auto-retry: stripe.max_network_retries = 3 enables built-in retry for network errors and 429s.

Idempotency

• Include Idempotency-Key on every POST (charge, refund, subscription creation).
• Use a stable key derived from your internal operation ID, e.g., f"order-{order_id}-payment".
• Results cached 24 hours; same key = same response (including 5xx errors).
• Different params + same key = 409 idempotency_error.

stripe.PaymentIntent.create(
    amount=4999,
    currency="usd",
    idempotency_key=f"order-{order_id}-payment-intent",
)

Error handling & troubleshooting

Error object

{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "decline_code": "insufficient_funds",
    "message": "Your card has insufficient funds.",
    "param": null,
    "charge": "ch_1ABCdef...",
    "doc_url": "https://stripe.com/docs/error-codes/card-declined"
  }
}

HTTP status → action

Error type → handler

Common decline_code values

Troubleshooting checklist

Security & compliance

PCI compliance

Stripe handles PCI scope when you use Stripe.js / Stripe Elements / Payment Element or Checkout Sessions — you never touch raw card numbers. Maintain SAQ A compliance:

• Never log, store, or transmit raw card numbers (number, cvc, full exp_month/exp_year combination).
• Never accept card data in your own API endpoint — only accept PaymentMethod IDs (pm_...) or tokens.
• Serve your payment page over HTTPS.
• If you find card data in logs, rotate the API keys immediately and notify Stripe.

API key security

• Store keys in environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault), never in source code.
• Use restricted keys for operations that don't need full access (e.g., a reporting service needs only Read on Charges and Invoices).
• Rotate keys immediately on suspected exposure: Dashboard → API keys → Roll key.
• Use sk_test_ in all non-production environments — a test key can never trigger live charges.

Webhook security

• Always verify Stripe-Signature before processing any webhook payload.
• Use a separate webhook signing secret (whsec_...) per endpoint — do not reuse across environments.
• Store the signing secret in environment variables.
• Reject webhooks with a timestamp more than 5 minutes old to prevent replay attacks (the SDK does this by default with a 300-second tolerance).

Stripe Connect — platform responsibilities

• Use the minimum Connect account type needed (Express > Standard > Custom — lower customisation = lower compliance burden).
• Platforms are responsible for complying with KYC/AML requirements for their connected accounts.
• Never display the connected account's full bank account or SSN to end users.

Audit trail

Every API action is logged in Dashboard → Developers → Logs (7-day retention for all accounts; extended with Sigma). Use metadata to attach your internal IDs for easier cross-referencing.

Testing checklist

Use sandbox keys (sk_test_, pk_test_) and the test card numbers below. No real money moves.

Test card numbers

Trigger test webhook events (Stripe CLI)

# Install: brew install stripe/stripe-cli/stripe
stripe login
stripe listen --forward-to localhost:8000/stripe/webhook

# In a separate terminal:
stripe trigger payment_intent.succeeded
stripe trigger invoice.payment_failed
stripe trigger customer.subscription.deleted
stripe trigger checkout.session.completed

QA checklist

• PaymentIntent created in sandbox; client_secret returned
• Test card 4242... → PaymentIntent reaches succeeded
• Decline card 4000...0002 → 402 with card_error, decline_code: card_declined
• 3DS card 4000...3155 → PaymentIntent reaches requires_action; completes after challenge
• Refund issued on succeeded Charge; re_... returned with status: succeeded
• Subscription created with payment_behavior=default_incomplete; first invoice payment confirmed
• invoice.payment_failed webhook received and processed without error
• cancel_at_period_end=true sets flag; customer.subscription.deleted fires at period end
• Webhook signature verification passes for valid payload; returns 400 for tampered payload
• Idempotency key: same request sent twice → identical response, no duplicate charge
• Pagination loop retrieves all pages (has_more=false terminates loop)
• Rate limit hit in sandbox (25 req/sec); 429 handled with backoff, eventual success

Sources

• Stripe API Reference
• Authentication & API Keys
• API Versioning & Changelog
• Payment Intents
• Subscriptions Overview
• Checkout Sessions
• Refunds
• Webhook Integration
• Idempotent Requests
• Rate Limits
• Error Codes
• Stripe Connect
• Testing
• Security Best Practices
• API Status