Card Status Management

This sequence shows how an already issued card can be managed through your system after issuance. It focuses on two operations: updating card status and retrieving card status. The update call returns 200 OK on success, and the retrieve call also returns 200OK with the card’s current status information.

Prerequisite

Before this flow begins, the card must already exist. As part of the card lifecycle, physical cards are inactive by default unless activateNow is set to true, while virtual cards are active by default unless activateNow is set to false.

What this diagram covers

This diagram focuses on the status-management journey from the point of view of the cardholder and your system. The cardholder requests a status change through a mobile or web experience, your system submits the update request to Payblr, and then retrieves the latest status to confirm what should be shown back to the cardholder. The retrieve-status operation returns the current status code together with its description, which makes it a clean confirmation step after an update.

1. Update Card Status

Use this flow when your system needs to move a card into another supported lifecycle state. In the diagram, your system calls:

PUT /thr/thredd/cards/{publicToken}/status

The request should include cardStatusCode. It can also include additional fields such as status, updatedBy, description, and validityDate. A successful update returns 200 OK and includes the updated status information in the response.

This flow also covers card activation. For example, a physical card can be activated after receipt by setting cardStatusCode to 00.

2. Retrieve Card Status

Use this flow when your system needs to confirm the card’s current lifecycle state after a status change, or when the latest status must be displayed. In the diagram, your system calls:

GET /thr/thredd/cards/{publicToken}/status

A successful response returns 200 OK with the card’s current status code and status description. This makes it the best confirmation step after updating status.

Status behavior

The card status flow can support different types of lifecycle actions, not just a simple active/inactive change. Depending on the use case, status updates may represent:

• activation

• temporary restrictions

• permanent blocks

• expiration or other terminal states

For this reason, it is useful to treat status management as a dedicated operational flow rather than just another field update.

Idempotency

Idempotency is an integration concern related to retries and duplicate protection. Where supported, requests use a unique IdempotencyKey header value to identify the request.

Key considerations

• This page covers post-issuance card status management.

• Card status changes are handled as lifecycle state transitions.

• Card status retrieval is used to confirm the current state shown to the cardholder.

Card Status Codes

The following table describes the codes that can be used for a card's status.