āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/directory/clerk/clerk-docs/reference/hooks/use-payment-attempts ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
usePaymentAttempts()'
description: Access and manage payment attempts in your React application with Clerk's usePaymentAttempts() hook.
sdk: nextjs, reactThe usePaymentAttempts() hook provides access to the payment attempts associated with a user or organization. It returns a paginated list of payment attempts and includes methods for managing them.
usePaymentAttempts() accepts a single object with the following properties:
Specifies whether to fetch payment attempts for the current user or organization. Defaults to 'user'.
pageSize?numberThe number of payment attempts 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>
usePaymentAttempts() returns an object with the following properties:
An array of payment attempts, or null if the data hasn't been loaded yet.
isLoadingbooleanA boolean that is true if there is an ongoing request and there is no fetched data.
isFetchingbooleanA boolean that is true if there is an ongoing request or a revalidation.
hasNextPagebooleanA boolean that indicates if there are available pages to be fetched.
hasPreviousPagebooleanA boolean that indicates if there are available pages to be fetched.
fetchNextA function that triggers the next page to be loaded. This is the same as fetchPage(page => Math.min(pageCount, page + 1)).
fetchPreviousA function that triggers the previous page to be loaded. This is the same as fetchPage(page => Math.max(0, page - 1)).
pageCountnumberThe total amount of pages. It is calculated based on count, initialPage, and pageSize.
countnumberThe total number of payment attempts available.
errorReturns an error object if any part of the process fails.
fetchPage(page: number) => voidA function that triggers a specific page to be loaded.
isErrorbooleanA boolean that indicates the request failed.
pagenumberThe current page.
revalidateA function that triggers a revalidation of the current page.
setData(data: any[]) => voidA function that allows you to set the data manually. </Properties>
The following example demonstrates how to fetch and display a user's payment attempts.
import { usePaymentAttempts } from '@clerk/nextjs/experimental'
function PaymentAttemptsList() {
const { data, isLoading } = usePaymentAttempts({
for: 'user',
pageSize: 10,
})
if (isLoading) {
return <div>Loading payment attempts...</div>
}
if (!data || data.length === 0) {
return <div>No payment attempts found.</div>
}
return (
<ul>
{data?.map((attempt) => (
<li key={attempt.id}>
Payment #{attempt.id} - {attempt.status}
<br />
Amount: {attempt.amount.amountFormatted} on {new Date(attempt.updatedAt).toLocaleString()}
</li>
))}
</ul>
)
}
The following example demonstrates how to implement infinite scrolling with payment attempts.
import { usePaymentAttempts } from '@clerk/nextjs/experimental'
function InfinitePaymentAttempts() {
const { data, isLoading, hasNextPage, fetchNext } = usePaymentAttempts({
for: 'user',
infinite: true,
pageSize: 20,
})
if (isLoading) {
return <div>Loading...</div>
}
if (!data || data.length === 0) {
return <div>No payment attempts found.</div>
}
return (
<div>
<ul>
{data?.map((attempt) => (
<li key={attempt.id}>
Payment attempt for {attempt.amount.amountFormatted}
<br />
Status: {attempt.status}
<br />
{attempt.status === 'failed' && attempt.failedAt && (
<span>Failed At: {new Date(attempt.failedAt).toLocaleString()}</span>
)}
</li>
))}
</ul>
{hasNextPage && <button onClick={() => fetchNext()}>Load more payment attempts</button>}
</div>
)
}
The following example demonstrates how to use usePaymentAttempts() to display a detailed payment history table.
import { usePaymentAttempts } from '@clerk/nextjs/experimental'
function PaymentAttemptsHistory() {
const { data, isLoading } = usePaymentAttempts({ for: 'user' })
if (isLoading) {
return <div>Loading payment attempts...</div>
}
if (!data || data.length === 0) {
return <div>No payment attempts found.</div>
}
const getStatusColor = (status: string) => {
switch (status) {
case 'paid':
return 'green'
case 'failed':
return 'red'
case 'pending':
return 'orange'
default:
return 'gray'
}
}
return (
<table>
<thead>
<tr>
<th>Payment ID</th>
<th>Amount</th>
<th>Status</th>
<th>Date</th>
<th>Payment Method</th>
</tr>
</thead>
<tbody>
{data?.map((attempt) => (
<tr key={attempt.id}>
<td>{attempt.id}</td>
<td>{attempt.amount.amountFormatted}</td>
<td style={{ color: getStatusColor(attempt.status) }}>{attempt.status}</td>
<td>{attempt.paidAt ? new Date(attempt.paidAt).toLocaleDateString() : '-'}</td>
<td>
{attempt.paymentSource.cardType} ****{attempt.paymentSource.last4}
</td>
</tr>
))}
</tbody>
</table>
)
}
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā