# `Stripe.Services.PaymentMethodService`
[🔗](https://github.com/jeffhuen/tiger_stripe/blob/main/lib/stripe/services/payment_method_service.ex#L2)

PaymentMethod

PaymentMethod objects represent your customer's payment instruments.
You can use them with [PaymentIntents](https://docs.stripe.com/payments/payment-intents) to collect payments or save them to
Customer objects to store instrument details for future payments.

Related guides: [Payment Methods](https://docs.stripe.com/payments/payment-methods) and [More Payment Scenarios](https://docs.stripe.com/payments/more-payment-scenarios).

# `attach`

```elixir
@spec attach(Stripe.Client.t(), String.t(), map(), keyword()) ::
  {:ok, term()} | {:error, Stripe.Error.t()}
```

Attach a PaymentMethod to a Customer

Attaches a PaymentMethod object to a Customer.

To attach a new PaymentMethod to a customer for future payments, we recommend you use a [SetupIntent](https://docs.stripe.com/docs/api/setup_intents)
or a PaymentIntent with [setup_future_usage](https://docs.stripe.com/docs/api/payment_intents/create#create_payment_intent-setup_future_usage).
These approaches will perform any necessary steps to set up the PaymentMethod for future payments. Using the `/v1/payment_methods/:id/attach`
endpoint without first using a SetupIntent or PaymentIntent with `setup_future_usage` does not optimize the PaymentMethod for
future use, which makes later declines and payment friction more likely.
See [Optimizing cards for future payments](https://docs.stripe.com/docs/payments/payment-intents#future-usage) for more information about setting up
future payments.

To use this PaymentMethod as the default for invoice or subscription payments,
set [`invoice_settings.default_payment_method`](https://docs.stripe.com/docs/api/customers/update#update_customer-invoice_settings-default_payment_method),
on the Customer to the PaymentMethod’s ID.

# `create`

```elixir
@spec create(Stripe.Client.t(), map(), keyword()) ::
  {:ok, term()} | {:error, Stripe.Error.t()}
```

Shares a PaymentMethod

Creates a PaymentMethod object. Read the [Stripe.js reference](https://docs.stripe.com/docs/stripe-js/reference#stripe-create-payment-method) to learn how to create PaymentMethods via Stripe.js.

Instead of creating a PaymentMethod directly, we recommend using the [PaymentIntents](https://docs.stripe.com/docs/payments/accept-a-payment) API to accept a payment immediately or the [SetupIntent](https://docs.stripe.com/docs/payments/save-and-reuse) API to collect payment method details ahead of a future payment.

# `detach`

```elixir
@spec detach(Stripe.Client.t(), String.t(), map(), keyword()) ::
  {:ok, term()} | {:error, Stripe.Error.t()}
```

Detach a PaymentMethod from a Customer

Detaches a PaymentMethod object from a Customer. After a PaymentMethod is detached, it can no longer be used for a payment or re-attached to a Customer.

# `list`

```elixir
@spec list(Stripe.Client.t(), map(), keyword()) ::
  {:ok, term()} | {:error, Stripe.Error.t()}
```

List PaymentMethods

Returns a list of all PaymentMethods.

# `retrieve`

```elixir
@spec retrieve(Stripe.Client.t(), String.t(), map(), keyword()) ::
  {:ok, term()} | {:error, Stripe.Error.t()}
```

Retrieve a PaymentMethod

Retrieves a PaymentMethod object attached to the StripeAccount. To retrieve a payment method attached to a Customer, you should use [Retrieve a Customer’s PaymentMethods](https://docs.stripe.com/docs/api/payment_methods/customer)

# `update`

```elixir
@spec update(Stripe.Client.t(), String.t(), map(), keyword()) ::
  {:ok, term()} | {:error, Stripe.Error.t()}
```

Update a PaymentMethod

Updates a PaymentMethod object. A PaymentMethod must be attached to a customer to be updated.

---

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