Card lifecycle management

Card lifecycle managementCard Lifecycle Management The set of in-app card operations Apple and Mastercard expect an issuer app to surface so cardholders can self-serve without leaving the app. Typical operations: view card number / CVV / PIN, lock and unlock, freeze and unfreeze, replace, report lost or stolen, view balance, and view transactions. Issuer apps that omit any of these are flagged at lab certification. (CLM) covers everything that happens to a card after it's created — keeping it usable, pausing it temporarily, replacing it when something goes wrong, and ending its life when it's no longer needed.

Every managed cardManaged Card A payment card (virtual or physical) that can be created and managed through the Weavr platform. Cards can operate in prepaid mode (with their own balance) or debit mode (linked to a managed account). All cards must be assigned to a card assignee who is an Authorised User. has one of three states at any time:

State	Meaning
ACTIVE	The card can be used in transactions.
BLOCKED	The card is temporarily unusable. Funds are frozen. A blockedReason indicates why.
DESTROYED	The card is permanently terminated. A destroyedReason indicates why. Terminal — destroyed cards cannot be reused.

BLOCKED and DESTROYED carry a sub-reason that records what triggered the transition:

• blockedReason — USER, SYSTEM, or LOST
• destroyedReason — USER, SYSTEM, LOST, STOLEN, EXPIRED, or COMPROMISED

State machine

Pending activation

Physical cardsPhysical Card A payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use. are shipped inactive and cannot be used until the card assigneeCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users. runs the activation flow. The API state during this period is reported as BLOCKED. Virtual cardsVirtual Card A payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. skip this step and start as ACTIVE.

Transitions you control

Transition	Endpoint	Notes
Activate a physical cardPhysical Card A payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use.	Activate	Required after upgrade and shipment.
Pause a card	Block	Sets blockedReason to USER. Funds are frozen.
Resume a card	Unblock	Only works if blockedReason is USER.
Report lost	Report lost	Blocks the card with blockedReason of LOST. Cannot be unblocked.
Report stolen	Report stolen	Destroys the card immediately with destroyedReason of STOLEN.
Replace lost or stolen card	Replace lost or stolen	Issues a new physical cardPhysical Card A payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use. and transfers the balance.
Replace damaged card	Replace damaged	Keeps the same card number; the original card stays usable for online purchases until then.
Renew a card	Renewals	Configurable per card profileProfile A template defining the configuration for one type of object — corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type.. Triggered automatically before expiry.
Permanently remove a card	Remove	Card must be empty. Sets destroyedReason to USER.

Transitions Weavr triggers

Some transitions happen without an API call:

• Expiry — when a card reaches its expiry date and is not renewed, it transitions to DESTROYED with destroyedReason of EXPIRED.
• System block — Weavr or our administrators may block a card for compliance or risk reasons. The blockedReason is SYSTEM and only Weavr can unblock it.
• Compromised — if our systems detect that the card has been compromised, the card is destroyed with destroyedReason of COMPROMISED.

Subscribe to card webhook events to be notified about state transitions in real time.