useCapxulPayments

Query hook for the signed-in user's payment ledger — the list of Payments, newest state included.

Reads the signed-in user's payment ledger — every Payment the user owns, including instant sends, commitments, payouts, and withdrawals. Read a single payment with useCapxulPayment; create payments with useCapxulPay.

Import

import { useCapxulPayments } from "@capxul/sdk-react";

Usage

"use client";

import { useCapxulPayments } from "@capxul/sdk-react";

function PaymentList() {
  const payments = useCapxulPayments();

  if (payments.isLoading) return <p>Loading payments…</p>;
  if (payments.error) return <p>{payments.error.message}</p>;

  return (
    <ul>
      {payments.data.map((payment) => (
        <li key={payment.id}>
          {payment.recipient.label} — {payment.amount.value}{" "}
          {payment.amount.currency} ({payment.status})
        </li>
      ))}
    </ul>
  );
}

Parameters

options

{ enabled?: boolean } | undefined

Pass enabled: false to skip the read until your UI is ready for it. The query is also disabled automatically until the provider finishes bootstrapping.

Return type

import { type UseCapxulPaymentsReturn } from "@capxul/sdk-react";
// UseQueryResult<readonly Payment[], CapxulError>

data is a read-only array of Payment: id, status (pending, submitted, pending_claim, scheduled, streaming, settled, cancelled, redirected, expired, or failed), amount (a decimal money value, never raw token units), paymentType, the recipient's kind and label, attached document references, the timing clause, and the released / availableToClaim amounts for commitments.

The hook returns TanStack Query's UseQueryResult. The most-used fields:

Field	Description
`data`	The query data (typed per hook, shown above). `undefined` until the first success.
`error`	A `CapxulError` when the last fetch failed, otherwise `null`.
`status`	`'pending'` \| `'error'` \| `'success'`.
`isLoading`	`true` during the first fetch (no data yet).
`isFetching`	`true` whenever a fetch is in flight, including background refetches.
`refetch`	Manually refetch the query.

Capxul query hooks stay pending until the provider finishes bootstrapping — you do not need to gate them on useCapxul() yourself. The full field list is in the TanStack Query useQuery reference; see also the TanStack Query integration guide.

Query key

["capxul", "payments"] — invalidated automatically by money mutations (useCapxulPay, useCapxulPayout, useCapxulWithdraw, payroll runs, …), so the ledger refreshes after every send. Note useCapxulTransfer does not invalidate it — a Transfer stays inside your Account and never appears in the payments ledger.

Client method

This hook wraps client.payments.list() on the core SDK.