PIN Management

This section provides instructions on how to manage your cardholder's Personal Identification Number (PIN). A card's PIN is a short numerical code used to authorise Point of Sale (POS) transactions between a merchant and cardholder. This provides an additional layer of security for POS transactions.

A card's PIN is always set to a randomly allocated value as part of the create card API call. To find out more about creating cards, see Creating a Card.

After card creation, the GPS Cards API enables you to:

  • Set a card's PIN to a user-defined value
  • Retrieve a card's PIN to display to the user
  • Unblock a card's PIN when the maximum number of attempts has been exceeded

Setting a card's PIN

Step 1: Identify the card's public token

Before setting a card's PIN, identify the corresponding public token relating to the card. This is returned in the response to creating a card within the publicToken object.

Step 2: Set the card's PIN

After identifying the card's public token, execute a POST call to the cards Set Card PIN endpoint with an updated PIN in the request body.
The example below updates a card PIN to 0000.

{
  "pin": 0000
}

A successful response will return a 204 http code - success with no response.

👍

API Explorer

See the Set card PIN endpoint for more information.

Retrieving a card's PIN

Step 1: Identify the card's public token

Before retrieving a card's PIN, identify the corresponding public token relating to the card. This is returned in the response to creating a card within the publicToken object.

Step 2: Retrieving the card's PIN

After identifying the card's public token, execute a GET call to the cards pin retrieve endpoint.

👍

API Explorer

See the Retrieve card PIN endpoint for more information.

This request requires no body and a successful response will return a 200 http code and the card's PIN.

Unblocking a card's PIN

Step 1: Identify the card's public token

Before unblocking a card's PIN, identify the corresponding public token relating to the card. This is returned in the response to creating a card within the publicToken object.

Step 2: Unblock the card's PIN

After identifying the card's public token, execute a POST call to the cards pin unblock endpoint.

👍

API Explorer

See the Unblock card PIN endpoint.

This request requires no body and a successful response will return a 204 http code - success with no response.

📘

Resetting an unblocked PIN

You can reset a card's PIN attempt counter at any time; it doesn't need to reach zero. Executing a successful unblock PIN request resets the PIN attempt counter back to its maximum value.