Card Status

This section provides details on card status, how to manage a card's status throughout the card's life cycle and how a card's status can be used to manage a variety of situations including when a card is lost, stolen or damaged.

By default both Physical and Virtual cards are issued in an inactive state on the Thredd system. You can activate a card and manage the card throughout its lifecycle using the Update Card Status endpoint.

When active, the card's status can be in one of two categories: Live or Archived.

📘

Note

For a full list of card status codes, see Card Status Codes.

Activating a Card

Both physical and virtual cards are created with an inactive status, which means that the card is live, but cannot be used. When you have created a card, you can use the card status endpoint to set the status of the card to active. Thredd recommends the following:

  • For a physical card, the cardholder should be provided with a means to request card activation when they have received their card (for example, via your customer app or call centre).
  • For a virtual card and for certain types of prepaid cards, after card creation you can immediately change the status of the card to Active.

📘

Activate virtual cards immediately

Thredd recommends you activate virtual cards immediately.

Step 1: Retrieve Card Details

Before activating a card, you will need to identify the corresponding Public Token for the card.
If you are activating a card straight after a Creating a Card API Call, this is returned in the response to creating a card within the publicToken object.

742

Step 2: Activate a Card

After identifying the Public Token for the card, you can use it to make a PUT request to the Update card status endpoint with the following payload:

{
  "CardStatusCode": "00"
}

A successful response will return a 200 http code with the updated card status code in the response and a description of the status.

{
     "status": "Active",
  	 "cardStatusCode": "00",
     "updatedBy": "John Bloggs",
     "description": "Card activated",
     "validityDate": "2023-02"
}

Updating Card Status

The Update Card Status endpoint enables you to update the status of a card, such as changing the status to active from inactive.

You can update a status by making a PUT request to the endpoint. For example:

{
     "cardStatusCode": "00",
     "updatedBy": "John Bloggs",
     "description": "Card activated",
     "validityDate": "2023-02"
}

A successful response will return a HTTP 200 response code. Below is an example response:

{
    "status": "Active",
  	"cardStatusCode": "00",
    "updated": "2023-02-10",
    "updatedBy": "John Bloggs",
    "description": "Card was activated. Card Expiry Changed From 2024-02-29 To Feb 29 2024 12:00AM"
}

👍

API Explorer

See the Update card status endpoint.

Status Codes for Card Blocks

Use the following Thredd status codes for card blocks:

  • Temporary Block: "05 - Do Not Honour", "62 - Restricted Card"
  • Permanent Block: "41 - Lost", "43 - Stolen", "83 - Card Destroyed"

Get Card Status

You can retrieve details of the current card status by making a GET request to the Retrieve Card Status endpoint, with the Public Token of the card whose status you are retrieving. For example:

{{base-url}}/cards/{{publicToken}}/status

If successful, a 200 response is returned with the card status code and the description of that status.

{
    "status": "Active",
 	  "cardStatusCode": "00",
    "cardStatusDescription": "00 (Active)"
}

👍

API Explorer

See the Retrieve card status endpoint.