useCapxulDeclineInboxRequest

Declines a payment request from an actor scope's inbox. No money moves; the issuer sees the request move to declined. List actionable items with useCapxulInbox; pay instead with useCapxulApproveInboxRequest.

Import

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

Usage

"use client";

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

function DeclineButton({ requestId }: { requestId: string }) {
  const decline = useCapxulDeclineInboxRequest(capxulAccountScope);

  return (
    <button
      type="button"
      disabled={decline.isPending}
      onClick={() => decline.mutate(requestId)}
    >
      {decline.isPending ? "Declining…" : "Decline"}
    </button>
  );
}

To decline from an organization's inbox, scope the hook with capxulOrgScope(orgId) instead.

Parameters

actor

CapxulActorScope | undefined — defaults to capxulAccountScope

Which actor declines. 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) — the id of the InboxItem, as returned by useCapxulInbox.

Return type

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

On success, data is the updated InboxItem with status: "declined".

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 inbox, the requests list, the declined request's detail query, the address book, 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 no longer open.

Client method

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

useCapxulDeclineInboxRequest

On this page