useCapxulApproveInboxRequest

Mutation hook that approves an inbox payment request — approving pays it, producing a Payment.

Approves a payment request from an actor scope's inbox. Approving pays: the mutation settles the requested amount to the issuer and resolves with the resulting Payment. List actionable items with useCapxulInbox; decline instead with useCapxulDeclineInboxRequest.

Import

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

Usage

"use client";

import type { InboxItem } from "@capxul/sdk";
import {
  capxulAccountScope,
  useCapxulApproveInboxRequest,
} from "@capxul/sdk-react";

function ApproveButton({ item }: { item: InboxItem }) {
  const approve = useCapxulApproveInboxRequest(capxulAccountScope);

  return (
    <button
      type="button"
      disabled={item.status !== "open" || approve.isPending}
      onClick={() => approve.mutate({ requestId: item.id })}
    >
      {approve.isPending
        ? "Paying…"
        : `Pay ${item.amount.value} ${item.amount.currency}`}
    </button>
  );
}

To approve from an organization's inbox — paying from the org treasury — scope the hook with capxulOrgScope(orgId) and gate the control on the org id being loaded.

Parameters

actor

CapxulActorScope | undefined — defaults to capxulAccountScope

Which actor approves (and pays). 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 an InboxApproveInput:

Prop

Type

timing is an optional timing clause; omitted means the payment is instant.

Return type

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

On success, data is the resulting Payment — id, status, amount, recipient (the request's issuer), timing, and attached 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

Approving settles money, so this mutation has the widest invalidation set in the family. For the acting scope only: the inbox, the requests list, the request's detail query, the address book, and both insights queries. Because the result is a Payment, it additionally invalidates money state — the payments list, the settled payment's detail, and the acting scope's balance: ["capxul", "accountBalance"] for the personal scope, or the org's treasury and account keys for an org scope.

Errors

Failures surface as a CapxulError on error / thrown from mutateAsync — for example when the request is no longer open, or the payment cannot be settled.

Client method

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

useCapxulApproveInboxRequest

On this page