useCapxulCancelRequest

Mutation hook that cancels a payment request an actor has issued, by request id.

Cancels a payment request an actor scope has issued. The request stops being payable and its status moves to cancelled. List issued requests with useCapxulRequests; issue new ones with useCapxulIssueRequest.

Import

import { capxulAccountScope, useCapxulCancelRequest } from "@capxul/sdk-react";

Usage

"use client";

import { capxulAccountScope, useCapxulCancelRequest } from "@capxul/sdk-react";

function CancelRequestButton({ requestId }: { requestId: string }) {
  const cancelRequest = useCapxulCancelRequest(capxulAccountScope);

  return (
    <button
      type="button"
      disabled={cancelRequest.isPending}
      onClick={() => cancelRequest.mutate(requestId)}
    >
      {cancelRequest.isPending ? "Cancelling…" : "Cancel request"}
    </button>
  );
}

To cancel a request issued by an organization, scope the hook with capxulOrgScope(orgId) instead.

Parameters

actor

CapxulActorScope | undefined — defaults to capxulAccountScope

Which actor's request to cancel. An explicit undefined also falls back to the personal scope — gate org-scoped controls on the org id being loaded. See Actor scopes.

Mutation input

The mutation takes the request id (string), as returned by useCapxulRequests or useCapxulIssueRequest.

Return type

import { type UseCapxulCancelRequestReturn } from "@capxul/sdk-react";
// UseMutationResult<ActorRequest, CapxulError, string>

On success, data is the updated ActorRequest with status: "cancelled".

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 invalidates, for the acting scope only: the requests list, the cancelled request's detail query, the address book, the scope's inbox (so a cancelled request stops showing as actionable anywhere in the same session), and both insights queries. No money moves, so balances are untouched.

Errors

Failures surface as a CapxulError on error / thrown from mutateAsync — for example when the request is not in a cancellable state.

Client method

This hook wraps client.account.requests.cancel(requestId) for the personal scope, or client.org(orgId).requests.cancel(requestId) for an org scope.

useCapxulCancelRequest

On this page