Debit Cards

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

Part ofEmbedded Banking

Lists an organization's debit cards one page at a time, with a "Show my cards" toggle, Create card and per-row Activate. Selecting a row opens the card's details in a side sheet, and Create card opens the built-in debit issuance flow in the same sheet.

Quick Start

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

export function DebitCardsPage() {
  return <DebitCardsWidget />;
}

Auth props are inherited from a parent RefreshingRootWidgetProvider or WidgetProvider. For credit cards, use CreditCardsWidget.

Behaviour

Create card shows only when the token holds debit_card:issue:org and either you pass onCreateCard or the token also holds user:read:org and bank_account:read:org (which the built-in sheet needs). Passing onCreateCard replaces the built-in sheet.
After a successful create, View card opens the new card's details. It is omitted when the token lacks debit_card:read:org.
Activate on a row shows only for cards awaiting activation, and only with debit_card:activate:org and onActivateCard. Without the callback, the cardholder can still activate from the details panel (see CardDetailsWidget).
A token without debit_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, ignored when `cardArtSrc` is set. Omit both and the face renders no logo.
`bankLogoAlt`	`string`	`undefined`	Alt text for `bankLogoSrc`.
`cardArtSrc`	`string`	`undefined`	Card art for the create sheet and the details card face. Omitted, the sheet uses a neutral plastic.
`onCreateCard`Event	`() => void`	`undefined`	Your own Create card handler. When supplied, the built-in sheet doesn't open.
`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 sheets' screen-reader names under `detailsSheet` and `createSheet`.
`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.
`createCardLabels`Labels	`PartialDeep<CreateCardWidgetLabels>` `PartialDeep<CreateCardWidgetLabels>`	English labels	Label overrides forwarded into the built-in create sheet.
`createCardFeatureLabels`Labels	toast / untitled-funding overrides toast / untitled-funding overrides	English labels	Overrides the create sheet's toasts, untitled funding-account fallback and pending-activation success copy.

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.

<DebitCardsWidget
  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.

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

TypeScript

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

CardsLabels, CardsFeatureLabels and CardsPagination are shared with CreditCardsWidget.

Debit 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

Debit Cards

Auth / scope props (shared)

On this page