# usePaymentMethods()

> Billing is currently in Beta and its APIs are experimental and may undergo breaking changes. To mitigate potential disruptions, we recommend [pinning](https://clerk.com/docs/pinning.md?sdk=nextjs) your SDK and `clerk-js` package versions.

The `usePaymentMethods()` hook provides access to the payment methods associated with a user or Organization. It returns a paginated list of payment methods and includes methods for managing them.

## Parameters

`usePaymentMethods()` accepts a single optional object with the following properties:

| Property                                          | Type                                 | Description                                                                                                                                                               |
| ------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="enabled"></a> `enabled?`                   | `boolean`                            | If `true`, a request will be triggered when the hook is mounted. Defaults to `true`.                                                                                      |
| <a id="for"></a> `for?`                           | `"user" | "organization"` | Specifies whether to fetch for the current user or Organization. Defaults to `'user'`.                                                                                    |
| <a id="infinite"></a> `infinite?`                 | `boolean`                            | If `true`, newly fetched data will be appended to the existing list rather than replacing it. Useful for implementing infinite scroll functionality. Defaults to `false`. |
| <a id="initialpage"></a> `initialPage?`           | `number`                             | A number that specifies which page to fetch. For example, if `initialPage` is set to 10, it will skip the first 9 pages and fetch the 10th page. Defaults to `1`.         |
| <a id="keeppreviousdata"></a> `keepPreviousData?` | `boolean`                            | If `true`, the previous data will be kept in the cache until new data is fetched. Defaults to `false`.                                                                    |
| <a id="pagesize"></a> `pageSize?`                 | `number`                             | A number that specifies the maximum number of results to return per page. Defaults to `10`.                                                                               |

## Returns

`usePaymentMethods()` returns an object with the following properties:

| Property                                       | Type                                                                                                                                                                                                                                                                                 | Description                                                                                                                                                                                                                 |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="count"></a> `count`                     | `number`                                                                                                                                                                                                                                                                             | The total count of data that exist remotely.                                                                                                                                                                                |
| <a id="data"></a> `data`                       | <code><a href="https://clerk.com/docs/nextjs/reference/types/billing-payment-method-resource.md">BillingPaymentMethodResource</a>[]</code>                                                                                                                                           | An array that contains the fetched data. For example, for the `memberships` attribute, data will be an array of [OrganizationMembership](https://clerk.com/docs/nextjs/reference/types/organization-membership.md) objects. |
| <a id="error"></a> `error`                     | <code>null | <a href="https://clerk.com/docs/nextjs/reference/types/clerk-api-response-error.md">ClerkAPIResponseError</a></code>                                                                                                                                                    | Clerk's API response error object.                                                                                                                                                                                          |
| <a id="fetchnext"></a> `fetchNext`             | `() => void`                                                                                                                                                                                                                                                              | A function that triggers the next page to be loaded. This is the same as `fetchPage(page => Math.min(pageCount, page + 1))`.                                                                                                |
| <a id="fetchpage"></a> `fetchPage`             | `ValueOrSetter`<`number`>                                                                                                                                                                                                                                                           | A function that triggers a specific page to be loaded.                                                                                                                                                                      |
| <a id="fetchprevious"></a> `fetchPrevious`     | `() => void`                                                                                                                                                                                                                                                              | A function that triggers the previous page to be loaded. This is the same as `fetchPage(page => Math.max(0, page - 1))`.                                                                                                    |
| <a id="hasnextpage"></a> `hasNextPage`         | `boolean`                                                                                                                                                                                                                                                                            | Indicates whether there are available pages to be fetched.                                                                                                                                                                  |
| <a id="haspreviouspage"></a> `hasPreviousPage` | `boolean`                                                                                                                                                                                                                                                                            | Indicates whether there are available pages to be fetched.                                                                                                                                                                  |
| <a id="iserror"></a> `isError`                 | `boolean`                                                                                                                                                                                                                                                                            | Indicates whether the request failed.                                                                                                                                                                                       |
| <a id="isfetching"></a> `isFetching`           | `boolean`                                                                                                                                                                                                                                                                            | Indicates whether there is an ongoing request or a revalidation.                                                                                                                                                            |
| <a id="isloading"></a> `isLoading`             | `boolean`                                                                                                                                                                                                                                                                            | Indicates whether there is an ongoing request and there is no fetched data.                                                                                                                                                 |
| <a id="page"></a> `page`                       | `number`                                                                                                                                                                                                                                                                             | The current page.                                                                                                                                                                                                           |
| <a id="pagecount"></a> `pageCount`             | `number`                                                                                                                                                                                                                                                                             | The total amount of pages. It is calculated based on `count`, `initialPage`, and `pageSize`.                                                                                                                                |
| <a id="revalidate"></a> `revalidate`           | <code>() => Promise<void></code>                                                                                                                                                                                                                                                     | A function that triggers a revalidation of the current page.                                                                                                                                                                |
| <a id="setdata"></a> `setData`                 | `CacheSetter`<<code>undefined | <a href="https://clerk.com/docs/nextjs/reference/types/clerk-paginated-response.md">ClerkPaginatedResponse</a><<a href="https://clerk.com/docs/nextjs/reference/types/billing-payment-method-resource.md">BillingPaymentMethodResource</a>></code>> | A function that allows you to set the data manually.                                                                                                                                                                        |

## Examples

### Basic usage

The following example demonstrates how to fetch and display a user's payment methods.

filename: app/billing/payment-methods/page.tsx
```tsx
'use client'

import { usePaymentMethods } from '@clerk/nextjs/experimental'

export default function PaymentMethodsList() {
  const { data, isLoading } = usePaymentMethods({
    for: 'user',
    pageSize: 10,
  })

  if (isLoading) {
    return <div>Loading payment methods...</div>
  }

  if (!data || data.length === 0) {
    // Code for how to add a new payment method: https://clerk.com/docs/guides/development/custom-flows/billing/add-new-payment-method
    return <div>No payment methods found. Please add a payment method to your account.</div>
  }

  return (
    <ul>
      {data?.map((method) => (
        <li key={method.id}>
          {method.cardType} **** {method.last4}
          {method.isDefault ? ' (Default)' : null}
        </li>
      ))}
    </ul>
  )
}
```

### Infinite pagination

The following example demonstrates how to implement infinite scrolling with payment methods.

filename: app/billing/payment-methods/page.tsx
```tsx
'use client'

import { usePaymentMethods } from '@clerk/nextjs/experimental'

export default function InfinitePaymentMethods() {
  const { data, isLoading, hasNextPage, fetchNext } = usePaymentMethods({
    for: 'user',
    infinite: true,
    pageSize: 20,
  })

  if (isLoading) {
    return <div>Loading...</div>
  }

  if (!data || data.length === 0) {
    // Code for how to add a new payment method: https://clerk.com/docs/guides/development/custom-flows/billing/add-new-payment-method
    return <div>No payment methods found. Please add a payment method to your account.</div>
  }

  return (
    <div>
      <ul>
        {data?.map((method) => (
          <li key={method.id}>
            {method.cardType} ending in {method.last4}
            {method.status === 'expired' ? ' (Expired)' : null}
            {method.status === 'disconnected' ? ' (Disconnected)' : null}
          </li>
        ))}
      </ul>

      {hasNextPage && <button onClick={() => fetchNext()}>Load more payment methods</button>}
    </div>
  )
}
```

### With checkout flow

The following example demonstrates how to use `usePaymentMethods()` in a checkout flow to select an existing payment method. For more information on how to build a checkout flow with an existing payment method, see [Build a custom checkout flow](https://clerk.com/docs/nextjs/guides/development/custom-flows/billing/checkout-existing-payment-method.md).

filename: app/billing/checkout/page.tsx
```tsx
'use client'

import { usePaymentMethods, useCheckout } from '@clerk/nextjs/experimental'
import { useRouter } from 'next/navigation'

export default function CheckoutPaymentSelection() {
  const { data, isLoading } = usePaymentMethods({ for: 'user' })
  const { checkout } = useCheckout()
  const router = useRouter()

  const handlePaymentSubmit = async (paymentMethodId: string) => {
    try {
      // Confirm checkout with selected payment method
      const { error } = await checkout.confirm({ paymentMethodId })
      if (error) {
        console.error(JSON.stringify(error, null, 2))
        return
      }
      // Complete checkout and redirect
      await checkout.finalize({
        navigate: ({ decorateUrl }) => {
          const url = decorateUrl('/')
          if (url.startsWith('http')) {
            window.location.href = url
          } else {
            router.push(url)
          }
        },
      })
    } catch (error) {
      console.error('Payment failed:', error)
    }
  }

  if (isLoading) {
    return <div>Loading payment methods...</div>
  }

  if (!data || data.length === 0) {
    // Code for how to add a new payment method: https://clerk.com/docs/guides/development/custom-flows/billing/checkout-new-payment-method
    return <div>No payment methods found. Please add a payment method to your account.</div>
  }

  return (
    <div>
      <h3>Select a payment method</h3>
      {data?.map((method) => (
        <button key={method.id} onClick={() => handlePaymentSubmit(method.id)}>
          Pay with {method.cardType} ending in {method.last4}
        </button>
      ))}
    </div>
  )
}
```

## Next steps

- [Checkout flow with a new payment method](https://clerk.com/docs/guides/development/custom-flows/billing/checkout-new-payment-method.md?sdk=nextjs): Build a custom checkout flow that allows users to add a new payment method during checkout.
- [Add a new payment method outside of a checkout flow](https://clerk.com/docs/guides/development/custom-flows/billing/add-new-payment-method.md?sdk=nextjs): Build a custom user interface that allows users to add a new payment method to their account.

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)