Payment methods

Hooks for the wallet surface of a customer portal — list saved methods and set-default / detach them, preflight what a detach would break, capture a new method, and atomically swap an in-use default. Together they cover the “you can’t just delete the card that’s paying for things” flow safely. Every hook returns loading/error state — reads via isLoading: boolean, mutations via isPending: boolean — plus error: Error | null. See Introduction. The sections below list each hook’s specific returns.

usePaymentMethods

Loads the customer’s saved payment methods and exposes the two write actions a wallet UI needs: setDefault(id) and detach(id). Both invalidate the customer scope on success so the list re-renders. Takes no arguments; the customer comes from <UnitPayProvider> context. Returns

paymentMethods — PaymentMethod[] — the customer’s saved methods, or [] while loading or when none exist. Card fields (cardLast4, cardBrand, expMonth, expYear) are null for non-card types.
setDefault(paymentMethodId) — (id: string) => Promise<void> — points the customer default at this method. Invalidates the customer scope on success.
detach(paymentMethodId) — (id: string) => Promise<void> — removes the method. Invalidates the customer scope on success. Throws PmInUseError when the method is a default still powering an active sub or auto-topup rule (see the warning below).
isActing — boolean — true while a setDefault or detach mutation is in flight.

import { usePaymentMethods } from '@unitpay/react';

export default function Wallet() {
  const { paymentMethods, setDefault, detach, isLoading, isActing } = usePaymentMethods();

  if (isLoading) return <p>Loading…</p>;

  return (
    <ul>
      {paymentMethods.map((pm) => (
        <li key={pm.id}>
          {pm.cardBrand} •••• {pm.cardLast4}
          <button onClick={() => setDefault(pm.id)} disabled={isActing}>Make default</button>
          <button onClick={() => detach(pm.id)} disabled={isActing}>Remove</button>
        </li>
      ))}
    </ul>
  );
}

detach() throws PmInUseError when the method is the customer default and is still powering an active subscription or auto-topup rule (server 409 pm_in_use). The error carries paymentMethodId, activeSubscriptionIds, autoTopupAccountIds, and requestId from error.details — render the block reason and route the user to the replace flow. Preflight it with usePaymentMethodDependencies so you never show a “Remove” button that’s doomed to throw.

import { usePaymentMethods, PmInUseError } from '@unitpay/react';

async function remove(detach: (id: string) => Promise<void>, id: string) {
  try {
    await detach(id);
  } catch (e) {
    if (e instanceof PmInUseError) {
      // e.activeSubscriptionIds / e.autoTopupAccountIds → offer the replace flow.
      console.warn('Still in use:', e.activeSubscriptionIds);
      return;
    }
    throw e;
  }
}

Show PaymentMethod object

{
  "id": "pm_01j9x...",
  "customerId": "cus_01ktxbxs2re8nsdfmzxw0gh988",
  "organizationId": "org_01j9x...",
  "paymentProviderId": "psp_01j9x...",
  "providerMethodId": "pm_1Pabc...",
  "type": "card",
  "status": "active",
  "cardLast4": "4242",
  "cardBrand": "visa",
  "expMonth": 12,
  "expYear": 2028,
  "createdAt": "2026-01-04T10:00:00.000Z",
  "updatedAt": "2026-06-20T08:15:00.000Z"
}

usePaymentMethodDependencies

The preflight query for a “remove card” confirmation modal. It returns whether the method is the customer default and, if so, the active subscriptions and auto-topup credit accounts that a detach would orphan. data.blocksDetach mirrors the server-side guardrail — when true, route the user to the replace flow instead of letting them click “Delete”. Parameters

string

required

The method to inspect. The query is disabled while this is null / undefined.

boolean

When false, the query is disabled — useful for a modal that fetches on open (enabled: isOpen). Defaults to true.

Returns — a TanStack UseQueryResult<PaymentMethodDependencies, Error> (short staleTime of 10s, because dependency state changes whenever subs / auto-topup rules change). data once loaded is PaymentMethodDependencies:

paymentMethodId string
isDefault boolean — whether this is the customer default.
blocksDetach boolean — true when detaching would orphan an active sub or auto-topup rule.
activeSubscriptions — Array<{ id, status, planId, collectionMethod, currentBillingPeriodEnd }>.
autoTopupAccounts — Array<{ id, creditCurrencyId, autoTopupThreshold, autoTopupAmount, autoTopupPackageId }>.

import { usePaymentMethodDependencies } from '@unitpay/react';

export default function ConfirmDeletePM({
  paymentMethodId,
  isOpen,
}: {
  paymentMethodId: string;
  isOpen: boolean;
}) {
  const { data, isLoading } = usePaymentMethodDependencies(paymentMethodId, {
    enabled: isOpen,
  });

  if (isLoading || !data) return <p>Checking…</p>;

  if (data.blocksDetach) {
    return (
      <p>
        This card powers {data.activeSubscriptions.length} subscription(s) and{' '}
        {data.autoTopupAccounts.length} auto-topup rule(s). Replace it instead.
      </p>
    );
  }

  return <button>Delete card</button>;
}

Show PaymentMethodDependencies object

{
  "paymentMethodId": "pm_01j9x...",
  "isDefault": true,
  "blocksDetach": true,
  "activeSubscriptions": [
    {
      "id": "sub_01k2x6...",
      "status": "active",
      "planId": "plan_01k2x5...",
      "collectionMethod": "charge_automatically",
      "currentBillingPeriodEnd": "2026-07-31T23:59:59.999Z"
    }
  ],
  "autoTopupAccounts": [
    {
      "id": "ca_01k2x9...",
      "creditCurrencyId": "ccur_01k2x4...",
      "autoTopupThreshold": 1000,
      "autoTopupAmount": 5000,
      "autoTopupPackageId": "pkg_01k2x3..."
    }
  ]
}

useSetupPaymentMethod

Mutation that captures a new payment method via a PSP SetupIntent. It always resolves to a requires_form SettleOutcome — the server mints a SetupIntent and returns the PSP client envelope, which you mount in <PaymentForm mode="save_only">. After the customer completes setup and the PSP webhook attaches the method, the payment-methods cache is invalidated so the next render shows it. Parameters

HandleSettlementOptions

Settlement callbacks dispatched after the mutation resolves — wire onRequiresForm to mount the inline form. See the Settlement model.

The setupPaymentMethod(input?) alias accepts an optional input:

string

Where to send the customer after a successful hosted-mode setup.

string

Where to send the customer if they abandon a hosted-mode setup.

'embedded' | 'hosted'

Whether to render the form inline (embedded) or redirect to the PSP-hosted page (hosted).

Returns — a TanStack UseMutationResult extended with setupPaymentMethod(input?), which triggers the SetupIntent and resolves to a requires_form outcome whose client.token is the Stripe Elements clientSecret.

import { useSetupPaymentMethod } from '@unitpay/react';
import { useState } from 'react';

export default function AddCard() {
  const [clientSecret, setClientSecret] = useState<string | null>(null);

  const { setupPaymentMethod, isPending } = useSetupPaymentMethod({
    onRequiresForm: (result) => setClientSecret(result.client.token),
  });

  if (clientSecret) {
    // Mount Stripe Elements in save-only mode with this client secret.
    return <PaymentForm mode="save_only" clientSecret={clientSecret} />;
  }

  return (
    <button onClick={() => setupPaymentMethod()} disabled={isPending}>
      {isPending ? 'Starting…' : 'Add a card'}
    </button>
  );
}

useReplacePaymentMethod

Mutation that performs an atomic “swap A for B” — it flips the customer default to the new method and detaches the old one in one server transaction. It’s the resolution path when usePaymentMethodDependencies reports blocksDetach: the old default is still powering active subs / auto-topup rules, so you can’t just detach it. Parameters — the hook takes no arguments; the replacement pair goes to the replacePaymentMethod(input) alias:

string

required

The method being replaced — typically the customer’s current default.

string

required

The method to become the new default. Must already be attached and active (capture one first with useSetupPaymentMethod).

Returns — a TanStack UseMutationResult extended with replacePaymentMethod(input), which runs the swap and resolves to a ReplacePaymentMethodResult. On success it invalidates all customer-scoped queries (the PM list, default pointer, sub references). The result carries:

customerId string
oldPaymentMethodId string
newPaymentMethodId string
becameDefault boolean — true iff the default pointer actually moved this call.
clearedOldDefault boolean — true iff the old method was the default (and is now cleared).

import { useReplacePaymentMethod } from '@unitpay/react';

export default function SwapCard({ oldId, newId }: { oldId: string; newId: string }) {
  const { replacePaymentMethod, isPending } = useReplacePaymentMethod();

  return (
    <button
      disabled={isPending}
      onClick={async () => {
        const result = await replacePaymentMethod({
          oldPaymentMethodId: oldId,
          newPaymentMethodId: newId,
        });
        if (result.becameDefault) alert('Card replaced.');
      }}
    >
      {isPending ? 'Replacing…' : 'Replace card'}
    </button>
  );
}

Show ReplacePaymentMethodResult object

{
  "customerId": "cus_01ktxbxs2re8nsdfmzxw0gh988",
  "oldPaymentMethodId": "pm_01j9x...",
  "newPaymentMethodId": "pm_01k2xa...",
  "becameDefault": true,
  "clearedOldDefault": true
}

Invoices

Collect payment with usePayInvoice once a method is on file.

Settlement model

The requires_form outcome and client envelope behind card capture.

Error handling

The SDK error model and PmInUseError.

Customer

setupPayment() on useCustomer mints a hosted-link alternative.

Overview

Building blocks

Payment methods

usePaymentMethods

usePaymentMethodDependencies

useSetupPaymentMethod

useReplacePaymentMethod

See also

Invoices

Settlement model

Error handling

Customer

​usePaymentMethods

​usePaymentMethodDependencies

​useSetupPaymentMethod

​useReplacePaymentMethod

​See also

Invoices

Settlement model

Error handling

Customer

usePaymentMethods

usePaymentMethodDependencies

useSetupPaymentMethod

useReplacePaymentMethod

See also