Skip to main content
This topic explains the different states of a card and its versions. The operational state of a card depends on both the card status and the version status.

​
Card Status

The card status (cardStatus) determines the state of the card by its ID (cardId). Each card has a unique identifier; the cardStatus defines the overall state of the card.

​
What is a card version?

A card can have several versions over its lifetime. A new version is created whenever the card’s credentials (its expiry date, CVV2/CVC2, and sometimes its PIN) need to change, without changing the card itself (its cardId). Renewal and reissue both do this; see the table below. Each version has its own status (INITIAL, ACTIVE_LIMITED, ACTIVE, or CLOSED), which tracks where that specific version is in its lifecycle: not yet usable, usable digitally only, fully usable, or superseded. Older versions aren’t discarded; they’re closed once a newer version takes over. Whether the card number (PAN) changes depends on why a new version is created. There are many possible reasons to reissue, renew, or replace a card; the table below shows a few common examples to make the pattern concrete: These are illustrative examples, not the full set of reasons a card might be reissued, renewed, or replaced. So renewal and reissue both keep the same card and the same PAN; they just introduce a new version of it, typically with a new expiry date and CVV2/CVC2. Replacement is different: it creates an entirely new card (new cardId, new PAN), which then has its own version(s). See Card Renewal, Reissue, Replacement for the full detail on each of these actions. The status of the version is what determines what the card can actually do, which is what the rest of this section covers.

​
Card Version Status

The status of each card version is indicated by cardVersionsStatus. The version status determines what a card can do when the card status is ACTIVE.

​
How a version moves between statuses

A new card version always starts in either INITIAL or ACTIVE_LIMITED, depending on the programme configuration. From there:
  • A version in INITIAL or ACTIVE_LIMITED can be activated and become ACTIVE.
  • A version in INITIAL, ACTIVE_LIMITED, or ACTIVE can become CLOSED.
  • A version cannot move from INITIAL to ACTIVE_LIMITED. ACTIVE_LIMITED is a starting state, not a transition target.
  • A CLOSED version cannot be reopened.
Whether a newly created card version starts in INITIAL or ACTIVE_LIMITED status is set at the programme level by Enfuce during customer onboarding. ACTIVE_LIMITED exists to support digital-first issuance: a cardholder can start using the card digitally, for example by adding it to a wallet or paying online with 3DS, before the physical card has been activated.

​
What each status allows

In ACTIVE_LIMITED status, e-commerce transactions are accepted only when the cardholder is authenticated with 3DS. Credentials on file transactions (for example recurring payments and subscriptions) are accepted, because they can only follow an earlier 3DS-authenticated transaction where the merchant stored the card details.

​
Moving to ACTIVE

Both INITIAL and ACTIVE_LIMITED versions can be activated to ACTIVE using the Activate Card Endpoint.

​
Reissue and renewal: version coexistence

Only one version can be ACTIVE at a time, and only one version can be ACTIVE_LIMITED at a time. These two limits are tracked independently, which is why an ACTIVE version and an ACTIVE_LIMITED version can temporarily coexist. This is intentional, and covers the reissue and renewal window:
  • The cardholder keeps using their current, ACTIVE physical card.
  • The newly issued version starts in ACTIVE_LIMITED status, so it can already be used digitally even though the physical card hasn’t arrived or been activated yet.
  • Once the new version is activated to ACTIVE, all previous versions are closed automatically.
If a card is reissued again while a version is already in ACTIVE_LIMITED status, the earlier ACTIVE_LIMITED version is closed and the new version takes over as ACTIVE_LIMITED. There is never more than one ACTIVE_LIMITED version at a time. Example: programme configured with ACTIVE_LIMITED as the default Example: programme configured with INITIAL as the default In both examples the cardholder is never left without a usable card. V1 stays ACTIVE and fully usable until the cardholder chooses to activate the new version. The difference is what the new version can already do before that happens. With ACTIVE_LIMITED, the new version can already be added to a digital wallet and used for 3DS-authenticated e-commerce ahead of activation, so a cardholder who adds it to their wallet early experiences no interruption when V1 later closes.

​
Other notes

  • An ACTIVE_LIMITED card version can still be replaced, for example if the card is compromised before the physical card has been activated.
  • A PIN can be set while a version is ACTIVE_LIMITED.
  • ACTIVE_LIMITED applies the same regardless of whether the card is physical or virtual-only. A virtual-only version can still move to ACTIVE.

​
Checking a version’s status and sequence number

Use the Get Card endpoint to see all of a card’s versions and their current state. The response includes a cardVersions array, ordered by sequence number ascending. Each entry has:
  • status: the version’s cardVersionsStatus (INITIAL, ACTIVE_LIMITED, ACTIVE, or CLOSED)
  • sequenceNumber: the version’s PAN sequence number (PSN), which uniquely identifies that version of the card
During a reissue or renewal window, cardVersions can contain one version with status ACTIVE and a newer one with status ACTIVE_LIMITED at the same time. Check each entry’s status individually rather than assuming the entry with the highest sequence number is the one currently usable. Both may be usable at once, for different transaction types.