useCapxulPayout

Mutation hook for paying out to a saved destination by id — currently settles wallet destinations only.

Pays out to a saved destination selected by its opaque id — the caller never re-enters account details on this path. Save destinations with useCapxulAddDestination and list them with useCapxulDestinations.

Wallet destinations only

The backend currently settles wallet (external_account) destinations only. A payout to a bank or mobile-money destination is rejected with INVALID_INPUT ("payout settlement requires a wallet destination") — the destination metadata can be stored, but there is no bank / mobile-money cash-out rail yet. See Capability status.

Import

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

Usage

"use client";

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

function PayoutButton() {
  const destinations = useCapxulDestinations({ kind: "external_account" });
  const payout = useCapxulPayout();
  const wallet = destinations.data?.[0];

  if (!wallet) return <p>No wallet destination saved yet.</p>;

  return (
    <div>
      <button
        disabled={payout.isPending}
        onClick={() =>
          payout.mutate({
            destinationId: wallet.id,
            amount: { currency: "USD", value: "100.00", decimals: 2 },
          })
        }
      >
        {payout.isPending ? "Paying out…" : `Pay out to ${wallet.label ?? "wallet"}`}
      </button>
      {payout.error ? <p>{payout.error.message}</p> : null}
    </div>
  );
}

Parameters

The hook itself takes no parameters. The mutation takes a PaymentsPayoutInput:

Prop

Type

destinationId must name a destination that belongs to the acting entity and has not been removed; otherwise the mutation fails with INVALID_INPUT ("destination not found").

actor. The input accepts an organization actor, but the backend rejects org payouts today ("org destination payout requires org settlement support") — payouts are personal-only in the current alpha. See Capability status.

Return type

import { type UseCapxulPayoutReturn } from "@capxul/sdk-react";
// UseMutationResult<Payment, CapxulError, PaymentsPayoutInput>

On success, data is the recorded Payment in pending status with instant timing. Its recipient kind is external_address and its label is the redacted destination address — the full address is never returned.

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

Field	Description
`mutate`	Fire the mutation (fire-and-forget; pair with `onSuccess`/`onError` callbacks).
`mutateAsync`	Fire the mutation and get a `Promise` of the result. Rejects with a `CapxulError` on failure.
`data`	The mutation result (typed per hook, shown above). `undefined` until the first success.
`error`	A `CapxulError` when the last attempt failed, otherwise `null`.
`isPending`	`true` while the mutation is in flight. Use it to disable submit buttons.
`reset`	Clear the mutation state (`data`, `error`) back to idle.

Mutations do not retry by default. The full field list is in the TanStack Query useMutation reference; see also the TanStack Query integration guide.

Cache behavior

On success this mutation refreshes the money state for the acting entity: the payments list (and payment detail queries under it), the insights summary and history, and the personal account balance (or the org treasury and account, once org payouts exist).

Errors

Failures surface as a CapxulError on error / thrown from mutateAsync. Notable modes: INVALID_INPUT when the destination id is unknown, removed, or not a wallet destination, and when an organization actor is passed.

Client method

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