useCapxulDestinations

Query hook for saved payout destinations — bank, mobile-money, and wallet metadata scoped to the acting entity.

Lists the saved destinations of the acting entity — the places money can be paid out to, saved once and later selected by id in useCapxulPayout. Save and retire them with useCapxulAddDestination and useCapxulRemoveDestination.

Stored metadata vs. settlement

Destination metadata can be stored for all three kinds — bank accounts, mobile-money numbers, and wallets — but the platform can only settle payouts to wallet (external_account) destinations today. Bank and mobile-money payouts are rejected. See Capability status.

Import

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

Usage

"use client";

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

function DestinationList() {
  const destinations = useCapxulDestinations({});

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

  return (
    <ul>
      {destinations.data.map((destination) => (
        <li key={destination.id}>
          {destination.label ?? destination.counterpartyId} — {destination.kind}
        </li>
      ))}
    </ul>
  );
}

Parameters

input

DestinationListInput | undefined

The query stays disabled while input is undefined. Pass {} to list every destination of the personal actor.

Prop

Type

target (or the lower-level ref) narrows the list to destinations saved for one counterparty. kind filters by destination kind (bank_account, mobile_money, external_account). actor scopes the list to the personal account (default) or an organization.

options

{ enabled?: boolean } | undefined

Pass enabled: false to skip the read until your UI is ready for it.

Return type

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

data is a read-only array of Destination: the opaque id (what useCapxulPayout takes), the counterparty it belongs to, its kind and rail, an optional label, and a kind-specific payload. Bank and mobile-money payloads are stored masked: account holder, bank name or operator, country, currency, and only the last four digits of the account or phone number. Wallet payloads carry the network and address.

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", "destinations", <serialized input>] — one cache entry per actor / target / kind combination, all sharing the ["capxul", "destinations"] prefix. Invalidated automatically by useCapxulAddDestination and useCapxulRemoveDestination.

Client method

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

useCapxulDestinations

On this page