Card Lifecycle and PIN

Acknowledge Card Reception

As a security measure in the logistical process of delivering physical plastics, by default, all physical cards created in the Sovera API are born inactive. This is reflected in the "isActive" and "status" fields of successful responses for the creation of these cards, as well as when making a GET call for all types of cards, such as seen in the example below:

{
  "success": true,
  "data": {
    "id": "string",
    "userId": "string",
    "walletId": "string",
    "physicalCard": true,
    "code": "string",
    "isActive": false,
    "status": "pendingAck",
    "creationDate": "2022-08-01T19:37:50.392Z",
    "dueDate": 0
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

Once a day, at a specific cut-off time, all physical cards created in the cycle are sent to the printing facility. The ackReception POST call will not return a successful response until the requested card has been printed, so it's a call that should only be made when the printed card is in hand or 48 hours after a successful response for card creation.

The purpose of this call is to allow the card to be delivered to the cardholder in an inactive state, waiting for validation of receipt from the cardholder once they have the card in hand.

The card-in-hand validation should be managed by comparing data entered by the cardholder (such as a range of the PAN or the CVV) with the results of calls made to obtain such sensitive data (see checkPan POST and checkCvv POST). If the entered data matches, the ackReception POST call can be made to activate the card for the first time, simply by sending the cardId of the card to be activated in the call.

The successful response to the call simply replicates the entered cardId. In case of encountering a 500 error, contact Sovera support team with the details of the case.

{
  "cardId": "string"
}

{
  "success": true,
  "data": {
    "cardId": "string"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

Block Card

‍This call allows for self-managed change of the card's activity status. This call directly affects the "isActive" boolean by transforming it to "false" based on a simple call that only carries the cardId.

{
  "cardId": "string"
}

{
  "success": true,
  "data": {
    "cardId": "string",
    "isActive": false
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

The API could respond with a descriptive HTTP 400 error if it is an attempt to block a card that has already been previously blocked. For active cards, unless an incorrect cardId is inputted, then the API will reply with a successful HTTP 201 Created message.

In case of encountering an HTTP 500 error, contact the Sovera support team with the details of the case.

Unblock Card

‍This call allows for self-managed change of the card's activity status. This call directly affects the "isActive" boolean by transforming it to "true" based on a simple call that only carries the cardId.

{
  "cardId": "string"
}

{
  "success": true,
  "data": {
    "cardId": "string",
    "isActive": true
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

The API could respond with a descriptive HTTP 400 error if it is an attempt to unblock an active card. For previously blocked cards that are currently inactive, unless an incorrect cardId is inputted, then the API will reply with a successful HTTP 201 Created message.

In case of encountering an HTTP 500 error, contact the Sovera support team with the details of the case.

Cancel Card

This call allows for permanently canceling a previously created card. This call directly affects the "isActive" boolean, changing it to "false", as well as the "status" field changing it to "Cancel" from a call that simply loads the cardId.

{
  "cardId": "string"
}

{
  "success": true,
  "data": {
    "cardId": "string",
    "isActive": "false"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

The Sovera API could respond with a descriptive HTTP 400 error if it is an attempt to cancel a card that has already been canceled.

In case of encountering an HTTP 500 error, contact the Sovera support team with the details of the case.

Check PAN

This call allows access to sensitive data such as the card number and expiration date. It requires a cardId as an input and carries the following structure:

{
  "cardId": "string"
}

{
  "success": true,
  "data": {
    "cardId": "string",
    "pan": "string",
    "expDate": 0
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

Unless an incorrect cardId is inputted, then the API will reply with a successful HTTP 201 Created message.

In case of encountering an HTTP 500 error, contact the Sovera support team with the details of the case.

Check CVV

This call allows access to sensitive data such as the card's CVV (Card Verification Value). It requires a cardId as an input and carries the following structure:

{
  "cardId": "string"
}

{
  "success": true,
  "data": {
    "cardId": "string",
    "cvv": "string"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

Unless an incorrect cardId is inputted, then the API will reply with a successful HTTP 201 Created message.

In case of encountering an HTTP 500 error, contact the Sovera support team with the details of the case.

Check Expiration Date

This call allows access the expiration date from the card. It requires a cardId as an input and carries the following structure:

{
  "cardId": "string"
}

{
  "success": true,
  "data": {
    "cardId": "string",
    "dueDate": "string"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

Unless an incorrect cardId is inputted, then the API will reply with a successful HTTP 201 Created message.

In case of encountering an HTTP 500 error, contact the Sovera support team with the details of the case.

Check PIN

This call allows access to the sensitive PIN data of the card, required for all ATM withdrawals and for some geographic regions' POS transactions.

{
  "cardId": "string"
}

{
  "success": true,
  "data": {
    "cardId": "string",
    "pin": "string"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

Unless an incorrect cardId is inputted, then the API will reply with a successful HTTP 201 Created message.

In case of encountering an HTTP 500 error, contact the Sovera support team with the details of the case.

Unblock PIN

This call allows the reactivation of a card's PIN after a security block occurs due to three incorrect attempts. The total number of acceptable incorrect attempts before the security block is a parameter that can be discussed during the project's scope definition phase, specifically for customized card profiles.

{
  "cardId": "string"
}

{
  "success": true,
  "data": {
    "cardId": "string",
    "pin": "string"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

Unless an incorrect cardId is inputted, then the API will reply with a successful HTTP 201 Created message.

In case of encountering an HTTP 500 error, contact the Sovera support team with the details of the case.

Change PIN

This call allows managing the sensitive PIN data of the card, which is required for all ATM withdrawals and for some geographic areas in point-of-sale devices. The call is designed to assign a 4-digit PIN specified by the user. The responses to this call should not be stored in databases for security reasons.

{
  "cardId": "string",
  "pin": "1234"
}

{
  "success": true,
  "data": {
    "cardId": "string",
    "pin": "string"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

On success, the API responds with HTTP 200 OK, echoing the cardId and the assigned pin.