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 direct payment and Commitment the user owns. 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 and the identity Account is claimed.

Return type

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

data is a read-only array of Payment: id, status (pending, settling, pending_claim, scheduled, streaming, settled, cancelled, or failed), amount (a decimal money value, never raw token units), paymentType, the recipient's kind and label, actor-relative direction, counterpartyLabel, a nullable settled receipt, attached document references, timing, and commitment amounts.

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 payment and Commitment mutations, so the ledger refreshes after every money operation.

Client method

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