Cards React integration

This guide covers the complete cardholder flow. First, check for an existing card. If none exists, use useSignUpForCard with SignUpForCardView to onboard the cardholder. Then, render CardSummaryView to display and manage the card. These APIs are exported from @privy-io/react-auth/cards and must be used within PrivyProvider. Before continuing, complete the cards setup and configure embedded wallets for your app. For an approved Earn-backed card program, follow Spend from vault balances. The same hooks and components handle vault-share approval and available balances.

useSignUpForCard works for any authenticated Privy user, including users authenticated with custom JWT authentication.

Install and import the SDK

Card prebuilt components require @privy-io/react-auth version 3.40.0 or later.

Install the React SDK:

npm install @privy-io/react-auth

Import usePrivy from the main entrypoint. Import the card hooks and components from the /cards entrypoint.

import {usePrivy} from '@privy-io/react-auth';
import {
  CardSummaryView,
  SignUpForCardView,
  useGetCardsForUser,
  useSignUpForCard
} from '@privy-io/react-auth/cards';

Get the funding wallet

The signUp method takes the Privy wallet ID, not the wallet address. Read it from the authenticated user’s linkedAccounts. The following helper returns the ID of an embedded EVM wallet:

import type {LinkedAccountWithMetadata, WalletWithMetadata} from '@privy-io/react-auth';

const getCardWalletId = (accounts: LinkedAccountWithMetadata[]) =>
  accounts.find(
    (x): x is WalletWithMetadata =>
      x.type === 'wallet' &&
      x.walletClientType === 'privy' &&
      x.connectorType === 'embedded' &&
      x.chainType === 'ethereum'
  )?.id;

For a Solana-funded card, select an embedded wallet with chainType === 'solana' instead.

Choose the card asset

Each card spends one stablecoin from its funding wallet. Pass the stablecoin’s asset ID as asset when calling signUp. Every supported chain has a default asset, and some chains also accept a second one.

Network	Chain ID	Default asset	Also accepts
Tempo	`eip155:4217`	`'ousd'`	`'pathusd'`
Ethereum	`eip155:1`	`'ousd'`	`'usdc'`
Base	`eip155:8453`	`'ousd'`	`'usdc'`
Solana	`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`	`'ousd'`	`'usdc'`
Optimism	`eip155:10`	`'usdc'`	None
Polygon	`eip155:137`	`'usdc'`	None
Arbitrum	`eip155:42161`	`'usdc'`	None
Avalanche C-Chain	`eip155:43114`	`'usdc'`	None
Tempo Moderato (sandbox)	`eip155:42431`	`'ousd'`	`'pathusd'`

The other sandbox networks, such as Base Sepolia and Solana devnet, accept only 'usdc'. To test OUSD cards in sandbox, use Tempo Moderato.

OUSD cards require @privy-io/react-auth version 3.49.1 or later.

A wallet can hold one open card per chain and asset. For example, the same Tempo wallet can fund both a PathUSD card and an OUSD card. signUp rejects when asset is not available on chainId.

Add the card flow

Use isOpen to mount the container for SignUpForCardView. Connect the container’s close action to close. The view renders the onboarding steps using the options passed to signUp. The promise returns the new card ID after signup completes and rejects if the flow does not complete. This sandbox example uses Tempo Moderato and OUSD. To issue a PathUSD card instead, set CARD_ASSET to 'pathusd'. The SDK supplies built-in stablecoin and Bridge spend-approval targets for supported sandbox networks.

'use client';

import {useState} from 'react';
import {
  usePrivy,
  type LinkedAccountWithMetadata,
  type WalletWithMetadata
} from '@privy-io/react-auth';
import {
  CardSummaryView,
  SignUpForCardView,
  useGetCardsForUser,
  useSignUpForCard
} from '@privy-io/react-auth/cards';

const getCardWalletId = (accounts: LinkedAccountWithMetadata[]) =>
  accounts.find(
    (x): x is WalletWithMetadata =>
      x.type === 'wallet' &&
      x.walletClientType === 'privy' &&
      x.connectorType === 'embedded' &&
      x.chainType === 'ethereum'
  )?.id;

const CARD_CHAIN_ID = 'eip155:42431'; // Tempo Moderato
const CARD_ASSET = 'ousd'; // or 'pathusd'

const Cards = () => {
  const {user} = usePrivy();
  const {signUp, close, isOpen} = useSignUpForCard();
  const {getCardsForUser} = useGetCardsForUser();
  const [cardId, setCardId] = useState<string | null>(null);
  const [error, setError] = useState<string | null>(null);
  const walletId = getCardWalletId(user?.linkedAccounts ?? []);

  const openCard = async () => {
    if (!walletId) return;
    setError(null);

    try {
      const {data} = await getCardsForUser({environment: 'sandbox', limit: 20});
      const existing = data.find(
        (x) =>
          x.wallet_id === walletId &&
          x.chain_id === CARD_CHAIN_ID &&
          x.asset === CARD_ASSET &&
          (x.status === 'active' || x.status === 'inactive')
      );

      if (existing) {
        setCardId(existing.id);
        return;
      }

      const {id} = await signUp({
        environment: 'sandbox',
        walletId,
        chainId: CARD_CHAIN_ID,
        asset: CARD_ASSET
      });
      setCardId(id);
    } catch (error) {
      setError(error instanceof Error ? error.message : 'Could not open card');
    }
  };

  return (
    <>
      {error && <p role="alert">{error}</p>}

      {!cardId && (
        <button disabled={!walletId} onClick={() => void openCard()}>
          Open card
        </button>
      )}

      {isOpen && (
        <aside aria-label="Card signup">
          <button type="button" onClick={close}>
            Close
          </button>
          <SignUpForCardView />
        </aside>
      )}

      {cardId && <CardSummaryView key={cardId} cardId={cardId} environment="sandbox" />}
    </>
  );
};

The example checks for an open card before starting signup. A failed list request stops the flow. The cardholder can use the same button to retry. The example checks the newest 20 cards. Apps with more records should use the pagination helper below before starting signup. Replace the aside with the modal or side panel that fits the app. Keep SignUpForCardView mounted while isOpen is true. CardSummaryView uses cardId to load the card, balance, activity, and statements. It also handles card-detail reveal, wallet provisioning, freezing, replacement, and cancellation.

Find the user’s existing cards

The signup promise only returns a card ID during the current page session. To support returning users, use useGetCardsForUser to fetch the authenticated user’s cards. getCardsForUser returns one page for a single environment, ordered newest first. Results include canceled cards. The default page size is 5 and the maximum is 20; pass each next_cursor back as cursor until it returns null.

const {getCardsForUser} = useGetCardsForUser();

const getAllCards = async (environment: 'sandbox' | 'production') => {
  const first = await getCardsForUser({environment, limit: 20});
  const cards = [...first.data];
  let cursor = first.next_cursor;

  while (cursor) {
    const page = await getCardsForUser({environment, limit: 20, cursor});
    cards.push(...page.data);
    cursor = page.next_cursor;
  }

  return cards;
};

Call the helper after the user authenticates. Keep the full result if your app lists card history, or select the newest open card to pass to CardSummaryView:

const cards = await getAllCards('sandbox');
const existing = cards.find(
  (x) =>
    x.wallet_id === wallet.id &&
    x.chain_id === chainId &&
    x.asset === asset &&
    (x.status === 'active' || x.status === 'inactive')
);

setCardId(existing?.id ?? null);

Handle card states

The list response can include these card states:

active: The card is open and can spend. Pass it to CardSummaryView.
inactive: The card is frozen but remains open. Pass it to CardSummaryView to allow unfreezing.
canceled: The card is permanently closed. Keep it for history, but do not select it for management.
replaced: A newer card replaced this closed card. Select the newer active or inactive card instead.

Cards are ordered newest first. Select the first active or inactive card that matches the funding wallet, chain, and asset.

Do not treat a failed getCardsForUser request as an empty list. Show the error and retry the request. Offer signup only after a successful request returns no open cards.

Configure production spend approval

Sandbox uses built-in targets for Ethereum Sepolia, OP Sepolia, Polygon Amoy, Base Sepolia, Arbitrum Sepolia, Avalanche Fuji, Tempo Moderato, and Solana devnet. On Tempo Moderato, the built-in target approves OUSD when asset is 'ousd' and PathUSD otherwise. Production requires the spend-approval target for the mainnet chain behind the app’s Bridge integration. Pass the target that a Privy account manager provides. Do not guess or hardcode another integration’s spender or merchant ID: the card can be issued but cannot spend if its wallet approves the wrong target. For an OUSD card, set stablecoinAddress to the OUSD contract on the card’s chain, or to the OUSD mint on Solana:

Network	OUSD address
Tempo	`0x20c0000000000000000000006a37DA5C996874BE`
Ethereum	`0x9f6F3991D525015a6F8CaF062C83b62fD3AC4436`
Base	`0xB2000000000000000000002fEb517dFeC7415344`
Solana	`ousd2mJsPEckLHcSCDxyKD7NDGARZcfLbDZkKiatYHB`

The Solana OUSD mint uses the Token-2022 program. The SDK derives the token account and builds the approval under Token-2022 automatically, so no extra configuration is needed.

EVM
Solana

Pass the stablecoin contract and Bridge spender for the card’s chain:

const openProductionSignUp = async () => {
  const {id} = await signUp({
    environment: 'production',
    walletId: wallet.id,
    chainId: 'eip155:4217',
    asset: 'pathusd', // or 'ousd'
    spendApproval: {
      stablecoinAddress: process.env.NEXT_PUBLIC_CARD_STABLECOIN_ADDRESS!,
      spenderAddress: process.env.NEXT_PUBLIC_CARD_SPENDER_ADDRESS!,
    },
  });
  setCardId(id);
};

Pass the stablecoin mint, Bridge card program, and merchant ID:

const openProductionSignUp = async () => {
  const {id} = await signUp({
    environment: 'production',
    walletId: wallet.id,
    chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
    asset: 'usdc', // or 'ousd'
    spendApproval: {
      stablecoinAddress: process.env.NEXT_PUBLIC_CARD_STABLECOIN_ADDRESS!,
      programId: process.env.NEXT_PUBLIC_CARD_PROGRAM_ID!,
      merchantId: process.env.NEXT_PUBLIC_CARD_MERCHANT_ID!,
    },
  });
  setCardId(id);
};

The environment option determines which configured card ledger the flow uses. Sandbox does not accept a caller-supplied spendApproval; production requires one.

API reference

`useGetCardsForUser`

useGetCardsForUser() returns a getCardsForUser method for the authenticated user:

const {getCardsForUser} = useGetCardsForUser();

getCardsForUser(options) returns a page with the user’s cards in data and the next page cursor in next_cursor.

Option	Type	Description
`environment`	`'sandbox' \| 'production'`	Card ledger to query.
`limit`	`number`	Optional page size from 1 to 20. Defaults to 5.
`cursor`	`string`	Optional cursor returned as `next_cursor` by the previous page.

`useSignUpForCard`

useSignUpForCard() returns the signUp and close methods and the isOpen state:

const {signUp, close, isOpen} = useSignUpForCard();

signUp(options) returns Promise<{id: string}>. Only one card signup can be active at a time; starting another before the first finishes rejects with an error. isOpen is true while signup is in progress. Use it to control the container that mounts SignUpForCardView. Call close() when the user dismisses that container. Closing before a card exists rejects the pending signUp promise.

Option	Type	Description
`environment`	`'sandbox' \| 'production'`	Card ledger to use.
`walletId`	`string`	Privy ID of the embedded wallet that funds the card.
`chainId`	`string`	CAIP-2 chain ID for the funding wallet.
`asset`	`'usdc' \| 'pathusd' \| 'ousd'`	Stablecoin the card spends. Must be available on `chainId`. See Choose the card asset.
`spendApproval`	`DevSpendApprovalTarget`	Required in production and unavailable in sandbox. Shape depends on whether `chainId` is EVM or Solana.

DevSpendApprovalTarget is a union of the EVM and Solana target shapes:

type EvmDevSpendApprovalTarget = {
  stablecoinAddress: string;
  spenderAddress: string;
};

type SvmDevSpendApprovalTarget = {
  stablecoinAddress: string;
  programId: string;
  merchantId: number | string | bigint;
};

type DevSpendApprovalTarget = EvmDevSpendApprovalTarget | SvmDevSpendApprovalTarget;

For EVM chains, spenderAddress identifies the Bridge contract approved to spend the stablecoin. For Solana, programId and merchantId identify the Bridge delegate.

`SignUpForCardView`

SignUpForCardView takes no props. Mount one instance within PrivyProvider while isOpen is true. The hook controls its options and completion state. The view handles disclosures, bank and provider terms, KYC, card creation, and the wallet spend approval.

`CardSummaryView`

Prop	Type	Description
`cardId`	`string`	Privy card ID to display.
`environment`	`'sandbox' \| 'production'`	Card ledger that contains the card.
`onClose`	`() => void`	Optional. Called when the user closes the view.

Always pass the same environment used to create the card. Cards are scoped by app, user, and environment, so the other environment cannot load the card.

Cards

Prebuilt components

API integration

Cards React integration

Install and import the SDK

Get the funding wallet

Choose the card asset

Add the card flow

Find the user’s existing cards

Handle card states

Configure production spend approval

API reference

`useGetCardsForUser`

`useSignUpForCard`

`SignUpForCardView`

`CardSummaryView`

​Install and import the SDK

​Get the funding wallet

​Choose the card asset

​Add the card flow

​Find the user’s existing cards

​Handle card states

​Configure production spend approval

​API reference

​useGetCardsForUser

​useSignUpForCard

​SignUpForCardView

​CardSummaryView

Install and import the SDK

Get the funding wallet

Choose the card asset

Add the card flow

Find the user’s existing cards

Handle card states

Configure production spend approval

API reference

`useGetCardsForUser`

`useSignUpForCard`

`SignUpForCardView`

`CardSummaryView`