Card Details

Part ofEmbedded Banking↗

Details for one credit or debit card: status, form factor, program, masked number, and copyable cardholder, nickname and billing-address rows. It renders panel content rather than its own drawer, so it fits on a page of your own or inside chrome you already have.

Quick Start

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

export function CardPage({ cardId }: { cardId: string }) {
  return <CardDetailsWidget cardId={cardId} cardProgram="credit" />;
}

cardId and cardProgram are both required. Under RefreshingRootWidgetProvider or WidgetProvider the auth props are inherited. If you only need details next to a card list, CardsWidget already composes this panel in its own sheet.

Behaviour

• Program: cardProgram must be exactly 'credit' or 'debit'. Any other value, including undefined, fetches nothing and shows the error screen with no retry, plus a console message. If you resolve the program asynchronously, wait for it before mounting.
• Debit-only features: reveal, lock, rename, billing address and card controls appear only with cardProgram="debit". A credit panel never shows them, so don't plan a credit layout around them.
• Reveal: View card fetches the number, expiry and security code only when pressed, and keeps nothing after Hide, close or a card switch. A refused (403) reveal shows featureLabels.revealNotPermittedDescription. It isn't offered on a card pending activation.
• Lock: needs the debit_card:lock:org scope, otherwise the control is hidden. It isn't offered on a physical card pending activation or a closed card. A locked card can still be revealed.
• Rename: needs debit_card:issue:org, the same scope that issues cards. It isn't offered on a closed card, and a blank name can't be saved.
• Billing address and card controls (allowed categories, spend limit, per-transaction max) show when the card has them and are omitted otherwise. The address omits the country, and limits scoped to one merchant or category aren't shown.
• Missing nickname or cardholder: the row shows labels.fields.emptyValue (shared by both rows) with no copy button, and the title falls back to labels.header.untitledCard.
• Activation: Activate Card appears only for a PHYSICAL card in PENDING_ACTIVATION, when the token holds credit_card:activate:org or debit_card:activate:org for that program and the viewer is the card's own cardholder. On a credit card the expiry and security code are only checked for format, so don't treat credit activation as proof the cardholder has the card. Setting a PIN isn't part of the flow.
• Closing: the widget reads no URL or router; you own navigation through onClose. Omit it on a standalone page. Pass it inside your own drawer or dialog, and hide your chrome's close button. On the activation success screen, Done calls onClose (no Done without it), and the X returns to the details. There is no activation callback, so read the card's status if you need to know.
• Updates: after a lock, rename or activation, the card and any list behind it refresh themselves. Nothing to wire.
• Not found appears for any 404, which covers both a card that doesn't exist and one the reader can't access.
• Copy does nothing when the host page blocks clipboard access.
• Nesting: inside another widget's provider, leave the auth props off so it inherits. Passing baseUrl or widgetToken adds a redundant init request each time it opens.

Props

Widget props

Nested label groups merge one group at a time, so overriding one string keeps the rest of its group.

Examples

Inside your own drawer

<Drawer open={Boolean(cardId)} onOpenChange={setOpen}>
  <DrawerContent>
    <CardDetailsWidget
      cardId={cardId}
      cardProgram="debit"
      onClose={() => setOpen(false)}
    />
  </DrawerContent>
</Drawer>

The widget imposes no width; the surface around it owns that.

TypeScript

import type {
  ActivateCardPanelLabels,
  CardDetailsFeatureLabels,
  CardDetailsWidgetLabels,
  CardDetailsWidgetProps,
} from '@tesouro/embedded-components-react';