Skip to main content
Docs

usePaymentMethods()

Warning

Billing is currently in Beta and its APIs are experimental and may undergo breaking changes. 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

usePaymentMethods() returns an object with the following properties:

  • Name
    data
    Type
    [] | null
    Description

    An array of , 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

    A function to fetch the next page of payment methods.

  • Name
    fetchPrevious
    Type
    () => Promise<void>
    Description

    A 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.

Examples

Basic usage

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

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

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.

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

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.

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

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

  const handlePaymentSubmit = async (paymentMethodId: string) => {
    try {
      // Confirm checkout with selected payment method
      await confirm({ paymentSourceId: paymentMethodId })
      // Complete checkout and redirect
      finalize({ redirectUrl: '/dashboard' })
    } 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>
  )
}

Add a new payment method during checkout

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

Build a custom user interface that allows users to add a new payment method to their account

Feedback

What did you think of this content?
GitHubEdit on GitHub

Last updated on