Card Status Change

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

About Card Status

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

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

Live Status Values

Status values in the Live category are applicable to a card that is still in use.
You can change a card's status to any of the following values:

  • Active
  • Inactive
  • DoNotHonour
  • LostCard
  • ReferToIssuer
  • CardPinBlocked

For details of status values, see Card Status Description.

Archived Status Values

Status values in the Archived category are applicable to a card that is no longer in use. Once a card's status has been updated to one of the following archived states it cannot be changed:

  • CardVoided
  • CardDestroyed
  • StolenCard
  • CardExpired

For details of status values, see Card Status Description.

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. Once you have created a card, you can use the card status endpoint to set the status of the card to active. GPS 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

GPS 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 card creation API Call (in the case of virtual cards), this is returned in the response to creating a card within the publicToken object.

Step 2: Activate a Card

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

{
  "status": "active"
}

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

Updating Card Status

Step 1: Retrieve Card Status

To retrieve the current card status you can use a GET method on the card status endpoint. This request returns the current status of the card linked to the Public Token in the request.

👍

API Explorer

See the Retrieve card status endpoint.

Step 2: Update Card Status

To update a card status, you can use a PUT method on the card status endpoint with an updated status in the request body.

The example below updates a card to the "Do Not Honour" status. For details of status values, see Card Status Description.

{
  "status": "DoNotHonour"
}

A successful response will return a 200 with the updated card status in the response.

👍

API Explorer

See the Update card status endpoint.

Status Codes for Card Blocks

Use the following GPS 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 card status endpoint, with the Public Token of the card whose status you are retrieving.

Card Status Description

Note that when you set the card to a status value, that status determines whether the card can be used or not, and what type of message is returned to the merchant shop when the card is used.

Status

Description

Type

Active

Card is active and ready for use

Live - status can be changed

Inactive

Card is not active. It must be set to active before it can be used.

Live - status can be changed

DoNotHonour

The card status indicates that a merchant should not accept transactions on this card. While in this status, the card cannot be used.

Live - status can be changed

LostCard

The card has been reported as lost. While in this status, the card cannot be used.

Live - status can be changed

ReferToIssuer

The card status indicates that a merchant should contact the issuer about any transactions on this card. While in this status, the card cannot be used.

Live - status can be changed

CardPinBlocked

The card PIN is blocked. The card cannot be used at a POS terminal.

Live - status can be changed

CardVoided

The card record has been voided.

Archived - card is not in use and card status cannot be changed

CardDestroyed

The card has been reported as destroyed.

Archived - card is not in use and card status cannot be changed

StolenCard

The card has been reported as destroyed.

Archived - card is not in use and card status cannot be changed

CardExpired

The card has expired.

Archived - card is not in use and card status cannot be changed


Did this page help you?