Managing cards

An Account holds funds and can own multiple 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 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 controls the artwork printed on the Physical Card and its carrier. See Physical cards for artwork and fulfillment.
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 controls the artwork displayed in a wallet. See Digital wallets for artwork and tokenization.

An Entity 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. The Account still funds the Card.

For displaying the Card’s sensitive details in your application, see Card Elements.

Card and Physical Card status

A Card’s status controls whether we approve new purchases made with its credentials. When the Card is disabled, we decline new purchases made with its card number, Physical Cards, and Digital Wallet Tokens, without changing their own statuses. Reactivating the Card allows them to be used again.

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 only to purchases made with that Physical Card, and an active Physical Card works only while its Card is also active. Disabling or canceling a Physical Card leaves the Card’s number, its other Physical Cards, and its Digital Wallet Tokens usable.

New Physical Cards start disabled, and delivery does not activate them. Canceling a Physical Card stops its shipment only while the shipment is still pending.

These status changes govern new authorizations. They do not reverse earlier authorizations or prevent their later settlement. See Card payment lifecycle for how authorized payments complete.

Freeze and unfreeze

To freeze all purchases on a Card, update the Card with status: disabled. To unfreeze it, set status: active. Unfreezing the Card does not activate Physical Cards that were already disabled.

To freeze only one Physical Card, update the 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 leaves its card number usable by anyone who copied it. When the credentials may be compromised, replace the Card as well:

Update the old Card with status: canceled. New purchases are blocked immediately, and its Physical Cards are canceled asynchronously.
Create a Card on the same Account, with replacement_for identifying the old Card and the reason lost or stolen. The new Card does not copy the old Card’s settings, so supply any you need.
Create a Physical Card against the new Card.
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.

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.

After receipt, activate the new Physical Card and cancel the damaged one.

Handle expiration

A Card expires four years after the month it was created. Physical Cards use the Card’s expiration date, so ordering another Physical Card does not extend it.

Cards are not automatically canceled or extended when they expire. Before a Card expires, either renew it to keep its card number, or replace it with a new Card.

Renew a Card

Renewing a Card gives it a new expiration date four years out and a new verification code. The Card keeps its card number, PIN, settings, and Digital Wallet Tokens, and merchants that have the Card on file are notified of the new expiration date.

Physical Cards that have already shipped are printed with the old expiration date and keep working until they are canceled. To give the cardholder a Physical Card that shows the new expiration date and verification code, create a Physical Card after renewing, activate it after receipt, and cancel the old one.

Replace a Card

To issue a new card number instead, create a Card with replacement_for, identifying the Card it replaces and the reason. Settings are not copied from the replaced Card.

With reason expiring, merchants that have the replaced Card on file are notified of the new Card, and the replaced Card’s Digital Wallet Tokens move to the new Card. The reasons lost, stolen, and fraud do neither, so a compromised card number is not passed on to merchants or wallets.

Replacing a Card does not cancel it. Once the cardholder has switched to the new Card, cancel the replaced one. Create a Physical Card against the new Card if the cardholder needs one.

Webhooks

Subscribe to these Events to keep your card management interface current:

card.created and card.updated for Card creation and changes.
physical_card.created and physical_card.updated for individual Physical Cards. Watch these separately from Card updates because the cancellation cascade is asynchronous.
digital_wallet_token.created and digital_wallet_token.updated for Digital Wallet Tokens. 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.