# `PhoenixKitBilling.Providers.Stripe`
[🔗](https://github.com/BeamLabEU/phoenix_kit_billing/blob/0.5.1/lib/phoenix_kit_billing/providers/stripe.ex#L1)

Stripe payment provider implementation.

This module implements the `PhoenixKitBilling.Providers.Provider` behaviour
for Stripe payments. It supports:

- Hosted Checkout for one-time payments
- Setup sessions for saving payment methods
- Charging saved payment methods (for subscription renewals)
- Webhook signature verification
- Refunds

## Configuration

Configure Stripe via the admin UI (`/admin/settings/billing/providers`)
or by writing the underlying `PhoenixKit.Settings` keys directly:

    PhoenixKit.Settings.update_setting("billing_stripe_enabled", "true")
    PhoenixKit.Settings.update_setting("billing_stripe_secret_key", "sk_test_...")
    PhoenixKit.Settings.update_setting("billing_stripe_webhook_secret", "whsec_...")

The secret key is read from `billing_stripe_secret_key` (falling back to
the legacy `billing_stripe_api_key`); see `stripe_secret_key/0`.

## Webhook Events

Configure your Stripe webhook to send these events:
- `checkout.session.completed` - Payment completed
- `checkout.session.expired` - Session expired
- `payment_intent.succeeded` - Payment succeeded (for saved cards)
- `payment_intent.payment_failed` - Payment failed
- `charge.refunded` - Refund processed
- `setup_intent.succeeded` - Card saved successfully

## Dependencies

Talks to the Stripe REST API directly over `Req` — no `stripe` hex
package is required.

# `charge_payment_method`

Charges a saved payment method.

Used for subscription renewals where the payment method was previously saved.

## Options

- `:currency` - Currency code (default: EUR)
- `:description` - Description for the charge
- `:invoice_uuid` - Associated invoice UUID
- `:metadata` - Additional metadata

## Examples

    iex> charge_payment_method(payment_method, Decimal.new("99.00"), currency: "EUR")
    {:ok, %{id: "pi_...", provider_transaction_id: "ch_...", status: "succeeded"}}

# `create_checkout_session`

Creates a Stripe Checkout Session for one-time payment.

## Options

- `:success_url` - URL to redirect after successful payment (required)
- `:cancel_url` - URL to redirect if user cancels (required)
- `:save_payment_method` - Whether to save card for future use (default: false)
- `:customer_email` - Pre-fill customer email
- `:metadata` - Additional metadata to attach

## Examples

    iex> create_checkout_session(invoice, success_url: "https://...", cancel_url: "https://...")
    {:ok, %{id: "cs_test_...", url: "https://checkout.stripe.com/..."}}

# `create_refund`

Creates a refund for a Stripe charge.

## Options

- `:reason` - Reason for refund ("duplicate", "fraudulent", "requested_by_customer")
- `:metadata` - Additional metadata

## Examples

    iex> create_refund("ch_xxx", Decimal.new("50.00"), reason: "requested_by_customer")
    {:ok, %{id: "re_...", provider_refund_id: "re_...", amount: #Decimal<50.00>}}

# `create_setup_session`

Creates a Stripe Setup Session to save a payment method.

## Options

- `:success_url` - URL to redirect after success (required)
- `:cancel_url` - URL to redirect if user cancels (required)
- `:customer_email` - Customer email

## Examples

    iex> create_setup_session(user, success_url: "https://...", cancel_url: "https://...")
    {:ok, %{id: "seti_...", url: "https://checkout.stripe.com/..."}}

# `detach_payment_method`

Detaches a payment method from its customer.

## Examples

    iex> detach_payment_method("pm_xxx")
    :ok

# `get_payment_method_details`

Gets details of a saved payment method from Stripe.

## Examples

    iex> get_payment_method_details("pm_xxx")
    {:ok, %{id: "pm_xxx", type: "card", brand: "visa", last4: "4242", ...}}

# `handle_webhook_event`

Handles and normalizes Stripe webhook events.

## Supported Events

- `checkout.session.completed` - Checkout payment completed
- `checkout.session.expired` - Checkout session expired
- `payment_intent.succeeded` - Payment intent succeeded
- `payment_intent.payment_failed` - Payment failed
- `charge.refunded` - Charge refunded
- `setup_intent.succeeded` - Setup intent completed (card saved)

## Examples

    iex> handle_webhook_event(%{"type" => "checkout.session.completed", ...})
    {:ok, %{type: "checkout.completed", event_id: "evt_...", data: %{...}}}

# `verify_webhook_signature`

Verifies Stripe webhook signature.

Uses Stripe's signature verification to ensure the webhook came from Stripe.

## Examples

    iex> verify_webhook_signature(raw_body, signature_header, webhook_secret)
    :ok

    iex> verify_webhook_signature(raw_body, "invalid", webhook_secret)
    {:error, :invalid_signature}

---

*Consult [api-reference.md](api-reference.md) for complete listing*