`usePaymentMethods()`

Warning

This API is experimental and subject to change while Clerk Billing is under Beta. To mitigate potential disruptions, we recommend pinning 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 object with the following properties:

Name
for?
Type
'user' | 'organization'
Description
Specifies whether to fetch payment methods for the current user or organization. Defaults to 'user'.
Name
pageSize?
Type
number
Description
The number of payment methods to fetch per page. Defaults to 10.
Name
initialPage?
Type
number
Description
The page number to start fetching from. Defaults to 1.
Name
infinite?
Type
boolean
Description
When true, enables infinite pagination mode where new pages are appended to existing data. When false, each page replaces the previous data. Defaults to false.
Name
keepPreviousData?
Type
boolean
Description
When true, the previous data will be kept while loading the next page. This helps prevent layout shifts. Defaults to false.

Returns

Name
data
Type
PaymentMethod[] | null
Description
An array of payment method objects, or null if the data hasn't been loaded yet.
Name
isLoading
Type
boolean
Description
A boolean that indicates whether the initial data is still being fetched.
Name
isFetching
Type
boolean
Description
A boolean that indicates whether any request is still in flight, including background updates.
Name
hasNextPage
Type
boolean
Description
A boolean that indicates whether there are more pages available to load.
Name
hasPreviousPage
Type
boolean
Description
A boolean that indicates whether there are previous pages available to load.
Name
fetchNext
Type
() => Promise<void>
Description
Function to fetch the next page of payment methods.
Name
fetchPrevious
Type
() => Promise<void>
Description
Function to fetch the previous page of payment methods.
Name
pageCount
Type
number
Description
The total number of available pages.
Name
count
Type
number
Description
The total number of payment methods available.

`PaymentMethod`

Each payment method object contains the following properties:

Name
id
Type
string
Description
The unique identifier for the payment method.
Name
type
Type
'card'
Description
The type of payment method. Currently, only card payments are supported.
Name
cardType
Type
string
Description
The type of card (e.g., 'visa', 'mastercard').
Name
last4
Type
string
Description
The last 4 digits of the card number.
Name
expirationDate
Type
string
Description
The expiration date of the card in 'MM/YY' format.
Name
isDefault
Type
boolean
Description
Specifies whether this is the default payment method.

Examples

Basic usage

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

import { usePaymentMethods } from '@clerk/nextjs'

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

  if (isLoading) {
    return <div>Loading payment methods...</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.

import { usePaymentMethods } from '@clerk/nextjs'

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

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

  return (
    <div>
      <ul>
        {data?.map((method) => (
          <li key={method.id}>
            {method.cardType} ending in {method.last4}
            <br />
            Expires: {method.expirationDate}
          </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.

import { usePaymentMethods, useCheckout } from '@clerk/nextjs'

function CheckoutPaymentSelection() {
  const { data, isLoading } = usePaymentMethods({ for: 'user' })
  const { checkout } = useCheckout()
  const { confirm, complete } = checkout

  const handlePaymentSubmit = async (paymentMethodId: string) => {
    try {
      // Confirm checkout with selected payment method
      await confirm({ paymentSourceId: paymentMethodId })
      // Complete checkout and redirect
      await complete({ redirectUrl: '/dashboard' })
    } catch (error) {
      console.error('Payment failed:', error)
    }
  }

  if (isLoading) {
    return <div>Loading payment methods...</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>
  )
}

Edit this page on GitHub

Last updated on Jul 24, 2025

usePaymentMethods()