# Payment methods

> Cards your customers save at your processor, so subscriptions can charge renewals, upgrades and retries without the customer coming back.

A **payment method** is a card (or another method your processor supports) that a customer saved for later payments. [Subscriptions](https://ownrecord.io/docs/concepts/subscriptions.md) that collect automatically charge it for renewals, upgrades and retries, without the customer being there. The card itself stays at your [processor](https://ownrecord.io/docs/concepts/processors.md): Ownrecord keeps the processor's reference, the card brand, its last four digits, its expiry and its country, never the number. A saved method belongs to the processor connection it was saved with: a subscription keeps charging it there, even while that connection is degraded, until the customer saves another method. With Mollie, what is saved is a **mandate** (`cst_…/mdt_…`): a card mandate, or a SEPA Direct Debit mandate after an iDEAL or Bancontact payment.

## How a card gets saved

- **Subscription checkout.** When a customer pays the first invoice in a [checkout session](https://ownrecord.io/docs/concepts/checkout.md) in `subscription` mode, the payment also saves the card for later (an off-session payment intent). With a trial, the page saves the card without charging it.
- **Setup checkout.** A session in `setup` mode only saves a card. `POST /api/v1/subscriptions` answers with such a page (`paymentSetup.url`) when a subscription should be charged automatically and the customer has no card yet. You can also create one yourself for a customer whose card expired:

```http
POST /api/v1/checkout/sessions

{ "mode": "setup", "customer": "cus_01m4…", "successUrl": "https://app.example/billing" }
```

The method is saved when the processor confirms it, through its webhook, and `payment_method.attached` is sent to your webhooks. A card is saved once per customer: saving the same card again returns the method already saved.

## The default method

Each customer has at most one **default** method. A newly saved card becomes the default, and the previous default stays saved. A subscription charges its own `defaultPaymentMethodId` when it has one, and the customer's default otherwise.

- `GET /api/v1/customers/{customerId}/payment_methods` lists a customer's methods (add `includeDetached=true` for removed ones).
- `POST /api/v1/payment_methods/{id}/set_default` makes another saved method the default.
- `DELETE /api/v1/payment_methods/{id}` detaches a method: it's never charged again and stops being the default. The record stays, with `detachedAt`, so past payments still show the card they used. The processor detaches it too.

Reading methods needs `customers:read`; changing them needs `customers:write`. Changes send `payment_method.updated` and `payment_method.detached`.

## Charging a saved card

Ownrecord charges a saved card only for an open invoice of a subscription: the first invoice, an upgrade's invoice, or later a renewal or a retry. The charge is made after the invoice is safely recorded, with an idempotency key per invoice and attempt, so a retry never charges twice. The result arrives from the processor's webhook: a successful charge marks the invoice paid; a declined one leaves it open for collection to retry.

In development and tests the fake processor's test cards stand in for real ones: `pm_fake_visa` is accepted, and `pm_fake_decline` is declined.