# Managing cards

An [Account](/documentation/api/accounts) holds funds and can own multiple [Cards](/documentation/api/cards). A Card is the payment credential: a card number, expiration date, and verification code. Payments made with a Card draw on its Account.

Each Card can have several objects associated with it:

- [Physical Cards](/documentation/api/physical-cards) are physical payment cards issued against the Card. Several Physical Cards can share the same Card and its credentials, while each has its own activation and shipment state.
  - A [Physical Card Profile](/documentation/api/physical-card-profiles) controls the artwork printed on the Physical Card and its carrier. See [Physical cards](/documentation/card-art-physical-cards) for artwork and fulfillment.
- [Digital Wallet Tokens](/documentation/api/digital-wallet-tokens) are tokenized credentials associated with the Card for use in wallets such as Apple Pay and Google Pay. They belong to the Card, independently of any Physical Card.
  - A [Digital Card Profile](/documentation/api/digital-card-profiles) controls the artwork displayed in a wallet. See [Digital wallets](/documentation/card-art) for artwork and tokenization.

An [Entity](/documentation/entities) represents a person or business. A Card can belong to an Entity other than the Account holder, such as an employee spending from a business Account. Set `entity_id` when you need this association; it does not change the Account that funds the Card.

For displaying the Card’s sensitive details in your application, see [Embedded card component](/documentation/embedded-card-component).

## Card and Physical Card status

A Card’s status controls whether we approve new purchase authorizations against its credentials. When the Card is `active`, purchases can be approved, subject to the Account’s state, available funds, and authorization controls. When it is `disabled`, we decline new purchases made with the card number, any of its Physical Cards, or its Digital Wallet Tokens. Disabling the Card does not change those objects’ statuses. Reactivating it allows them to be used again, subject to their own statuses.

Setting a Card to `canceled` permanently blocks new purchases. We then cancel all of its Physical Cards asynchronously. A canceled Card cannot be reactivated.

A Physical Card’s status applies to authorizations identified as using that particular Physical Card. An `active` Physical Card can be used only while its Card is also active. A `disabled` Physical Card is declined at the point of sale, but the Card’s number, other active Physical Cards, and Digital Wallet Tokens remain usable. Setting a Physical Card to `canceled` makes that restriction permanent. Neither disabling nor canceling it changes the Card or the other objects.

New Physical Cards start disabled. Shipping and activation are separate: delivery does not activate a Physical Card. Canceling a Physical Card also cancels its shipment if the shipment is still `pending`. Once the shipment has progressed beyond that state, canceling the Physical Card does not stop fulfillment.

These status changes govern new authorizations. They do not reverse earlier authorizations or prevent their later settlement. See [Card payment lifecycle](/documentation/card-payment-lifecycle) for how authorized payments complete.

## Freeze and unfreeze

To freeze all purchases on a Card, [update the Card](/documentation/api/cards#update-a-card) with `status: disabled`. To unfreeze it, set `status: active`. Physical Cards that were already disabled remain disabled; unfreezing the Card does not activate them.

To freeze only one Physical Card, [update the Physical Card](/documentation/api/physical-cards#update-a-physical-card) with `status: disabled`. Set it back to `active` to unfreeze it. Use this same update to activate a newly delivered Physical Card after your cardholder confirms receipt.

## Replace a lost or stolen Physical Card

Canceling only the Physical Card blocks use of that Physical Card. It leaves the underlying card number usable, including a number copied from the lost card. When the credentials may be compromised, replace the Card as well:

1. Update the old Card with `status: canceled`. New purchases are blocked immediately, and its Physical Cards are canceled asynchronously.
2. [Create a Card](/documentation/api/cards#create-a-card) on the same Account. Supply the Entity association, billing address, authorization controls, and wallet configuration that should apply to the new Card; creating it does not copy the old Card’s settings.
3. [Create a Physical Card](/documentation/api/physical-cards#create-a-physical-card) against the new Card, providing the cardholder and shipment details.
4. Activate the new Physical Card after receipt. The cardholder must use the new credentials for future purchases and provision the new Card in their wallets. Creating a Card does not move Digital Wallet Tokens from the old Card.

## Reprint a damaged Physical Card

If the credentials remain secure, create another Physical Card against the existing Card. The new Physical Card uses the same credentials, so the cardholder can continue using the Card’s number and Digital Wallet Tokens while waiting for delivery. Creating it does not disable or cancel the damaged Physical Card.

After receipt, activate the new Physical Card and cancel the damaged one. This cancels only the old Physical Card; it does not replace the Card or extend its expiration date.

## Handle expiration

When we create a Card, we assign an expiration month matching the month of creation and an expiration year four years later. Read `expiration_month` and `expiration_year` on the Card when scheduling notices or planning issuance. Physical Cards use the Card’s expiration date; ordering another Physical Card does not extend it.

Cards are not automatically canceled when they expire. Use the Card Replacement API to replace a Card and send Account Updater updates to merchants. You can retain the existing card number or issue a new one.

## Webhooks

Subscribe to these [Events](/documentation/webhooks) to keep your card management interface current:

- `card.created` and `card.updated` for Card creation and changes, including status, billing address, Entity association, and PIN updates.
- `physical_card.created` and `physical_card.updated` for individual Physical Cards, including activation, cancellation, and shipment updates. Watch these separately from Card updates because the cancellation cascade is asynchronous.
- `digital_wallet_token.created` and `digital_wallet_token.updated` for wallet provisioning and token changes. A Card status change does not itself change the token’s status, so use both objects when determining whether wallet purchases can be approved.

Retrieve the object identified by each Event to refresh its current state. For purchase activity, use the payment webhooks described in [Card payment lifecycle](/documentation/card-payment-lifecycle).