Credit Cards

Lists an organization's credit cards one page at a time, with a "Show my cards" toggle and per-row Activate.

Lists an organization's credit cards one page at a time, with a "Show my cards" toggle and per-row Activate. Selecting a row opens the card's details in a side sheet. There is no built-in credit issuance flow, so Create card appears only when you supply onCreateCard.

Quick Start

import { CreditCardsWidget } from '@tesouro/embedded-components-react';

export function CreditCardsPage() {
  return <CreditCardsWidget />;
}

Auth props are inherited from a parent RefreshingRootWidgetProvider or WidgetProvider. For debit cards, use DebitCardsWidget, which also has the built-in create sheet.

Behaviour

Create card shows only when the token holds credit_card:issue:org and you pass onCreateCard, such as onCreateCard={() => setCreateOpen(true)}.
Activate on a row shows only for cards awaiting activation, and only with credit_card:activate:org and onActivateCard. Without the callback, the cardholder can still activate from the details panel (see CardDetailsWidget).
On credit, the activation form's expiry and security code are checked in the browser only, so a well-formed guess activates the card. Don't treat activation as proof the cardholder holds the card.
A token without credit_card:read:org shows the list's empty state, not an error.
The list renders no heading of its own; put yours in headerStart. If both card lists share a page, give each its own heading.
The widget reads no URL or router. In uncontrolled mode the open card is cleared when the organization or user changes; in controlled mode the widget calls onSelectedCardIdChange(null) instead. Paging doesn't close the open card.

Props

Prop	Type	Default	Description
`pagination`Controlled	`{ paginationToken?, pageSize? }`	`undefined`	Controlled cursor and page size. Supply with `onPaginationChange`.
`defaultPagination`Uncontrolled	`{ paginationToken?, pageSize? }`	First page, 10	Initial cursor and page size when uncontrolled. Ignored when `pagination` is supplied.
`onPaginationChange`Event	`(pagination: CardsPagination) => void` `(pagination: CardsPagination) => void`	`undefined`	Called on every page or page-size change. Persist the whole object, not the token alone.
`selectedCardId`Controlled	`string \| null`	`undefined`	Controlled selection of the card whose details panel is open. `null` closes it; omit for uncontrolled.
`defaultSelectedCardId`Uncontrolled	`string \| null`	`undefined`	Initial selection when uncontrolled. Ignored when `selectedCardId` is supplied.
`onSelectedCardIdChange`Event	`(cardId: string \| null) => void`	`undefined`	Fires whenever the open card changes, including on close (`null`). Supplying it does not change what renders.
`bankLogoSrc`	`string`	`undefined`	Bank logo for the details panel's card face. Omit it and the face renders no logo.
`bankLogoAlt`	`string`	`undefined`	Alt text for `bankLogoSrc`.
`onCreateCard`Event	`() => void`	`undefined`	Your own Create card handler. Required for the button to render.
`headerStart`Slot	`ReactNode`	`undefined`	Your markup for the start of the header row, beside Create card. Put your heading here; you choose the element and level.
`onActivateCard`Event	`(cardId: string) => void`	`undefined`	Called when a row's Activate button is clicked. Omit it and the button isn't rendered.

Label overrides

Prop	Type	Default	Description
`labels`Labels	`PartialDeep<CardsLabels>`	English labels	Overrides the list screen's copy, including the details sheet's screen-reader name under `detailsSheet`.
`featureLabels`Labels	`PartialDeep<CardsFeatureLabels>`	English labels	Overrides status and form-factor vocabulary, the empty-cell placeholder and name fallbacks.
`cardDetailsLabels`Labels	`PartialDeep<CardDetailsWidgetLabels>` `PartialDeep<CardDetailsWidgetLabels>`	English labels	Label overrides forwarded into the details panel.
`cardDetailsFeatureLabels`Labels	`PartialDeep<CardDetailsFeatureLabels>` `PartialDeep<CardDetailsFeatureLabels>`	English labels	Overrides the details panel's status, form-factor and program copy and its copy-success toast.
`cardDetailsActivateLabels`Labels	`PartialDeep<ActivateCardPanelLabels>` `PartialDeep<ActivateCardPanelLabels>`	English labels	Overrides the copy of the Activate Card form the details panel opens.

Examples

Controlled with a URL query param

Bind the selection to your router. A card deep-linked this way has its panel open on first paint.

<CreditCardsWidget
  selectedCardId={searchParams.get('cardId')}
  onSelectedCardIdChange={(cardId) =>
    router.push(cardId ? `${pathname}?cardId=${cardId}` : pathname)
  }
/>

Your own details route instead of the built-in panel

Pin the selection to null and navigate from the callback. Row clicks are still reported, and the panel never opens.

<CreditCardsWidget
  selectedCardId={null}
  onSelectedCardIdChange={(cardId) => {
    if (cardId) router.push(`/credit-cards/${cardId}`);
  }}
/>

TypeScript

import type {
  ActivateCardPanelLabels,
  CardDetailsFeatureLabels,
  CardDetailsWidgetLabels,
  CardsFeatureLabels,
  CardsLabels,
  CardsPagination,
  CreditCardsWidgetProps,
} from '@tesouro/embedded-components-react';

CardsLabels, CardsFeatureLabels and CardsPagination are shared with DebitCardsWidget.

Credit Cards

Quick Start

Behaviour

Props

Widget props

Examples

Controlled with a URL query param

Your own details route instead of the built-in panel

TypeScript

On this page

Credit Cards

Auth / scope props (shared)

On this page