Card Issuing & Management

Card Status Management

This page explains how to manage the status of an already issued card. The flow covers updating the card status, confirming the update, and retrieving the latest card status so your system can display the correct card state to the cardholder.

Updated 15 minutes ago

On this page

Overview

Card status management allows your system to update the state of a card after it has been issued. This is typically used when a cardholder or operational process requires a card to be activated, blocked, suspended, or otherwise updated according to the supported status values.

After a status update is submitted, your system should confirm the result and retrieve the latest card status when needed to keep the cardholder experience synchronized.

Recommended flow

Use the following flow when managing the status of an already issued card.

Identify the card

Use the stored card reference to identify the card that requires a status change.

Update Card Status

Submit the requested status update through the applicable Payblr card status API.

Confirm the update

Process the response returned by Payblr and confirm whether the status update was completed.

Get Card Status

Retrieve the latest card status so your system can display the correct card state to the cardholder.

Card Status Management Sequence Diagram

Recommended card status update sequence

User

Cardholder

System

Client System

Platform

Payblr APIs

1. Request status change

Cardholder requests a card status change in the client app.

CardholderClient System

2. Update Card Status

Status update

Endpoint

Update Card Status

Method

PUT /program-manager/thr/cards/{publicToken}/status

Client system submits the requested card status update to Payblr.

Client SystemPayblr APIs

3. Return update result

Endpoint

Update Card Status

Payblr returns the result of the card status update request.

Payblr APIsClient System

4. Get Card Status

Endpoint

Get Card Status

Method

GET /program-manager/thr/cards/{publicToken}/status

Client system retrieves the latest card status after the update.

Client SystemPayblr APIs

5. Return latest card status

Status update

Endpoint

Get Card Status

Payblr returns the current card status for the card.

Payblr APIsClient System

6. Display updated status

Client system displays the confirmed card status to the cardholder.

Client SystemCardholder

Sequence diagram showing how the cardholder, client system, and Payblr APIs participate in the card status management flow.

API sequence

The following sequence summarizes the API activities involved in managing card status.

Order	API activity	Purpose	Output / next action
1	Update Card Status	Submit the requested status update for an already issued card.	Process the update result returned by Payblr.
2	Get Card Status	Retrieve the latest card status after the update.	Display or store the confirmed card state.

Request patterns

PUT /program-manager/thr/cards/{publicToken}/status
Authorization: Bearer [ACCESS_TOKEN]
Content-Type: application/json

GET /program-manager/thr/cards/{publicToken}/status
Authorization: Bearer [ACCESS_TOKEN]
Accept: application/json

Card status codes

The following table describes card status codes that may be used when retrieving or updating a card status.

Note:

Live statuses can be changed. Archived statuses indicate that the card is not in use and the card status cannot be changed.

Code	Description	Type	Notes
`00`	The card is active.	Live	Status can be changed.
`02`	Card not yet activated or card is inactive.	Live	May be used for newly issued cards before activation.
`04`	Capture card.	Archived	Card is not in use and card status cannot be changed.
`05`	Do not honour.	Live	Status can be changed.
`14`	Invalid card.	Archived	Card is not in use and card status cannot be changed.
`41`	Lost card.	Archived	Card is not in use and card status cannot be changed.
`43`	Stolen card.	Archived	Card is not in use and card status cannot be changed.
`46`	Closed account.	Archived	Card is not in use and card status cannot be changed.
`54`	Expired card.	Archived	If set, money cannot be loaded onto the card.
`57`	Transaction not permitted to cardholder.	Live	Status can be changed.
`59`	Suspected fraud.	Live	Status can be changed.
`62`	Restricted card.	Live	If set, money cannot be loaded onto the card.
`63`	Security violation.	Live	If set, a balance adjustment cannot be performed for the card.
`70`	Cardholder to contact issuer.	Live	Status can be changed.
`75`	Allowable number of PIN tries exceeded.	Live	Status can be changed.
`83`	Card destroyed.	Archived	If set, money cannot be loaded onto the card.
`98`	Refund given to customer.	Archived	Card is not in use and card status cannot be changed.
`99`	Card voided.	Archived	If set, automatically adjusts the card balance to zero.
`G1`	Short-term block that temporarily blocks card usage for all card transactions, excluding credits and refunds.	Live	Status can be changed.
`G2`	Short-term full block. All transactions are blocked.	Live	Status can be changed.
`G3`	Long-term block, excluding credits and refunds.	Live	Status can be changed.
`G4`	Long-term full block. All transactions are blocked.	Live	Status can be changed.
`G5`	Status changed by fraud monitoring/protection service for a short-term block on all transactions, excluding credits and refunds.	Live	Status can be changed.
`G6`	Status changed by fraud monitoring/protection service for a short-term block on all transactions.	Live	Status can be changed.
`G7`	Status changed by fraud protection service for a long-term block on all transactions, excluding credits and refunds.	Live	Status can be changed.
`G8`	Status changed by fraud protection service for a long-term block on all transactions.	Live	Status can be changed.
`G9`	Status changed by fraud protection service for a lost/stolen block on all transactions.	Archived	Irreversible status. Card is not in use and card status cannot be changed.

Implementation notes

Before implementing card status management, confirm the supported statuses and transitions for the applicable card product and client program.

Confirm the card identifier before sending a status update.
Only allow valid status transitions supported by the client program and card product.
Store the latest confirmed status in your system after the update is completed.
Retrieve the latest card status after the update when your user experience depends on current card state.
Log request identifiers, card references, requested status, response status, and timestamps for troubleshooting.

Validate status transitions

Do not submit unsupported status transitions. Confirm the valid status values and transition rules for the card product before implementation.

Keep card state synchronized

Store or display the latest confirmed card status so the cardholder experience reflects the current card state.

Next steps

After implementing card status management, continue with card details update, CVV and PIN status management, secure card data, and renewal or replacement documentation as needed for your cardholder lifecycle.