āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/directory/clerk/clerk-docs/reference/hooks/use-payment-methods ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
usePaymentMethods()'
description: Access and manage payment methods in your React application with Clerk's usePaymentMethods() hook.
sdk: nextjs, reactThe 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.
usePaymentMethods() accepts a single object with the following properties:
Specifies whether to fetch payment methods for the current user or organization. Defaults to 'user'.
pageSize?numberThe number of payment methods to fetch per page. Defaults to 10.
initialPage?numberThe page number to start fetching from. Defaults to 1.
infinite?booleanWhen true, enables infinite pagination mode where new pages are appended to existing data. When false, each page replaces the previous data. Defaults to false.
keepPreviousData?booleanWhen true, the previous data will be kept while loading the next page. This helps prevent layout shifts. Defaults to false.
</Properties>
usePaymentMethods() returns an object with the following properties:
An array of payment methods, or null if the data hasn't been loaded yet.
isLoadingbooleanA boolean that indicates whether the initial data is still being fetched.
isFetchingbooleanA boolean that indicates whether any request is still in flight, including background updates.
hasNextPagebooleanA boolean that indicates whether there are more pages available to load.
hasPreviousPagebooleanA boolean that indicates whether there are previous pages available to load.
fetchNext() => Promise<void>A function to fetch the next page of payment methods.
fetchPrevious() => Promise<void>A function to fetch the previous page of payment methods.
pageCountnumberThe total number of available pages.
countnumberThe total number of payment methods available. </Properties>
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>
)
}
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>
)
}
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'
import { useRouter } from 'next/navigation'
function CheckoutPaymentSelection() {
const { data, isLoading } = usePaymentMethods({ for: 'user' })
const { checkout } = useCheckout()
const { confirm, finalize } = checkout
const router = useRouter()
const handlePaymentSubmit = async (paymentMethodId: string) => {
try {
// Confirm checkout with selected payment method
await confirm({ paymentSourceId: paymentMethodId })
// Complete checkout and redirect
await finalize({
navigate: () => router.push('/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>
)
}
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā