useCapxulWithdraw

Mutation hook for cashing out to an external wallet address, backed by a required Withdrawal document.

Cashes out to an external wallet. This is the one lane on the payments surface that takes a raw 0x address — the useCapxulPay lane rejects bare addresses by design. Every withdrawal carries a committed Withdrawal document that records the audited destination and amount.

Import

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

Usage

"use client";

import { useCapxulWithdraw } from "@capxul/sdk-react";
import type { PaymentsWithdrawInput } from "@capxul/sdk";

function WithdrawButton({ input }: { input: PaymentsWithdrawInput }) {
  const withdraw = useCapxulWithdraw();

  return (
    <div>
      <button disabled={withdraw.isPending} onClick={() => withdraw.mutate(input)}>
        {withdraw.isPending ? "Withdrawing…" : "Withdraw"}
      </button>
      {withdraw.error ? <p>{withdraw.error.message}</p> : null}
      {withdraw.data ? (
        <p>
          Sent to {withdraw.data.recipient.label} — {withdraw.data.status}
        </p>
      ) : null}
    </div>
  );
}

Parameters

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

Prop

Type

to must be an external wallet address: 0x followed by exactly 40 hex characters. Anything else fails with INVALID_INPUT.

document is required — the Withdrawal document envelope (WithdrawalDocumentEnvelopeV1) minted by the surface that prepares the withdrawal. The backend binds it to the request: the document's destination address must equal to, and its committed amount must equal amount — a mismatch is rejected with INVALID_INPUT, so the audited cash-out record can never disagree with where or how much money is sent. Documents of any other kind are rejected.

Return type

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

On success, data is a Payment in pending status with instant timing. Its recipient kind is external_address and its label is the redacted destination address — the full address never appears on the returned payment. The committed Withdrawal document is referenced in documents.

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 personal money state: the payments list (and payment detail queries under it), the personal account balance, and the personal insights summary and history.

Errors

Failures surface as a CapxulError on error / thrown from mutateAsync — INVALID_INPUT when to is not a valid external address, when the document is missing or not a Withdrawal document, or when the document's destination or amount disagrees with the request.

Client method

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