useCapxulAddDestination
Mutation hook for saving a payout destination — masked bank, mobile-money, or wallet details tied to a counterparty.
Saves a destination for a counterparty — a bank account, mobile-money
number, or wallet that can later be selected by id in
useCapxulPayout. List saved
destinations with
useCapxulDestinations.
Stored metadata vs. settlement
All three destination kinds can be stored, but only wallet
(external_account) destinations can be settled by
useCapxulPayout today. Saving a
bank or mobile-money destination models the counterparty; it does not enable
bank or mobile-money cash-out. See
Capability status.
Import
import { useCapxulAddDestination } from "@capxul/sdk-react";Usage
"use client";
import { useCapxulAddDestination } from "@capxul/sdk-react";
function AddBankDestination({ email }: { email: string }) {
const addDestination = useCapxulAddDestination();
return (
<button
disabled={addDestination.isPending}
onClick={() =>
addDestination.mutate({
target: { kind: "email", email },
kind: "bank_account",
label: "Main NGN account",
payload: {
accountHolderName: "Ada Obi",
bankName: "First Bank",
country: "NG",
currency: "NGN",
accountNumberLast4: "1234",
},
})
}
>
{addDestination.isPending ? "Saving…" : "Save destination"}
</button>
);
}Parameters
The hook itself takes no parameters. The mutation takes a
DestinationAddInput:
Prop
Type
target or ref names the counterparty the destination belongs to — one
of the two is required (INVALID_INPUT otherwise). Saving a destination also
records the counterparty in the acting entity's address book.
payload is validated by kind:
bank_account—accountHolderName,bankName,country(ISO-3166 alpha-2),currency(ISO-4217), andaccountNumberLast4(exactly four digits). Only the last four digits are ever stored.mobile_money—provider,country,currency, andphoneNumberLast4(exactly four digits).external_account(wallet) —network(must bebase-sepoliain the current alpha) and a0x+ 40-hexaddress.
label is optional and at most 120 characters. actor scopes the
destination to the personal account (default) or an organization; org actors
need spend authority in that org.
Return type
import { type UseCapxulAddDestinationReturn } from "@capxul/sdk-react";
// UseMutationResult<Destination, CapxulError, DestinationAddInput>On success, data is the saved Destination, including the opaque id to
pass to useCapxulPayout.
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 every destinations query (the
["capxul", "destinations"] prefix) and the acting entity's address book,
since adding a destination also records the counterparty there.
Errors
Failures surface as a CapxulError on error /
thrown from mutateAsync — INVALID_INPUT when neither target nor ref is
given, when the payload fails the kind-specific validation above, or when the
label is too long.
Client method
This hook wraps client.destinations.add(input) on the core SDK.