## Stored Payment Methods

A stored payment method is a credit or debit card, bank account, or wallet that the client has saved for reuse. WHMCS calls these pay methods in the Admin Area and the Client Area, and the API route is `/user/paymethods`.

The gateway stores the card number or account details. These endpoints return an identifier that you pass to other endpoints, not a value that you can charge directly.

Info
These endpoints apply to any integration that collects payment, headless or not. For more information, see Pay Methods.

## Listing a Client's Methods

Read the client's stored payment methods from [`GET /user/paymethods`](/rest-api/reference/whmcs-rest-api/paths/~1user~1paymethods/get).

For example:

##### Using JavaScript

```js
const { data: methods } = await api('/user/paymethods');
```

##### Using cURL

```
curl -X GET --location "https://example.com/api/v2/user/paymethods"
  -H "X-Api-State: <your latest state token>"
```

The list paginates on the `page` and `page_size` values, and the client's default method comes first. An empty array indicates that the client has stored no payment methods.

- Pass the `id` value as the `payment.paymethod_id` value at checkout.
- The `gateway_is_active` value indicates whether the gateway behind the method is still usable.


Info
The `api()` wrapper above is the one that [Headless Stripe Payments](/rest-api/headless-stripe-payments) defines. For more information about the `X-Api-State` header that these endpoints require, see [Authentication](/rest-api/authentication).

## Reading and Removing a Method

[`GET /user/paymethods/{paymethod_id}`](/rest-api/reference/whmcs-rest-api/paths/~1user~1paymethods~1%7Bpaymethod_id%7D/get) returns one method. [`DELETE /user/paymethods/{paymethod_id}`](/rest-api/reference/whmcs-rest-api/paths/~1user~1paymethods~1%7Bpaymethod_id%7D/delete) removes one.

The following failure responses require different handling:

- A `422` response indicates a merchant setting. It recurs until the merchant enables **Allow Client Pay Method Removal** in the WHMCS Admin Area, on the **Security** tab at **Configuration > System Settings > General Settings**.
- A `409` response indicates a passing condition, so a later retry can succeed.
- A `429` response indicates that the request exceeded the rate limit, so WHMCS did not remove the payment method.


Info
For more information, see [Rate Limits](/rest-api/rate-limits).

## Declines at Checkout

Naming a stored payment method at checkout does not guarantee a charge. If the gateway declines the stored payment method, the `payment.status` value is `failed` and the API does not return an error response.

A headless checkout then returns a new `payment_session` value. Use that value to collect a different payment method.

Info
For more information, see [Headless Stripe Payments](/rest-api/headless-stripe-payments).