Skip to content

Replace card

This method replaces a specified card. Card replacement is permitted only if the card is in one of the statuses listed below:

  • "DIGITALLY ACTIVE"
  • "ACTIVE"
  • "BLOCKED"
  • "CANCELLED"
  • "REVOKED" where reason for card revoke does not equal "REPLACEMENT"

Then the new successor card is created in the “CONFIRMING” state and, depending on the card technology, transitions it to either “INACTIVE”, “DIGITALLY ACTIVE”, or “ACTIVE” status. Virtual cards utilizing “VIRTUAL” and “VIRTUAL DISPOSABLE” technologies are promptly set to “ACTIVE” status. Physical cards, categorized by “MAGSTRIPE”, “CONTACT CHIP”, or “CONTACTLESS CHIP” technologies, are set to “INACTIVE” status for non-tokenizable cards and to “DIGITALLY ACTIVE” for tokenizable cards.

Each new successor card request must specify "ACTIVE" CPD "code", or alternatively, its CPD successor. The specified CPD establishes predefined limits, restrictions, card design, and instructions for card production and delivery.

To set a limit for a card, the ID of the limit must be provided along with all the necessary values. All limits included in CPD, which allows modifications must be included in a request for a new card. If a limit has a range of values set by CPD, the CMS will allow only setting limit value in this range. Limits can be configured for daily, weekly, and monthly periods, encompassing both amount and count settings. List of limits can be found here.

To set a restriction for a card, the ID of the restriction must be provided along with all the necessary values. All restrictions included in CPD, which allows modifications must be included in a request for a new card. Restrictions can be established using the logic of a blacklist, whitelist, or a specific flag from transaction data to either restrict or allow specific transaction configurations. List of restrictions can be found here.

Editing limits and restrictions settings is permissible after card creation using PUT/cards/{id}/limits and PUT /cards/{id}/restrictions, subject to the preferences of the owner or cardholder, provided that the settings for the restriction or limit allow such modifications.

As the replace card is created by the card processor as well as new cards, CMS sends a request to the card processor to create new card based on the settings specified in the request when creating a replaced card. The replaced card is then permitted to authorize transactions, adhering to the resulting state in which the replaced card is provided.

URL test:

https://dev.lightcms.io/cms/v1/cards/{id}/replace

URL live:

https://fat.lightcms.io/cms/v1/cards/{id}/replace

Method:

POST

Path items:

/cards (Card Service)

/{id} (ID code of replaced card)

/replace (Method name)

Parameters:

Parameter Location Type Example Description Required
card body "object" - Card details Yes
cpdCode card "string" "94CHBIA4FX31CUPWFMNSHONI" CPD code Yes
expressDelivery card "boolean" true Enables express delivery No
delivery body "object" - Yes
deliveryType delivery "string" "POST" POST/BRANCH/INSTANT Yes
deliveryPoint delivery "string" - ID of Branch Yes1)
deliveryAddress delivery "string" - Delivery address of holder Yes2)
city deliveryAddress "string" "Příbram" Yes2)
country deliveryAddress "string" "CZE" Yes2)
state deliveryAddress "string" "CZE" No
addressLine1 deliveryAddress "string" "Barandovská 424" Yes2)
addressLine2 deliveryAddress "string" No
zip deliveryAddress "string" "26101" Yes2)
limits body "object" - Limits details Yes
limitId limits "string" LIM_POS_D Limit ID specified in CPD Yes
limitType limits "string" "AMOUNT" AMOUNT/COUNT Limit type No
limitValue limits "integer" "50000" Yes
name limits "string" "POS DAILY LIMIT" Limit name No
restrictions body "object" - Resctions details Yes
name restrictions "string" "CASH TRANSACTIONS" Restriction name No
restrictionId restrictions "string" "DENYCASH" Restriction ID specified in CPD Yes
restrictionValue restrictions "string" "ENABLED" ENABLED/DISABLED value for turning ON or OFF the restriction Yes

Info

1) If Delivery type is BRANCH

2) If Delviery type is POST

Example:

curl -X 'POST' \
  'https://dev.lightcms.io/cms/v1/cards/32/replace' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "card": {
    "cpdCode": "VISA_DEV_TEST",
    "expressDelivery": true
  },
  "holder": {
    "holderExternalId": "1002778",
    "firstName": "Benjamin",
    "lastName": "Griffiths",
    "embossName": "GRIFFITHS BENJAMIN",
    "sex": "MALE",
    "birthdate": "01-01-1970",
    "phoneNumber": "123456789",
    "residenceAddress": {
      "addressLine1": " 59",
      "city": "Černá Voda",
      "country": "CZE",
      "zip": "79054"
    },
    "mailingAddress": {
      "addressLine1": " 59",
      "city": "Černá Voda",
      "country": "CZE",
      "zip": "79054"
    }
  },
  "delivery": {
    "deliveryType": "INSTANT"
  },
  "limits": [
    {
      "limitId": "LIM_17_POS_AMT_D",
      "limitValue": 50000
    },
    {
      "limitId": "LIM_17_ECOM_AMT_D",
      "limitValue": 20000
    },
    {
      "limitId": "LIM_17_ATM_AMT_D",
      "limitValue": 50000
    }
  ],
  "restrictions": [
    {
      "restrictionId": "TPRF_17_01_2",
      "restrictionValue": "DISABLED"
    },
    {
      "restrictionId": "TPRF_17_01_3",
      "restrictionValue": "DISABLED"
    },
    {
      "restrictionId": "TPRF_17_01_4",
      "restrictionValue": "DISABLED"
    },
    {
      "restrictionId": "TPRF_17_01_5",
      "restrictionValue": "DISABLED"
    },
    {
      "restrictionId": "TPRF_17_01_7",
      "restrictionValue": "DISABLED"
    },
    {
      "restrictionId": "TPRF_17_01_9",
      "restrictionValue": "DISABLED"
    },
    {
      "restrictionId": "TPRF_17_01_8",
      "restrictionValue": "DISABLED"
    },
    {
      "restrictionId": "TPRF_17_01_6",
      "restrictionValue": "DISABLED"
    },
    {
      "restrictionId": "TERMINAL_EU_COUNTRIES",
      "restrictionValue": "DISABLED"
    },
    {
      "restrictionId": "TRANSACTIONS_PERMISSIONS_A",
      "restrictionValue": "DISABLED"
    },
    {
      "restrictionId": "TRANSACTIONS_PERMISSIONS_B",
      "restrictionValue": "DISABLED"
    }
  ]
}
'

Responses:

200 - OK

Status Code: 200 OK

{
  "cardId": 33,
  "expiryDate": "2804"
}

Parameter Location Type Example Description
cardId body integer 265 Internal Card ID
expiryDate body date "2024-04-10T08:54:30.070Z" Expiry date of Card
500 - Internal error

Status Code: 500 Internal error

404 - Not found

Status Code: 404 Not found

{
"errorMessage": "Entity with id 132132123 not found in DB."
}

Parameter Location Type Example Description
errorMessage body string "Entity with id 132132123 not found in DB." Error message
400 - Incorrect parameters

Status Code: 400 Bad request

{
"delivery.deliveryAddress.country": "must be a valid alpha3 country code"
}

Parameter Location Type Example Description
incorrect parameter body string "must be a valid alpha3 country code" Requested parameters detail
400 - Bad request format

Status Code: 400 Bad request

{
"timestamp": "2024-04-10T11:47:49.208+00:00",
"status": 400,
"error": "Bad Request",
"path": "/cms/v1/cards/27/replace"
}

Parameter Location Type Example Description
timestamp body date "2024-04-10T11:47:49.208+00:00" Timestamp of request
status body integer 400 Status error code
error body string "Bad Request" Error description
path body string "/cms/v1/cards/27/replace" Request path