Create new card

This method creates a card 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 card request must specify "ACTIVE" CPD "code", if it selected deactivated CPD, CMS automatically retrieves its "ACTIVE" 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 card number is assigned by the card processor, CMS sends a request to the card processor to assign a card number based on the settings specified in the request when creating a new card. The new card number is then permitted to authorize transactions, adhering to the resulting state in which the new card is provided.

URL test:

https://test.lightcms.io/cms/v1/cards

Method:

POST

Path items:

/cards (Card Service)

Headers

Parameter	Type	Required	Description
x-idempotency-key	string	No	Idempotency key to guarantee safe retries of the activation.
x-tenant	string	No	Tenant identifier (used in multi‑tenant deployments).

Request Body

`card`

Required.

Field	Type	Required	Constraints	Description
cpdCode	string	Yes	pattern `^[A-Z0-9_-]{3,50}$`	CPD code
expressDelivery	boolean	No		Enables express delivery

`holder`

Required.

Field	Type	Required	Constraints	Description
holderExternalId	string	Yes	not empty, max 50 chars	External holder ID
firstName	string	Yes	not empty, max 50 chars	First name
middleName	string	No	max 50 chars	Middle name
lastName	string	Yes	not empty, max 50 chars	Last name
sex	string	Yes	`MALE` / `FEMALE`	Sex
birthdate	date	Yes	format `YYYY-MM-DD`	Date of birth
phoneNumber	string	No	valid phone number (regex from config)	Mobile phone number
email	string	No	valid email format	Email address
residenceAddress	object	Yes	see `address`	Residence address
mailingAddress	object	No	see `address`	Mailing address

`accountsInfo`

Required.

`accountsInfo.accountOwner`

Required. The required fields within accountOwner depend on subjectType:

`subjectType`	Required fields	Forbidden fields
`PERSON`	`firstName`, `lastName`, `birthdate`, `sex`	`companyName`, `businessId`
`COMPANY`	`companyName`, `businessId`	`firstName`, `lastName`, `middleName`, `birthdate`, `sex`

Field	Type	Required	Constraints	Description
holderExternalId	string	Yes	not empty, max 50 chars	Account owner external ID
subjectType	string	Yes	`PERSON` / `COMPANY`	Drives conditional requirements
firstName	string	Cond. (PERSON)	max 50 chars	First name
middleName	string	No	max 50 chars	Middle name
lastName	string	Cond. (PERSON)	max 50 chars	Last name
sex	string	Cond. (PERSON)	`MALE` / `FEMALE`	Sex
birthdate	date	Cond. (PERSON)	format `YYYY-MM-DD`	Date of birth
companyName	string	Cond. (COMPANY)		Company name
businessId	string	Cond. (COMPANY)		Business ID (IČO)
phoneNumber	string	No	valid phone number (regex from config)	Mobile phone number
email	string	No	valid email format	Email address
residenceAddress	object	Yes	see `address`	Residence address

`accountsInfo.accounts[]`

Required. At least one item.

Field	Type	Required	Constraints	Description
accountExternalId	string	Yes	valid account external ID	Bank account number (unique per `accountCurrency`)
accountCurrency	string	No	exactly 3 chars, ISO 4217	Account currency (e.g. `CZK`)

`delivery`

Required.

Field	Type	Required	Constraints	Description
deliveryType	string	Yes	`POST` / `BRANCH` / `INSTANT`	Card delivery method
deliveryPoint	string	Cond. (BRANCH)	1–50 chars	Branch code; required when `deliveryType = BRANCH`, forbidden otherwise
deliveryAddress	object	Cond. (POST)	see `address`	Delivery address; required when `deliveryType = POST`, forbidden otherwise

`limits[]`

Optional. When provided, must include all limits from the CPD that allow modification.

Field	Type	Required	Description
limitId	string	Yes	Limit ID as defined in CPD
limitType	string	No	`AMOUNT` / `COUNT`
limitValue	integer	Yes	Limit value
name	string	No	Human-readable limit name

`restrictions[]`

Optional. When provided, must include all restrictions from the CPD that allow modification.

Field	Type	Required	Description
restrictionId	string	Yes	Restriction ID as defined in CPD
restrictionValue	string	No	`ENABLED` / `DISABLED`
name	string	No	Human-readable restriction name

`address` object

Reused by holder.residenceAddress, holder.mailingAddress, accountsInfo.accountOwner.residenceAddress, and delivery.deliveryAddress.

Field	Type	Required	Constraints	Description
addressLine1	string	Yes	1–50 chars	Street and house number
addressLine2	string	No	max 50 chars	Additional address info
city	string	Yes	1–50 chars	City
state	string	No	max 50 chars	State / region
zip	string	Yes	1–50 chars	ZIP code
country	string	Yes	ISO 3166-1 alpha-3 (e.g. `CZE`)	Country code

Example:

curl -X 'POST' \
  'https://test.lightcms.io/cms/v1/cards' \
  -H 'accept: */*' \
  -H 'x-idempotency-key: 1' \
  -H 'x-tenant: 1' \
  -H 'Content-Type: application/json' \
  -d '{
  "card": {
    "cpdCode": "VISA_DEV_TEST",
    "expressDelivery": true
  },
  "holder": {
    "holderExternalId": "1002778",
    "firstName": "Benjamin",
    "lastName": "Griffiths",
    "sex": "MALE",
    "birthdate": "1970-01-01",
    "phoneNumber": "123456789",
    "residenceAddress": {
      "addressLine1": " 59",
      "city": "Černá Voda",
      "country": "CZE",
      "zip": "79054"
    },
    "mailingAddress": {
      "addressLine1": " 59",
      "city": "Černá Voda",
      "country": "CZE",
      "zip": "79054"
    }
  },
  "accountsInfo": {
    "accountOwner": {
      "holderExternalId": "1001863",
      "subjectType": "PERSON",
      "firstName": "Duncan",
      "lastName": "Clarke",
      "sex": "MALE",
      "birthdate": "1970-01-01",
      "phoneNumber": "123456789",
      "residenceAddress": {
        "addressLine1": "Boční 300",
        "city": "Jablonec nad Nisou",
        "country": "CZE",
        "zip": "46801"
      }
    },
    "accounts": [
      {
        "accountExternalId": "1000019953",
        "accountCurrency": "CZK"
      }
    ]
  },
  "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:

201 - Created

Status Code: 201 Created

  {
    "cardId": 32,
    "expiryDate": "2028-04-01T00:00:00Z"
  }

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

400 - Incorrect parameters

Status Code: 400 Bad request

  {
  "accountsInfo.accounts[0].accountExternalId": "must be a valid account external id",
  "delivery.validDeliveryPointAllowed": "deliveryPoint is allowed only for BRANCH",
  "accountsInfo.accountOwner.residenceAddress.country": "must be a valid alpha3 country code",
  "holder.residenceAddress.country": "must be a valid alpha3 country code",
  "delivery.deliveryAddress.country": "must be a valid alpha3 country code",
  "holder.mailingAddress.country": "must be a valid alpha3 country code"
  }

Parameter	Location	Type	Example	Description
incorrect parameter	body	string[]	"must be a valid account external id"	Requested parameters detail

Create new card

URL test:

Method:

Path items:

Headers

Request Body

card

holder

accountsInfo

accountsInfo.accountOwner

accountsInfo.accounts[]

delivery

limits[]

restrictions[]

address object

Example:

Responses:

`card`

`holder`

`accountsInfo`

`accountsInfo.accountOwner`

`accountsInfo.accounts[]`

`delivery`

`limits[]`

`restrictions[]`

`address` object