# Card Management System
source: https://developer.mastercard.com/mastercard-processing-core/documentation/guides/card-management-system/index.md

## Overview {#overview}

Mastercard Processing enables you to access the Mastercard Processing Card Management System (CMS). The system uses three main classes of objects:

* Client
* Contract (account contract and card contract)
* Card plastic (physical or virtual cards)

The most simple and intuitive is a client object that owns contracts. Clients can own many contracts, both account contracts and card contracts. Account and card contracts are linked together so that a card contract is a subcontract of an account contract. This means that an account contract is higher in the hierarchy.

Although contracts are different and linked to each other in the hierarchy, they belong to the same class of objects in the CMS. This allows you to choose the level (account or card) on which you would like to set specific parameters.

The card plastic object relates to physical and virtual cards, and is linked with a particular card contract.

Relations between these entities and their properties are described in the relevant sections of this documentation.

![](https://static.developer.mastercard.com/content/mastercard-processing-core/uploads/processing_6.png)

To meet the issuers' requirements for card issuing, a specific structure of main objects in a particular sequence must be created.

![](https://static.developer.mastercard.com/content/mastercard-processing-core/uploads/processing_7.png)

### General Rules {#general-rules}

The general rules are:

* One client can have multiple account contracts linked.
* One account contract can have multiple card contracts linked.
* One account contract can have other account contracts linked as sub-accounts. More complex structures of contracts are useful for corporate cards.
* Each account contract is linked to one client (the account owner).
* Each card contract is linked to one account contract.
* Each card contract is linked to one cardholder (client who is a card user).

## Client {#client}

A client represents a physical person or a company that owns the account contracts and card contracts. You can also construct a client as a technical object without any connection to the real entity.

The client object stores the following information:

* Personal data, such as last name, marital status, and birthplace
* Identification data
* Contact data
* Base address date
* Company data
* Embossed data
* Custom data

A client has two roles:

* **Owner**: A client who owns the account contract. This role typically includes the cardholder role.
* **Cardholder**: A client who owns the card contract but does not own the account contract.

The following rules apply to a card contract:

* Has one owner and one cardholder (who is typically the same client).
* Is linked to one account contract.

A client can have multiple account contracts, but every account contract must be linked to one client. Multiple card contracts can be linked to each account contract, but each card contract is connected to one account contract. A cardholder can have a card contract and be the owner of the account contract. A cardholder can also possess a card contract linked to a different account contract. This situation is illustrated in the following diagram:
![](https://static.developer.mastercard.com/content/mastercard-processing-core/uploads/processing_8.png)

The methods used for the client object are illustrated in the following diagram:
![](https://static.developer.mastercard.com/content/mastercard-processing-core/uploads/client-object.png)

## Contract {#contract}

A contract is a category of objects that exist in two forms: an account contract and a card contract. Although they are objects of the same class, both are inherited from contract objects. This allows some CMS functionalities, such as usage limits, transactions, addresses, and classifiers, to be available on the contract level. These functionalities are accessible with one common operation that requires `contractId` in the path. You can provide the `accountContractId` or `cardContractId` depending on which object the operation is to be performed.

![](https://static.developer.mastercard.com/content/mastercard-processing-core/uploads/contract-object.png)

## Account Contract {#account-contract}

An account contract represents a contract for an account owned by a client in the account owner role. You must create an account contract for each client. An account contract can have multiple card contracts or account contracts linked as sub-accounts, forming a hierarchical tree. The mandatory dataset for creating an `AccountContract` object contains the following:

* `accountContractNumber` - an [identifier](https://developer.mastercard.com/mastercard-processing-core/documentation/guides/card-management-system/index.md#object-identifiers) from your internal system called the Core Banking System (CBS) in this documentation.
* A `productCode` that determines a set of general [configuration parameters](https://developer.mastercard.com/mastercard-processing-core/documentation/guides/card-management-system/index.md#product-configuration-for-account-contracts-and-card-contracts), including currency.  
  Note: Although `clientId` is not a mandatory field, it is conditionally required if you want to create a top account. For creating a subaccount, this field should be skipped. The methods used for the account contract object are illustrated in the following diagram: ![](https://static.developer.mastercard.com/content/mastercard-processing-core/uploads/account-contract-object.png)

## Card Contract {#card-contract}

A card contract represents the actual card and is necessary to carry out payment transactions. The card contract is the most relevant object describing what the cardholder understands as a banking card with all its properties and functionalities, such as usage limits or embossed data. A card contract is created for a specific account contract. The mandatory dataset for creating a card contract contains:

* Card [identifiers](https://developer.mastercard.com/mastercard-processing-core/documentation/guides/card-management-system/index.md#object-identifiers)
* Card contract `productCode` representing [product configuration](https://developer.mastercard.com/mastercard-processing-core/documentation/guides/card-management-system/index.md#product-configuration-for-account-contracts-and-card-contracts) in the CMS which determines a specific set of parameters, such as list of allowed transactions, risk rules, and so on.

The methods used for the card contract object are illustrated in the following diagram:
![](https://static.developer.mastercard.com/content/mastercard-processing-core/uploads/card-contract-object.png)

## Card Plastic {#card-plastic}

A card plastic applies to virtual and physical cards issued under a card contract. The card plastics data is stored in the `CardContractPlastics` object in the CMS and helps with card management. The `CardContractPlastics` array object keeps a list of all `Plastic` linked to a specific card contract. It contains the `plasticId`, `sequenceNumber`, and `status` fields which make card-related operations, such as card renewal, simple and accurate.

The card plastic is automatically created by CMS after the `createCardContract` and `reissueCard` requests and contains the following data:

* An expiry date.
* A Card Verification Code 2 (CVC2) for Mastercard, or Card Verification Value 2 (CVV2) for Visa.
* A `sequenceNumber`, the incremental number assigned to consecutive cards. Virtual and physical cards are numbered.
* The embossed data.
* A `plasticId`, the technical identifier of `Plastic`.

To determine if a specific Plastic represents virtual or physical card, use the `getCardPlastics` operation to retrieve all `Plastic` created under a specified card contract and check the value returned in the `productionCode` field:

| productionCode | Type of card |                                                                          Description                                                                           |
|----------------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| NWOPIN_NOPROD  | Virtual      | New virtual card (the `createCardContract` request)                                                                                                            |
| NWOPIN         | Physical     | New physical card (the `createCardContract` request)                                                                                                           |
| RPLRE          | Physical     | Issue a physical card to an existing virtual card or duplicate a physical card (the `reissueCard` request with the `REISSUE` value in the `reissueType` field) |
| RPLRE_NOPROD   | Virtual      | Renew with a virtual card (the `reissueCard` request with the `RENEW_D` value in the `reissueType` field)                                                      |
| RPL            | Physical     | Renew with a physical card (the `reissueCard` request with the `RENEW` value in the `reissueType` field)                                                       |
| RWOPIN_NOPROD  | Virtual      | Replace with a virtual card (the `reissueCard` request with the `REPLACE_D` value in the `reissueType` field)                                                  |
| NLOSTWOPIN     | Physical     | Replace with a physical card (the `reissueCard` request with the `REPLACE` value in the `reissueType` field)                                                   |

![](https://static.developer.mastercard.com/content/mastercard-processing-core/uploads/card-plastic-object.png)

### Card Plastic Sequence Number {#card-plastic-sequence-number}

Only the expiry date and CVC change during renewal. The Primary Account Number (PAN), cardholder name, and PIN do not change. The card plastic `sequenceNumber` makes card management possible, as you can track all `Plastic` issued.

The first card issued is assigned the sequence number '1'. The sequence number of the next card `Plastic` is increased by one. To learn more about card plastic, refer to [Card Lifecycle](https://developer.mastercard.com/mastercard-processing-core/documentation/guides/card-lifecycle/index.md).

## Other Objects {#other-objects}

#### Addresses {#addresses}

Mastercard Processing allows you to store multiple addresses. However, when you create a main object (client, card contract, or account contract), you can only provide one address on the client level when you send a `POST` request to the `/clients` endpoint. You can store additional addresses on the client, account contract, or card contract using a dedicated API operation. Each additional address must be defined during the onboarding process with a dedicated address type (for example, PIN, STMT, TAX, and so on).

#### Embossed Data {#embossed-data}

The embossed data specifies the text to be embossed on a physical card. It can be stored on the client or the card contract level. When a new card is ordered, a card contract is created, and the CMS initiates the card [personalization process](https://developer.mastercard.com/mastercard-processing-core/documentation/guides/issuing-card/index.md#personalization-process). The process includes preparing the data required for physical card production and production in general. The storage rules for embossed data in card production are as follows:

* If the client embossed data and the card contract embossed data fields are filled, then the personalization process uses the values from the card contract.
* If the client embossed data fields are not filled and a `POST /cards` request is processed without providing embossed data, then the Mastercard Processing CMS will not allow the creation of a card contract. The request will be rejected with an error message. For more information about error messages, see [Error Codes](https://developer.mastercard.com/mastercard-processing-core/documentation/code-and-formats/index.md).

Note: According to embossed data, the `lastName` field is mandatory and must always be filled. In a special case, when you want to show on a physical card only a company name, it must be placed in the `lastName` field instead of the `companyName` field.

The Mastercard Processing CMS checks the length of the fields and limits the number of characters because they must be printed on the card with a standard font. By default, the length is limited to 26 characters for each line printed on the card but it can be adjusted to your needs during the onboarding process.
![](https://static.developer.mastercard.com/content/mastercard-processing-core/uploads/processing_13.png)

The Mastercard Processing CMS validates the types of characters submitted. If you provide a character that is not allowed, an error message will be returned, and your request will be rejected.

#### Custom data {#custom-data}

The Mastercard Processing Card Management System (CMS) was not intended to serve as Customer Relationship Management (CRM) system. The CMS stores only basic information about the `client`, `accountContract`, and `cardContract`, but there is often a need to store additional information, flags, or specific data. For this purpose, `customData` can be used.

The CMS provides four containers for storing additional information for each object (client, account contract, and card contract). The data in the containers are stored as a `key` and `value` in the format `key=value`.

Containers have fixed names: `tagContainer` field with defined values:

* ADD_INFO_01
* ADD_INFO_02
* ADD_INFO_03
* ADD_INFO_04

The data is stored in a format of string, key=value, in this case: `tagName`=`tagValue` separated by the semicolon. You can specify a proper value to make the `tagName` field meaningful.

For example, Container 1  

`tagContainer`: 'ADD_INFO_01'  

`tagName`: 'Client_status'  

`tagValue`: 'VIP'  

`tagName`: 'Company_name'  

`tagValue`: 'My_Company'

will store data in one string: 'Client_status=VIP;Company_name=My_Company'.
Tip: The `customData` defined on the card level is sent to the personalization bureau in a personalization file for adding any specific information, such as card carrier. Note: Due to the format of storing in the database, it is not allowed to use "=", ";", or " " characters in the `customData` `key` and `value`.

The maximum length of each container is as follows:

* Client -- 3900 characters
* Account contract and card contract -- 255 characters

The API rejects the request if the length of the container is exceeded.  

Depending on the onboarding configuration, the CMS can also store some internal values in some containers.

## Object Identifiers {#object-identifiers}

The Mastercard Processing API is flexible and provides multiple identifiers to manage the main objects of the Card Management System (CMS): client, account contract and card contract. Mastercard Processing generates some identifiers, and some can come from servers. This documentation refers to servers as the Core Banking System. When you create a new client, account contract, or card contract object, you are asked to provide in the request your identifiers stored in your CBS. You will receive the CMS technical number as the object identifier generated by the CMS in the response, and you must reference it in all requests concerning that object. If you do not want to store the CMS technical numbers in your system, you can send a request to retrieve the CMS numbers. The CMS will maintain the mapping between your CBS numbers and CMS technical identifiers.

The following list names all objects and their available identifiers:

* **Client** : The client number is generated by the CMS and is stored in the `clientId` field. The client identification number is defined by you and is named `clientNumber` in our system. It must contain a three-letter prefix related to your company name to prevent other institutions from using the same `clientNumber`. Your unique prefix is approved during onboarding.
* **Account contract** : The unique account contract number is generated by the CMS and is stored in the `accountContractId` field. The number provided by your Core Banking System is called the `accountContractNumber`, and a unique three-letter prefix agreed with Mastercard Processing should precede it. The `cbsNumber` is used in our Graphic User Interface (GUI), Workbench. This field is usually used to store the IBAN of the account.
* **Card contract** : By default, the CMS system generates a unique number in the `cardContractId` field for use in the API requests. The `cardContractNumber` field stores the PAN up to 19-digit (usually 16-digit) format as the card contract stores data directly related to the card. If issuers do not want to handle [PAN](https://developer.mastercard.com/mastercard-processing-core/documentation/guides/pan-related-decisions/index.md), the alternative `cbsNumber` is generated by the CMS or provided by the Core Banking System and used in our GUI Workbench. Mastercard Processing is a full Payment Card Industry (PCI) compliant partner. We store PAN in the CMS and keep PAN's mapping to the `cbsNumber` and `cardContractId`.

|    **Object**    | **Identifier (API field name)** | **Generated by** |                                         **Description and Format**                                          |
|------------------|---------------------------------|------------------|-------------------------------------------------------------------------------------------------------------|
| Client           | clientId                        | CMS              | NUMERIC                                                                                                     |
|                  | clientNumber                    | Issuer           | Issuer prefix (set by CMS) + number generated by the issuer Example: 'ABC_000000001'                        |
| Account contract | accountContractId               | CMS              | NUMERIC                                                                                                     |
|                  | accountContractNumber           | Issuer           | Issuer prefix (agreed with Mastercard Processing) + number generated by the issuer Example: 'ABC_000000001' |
|                  | cbsNumber                       | Issuer/CMS       | CHAR 64                                                                                                     |
| Card contract    | cardContractId                  | CMS              | NUMERIC                                                                                                     |
|                  | cardContractNumber              | Issuer/CMS       | Primary Account Number (PAN); 16 digits                                                                     |
|                  | cbsNumber                       | Issuer/CMS       | CHAR 64                                                                                                     |

Note: The account contract and card contract identifiers generated by the CMS are named `accountContractId` and `cardContractId`. If you encounter the `contractId` parameter, you must provide the `accountContractId` or `cardContractId`, depending on the object you want to manage. The `contractId` occurs when the operation is universal. A universal operation can handle either the account contract or the card contract. For example, to add an address to a card contract, provide the `cardContractId`. To add an address to an account contract, provide the `accountContractId`.

![](https://static.developer.mastercard.com/content/mastercard-processing-core/uploads/account-or-card-contract.jpg)
Tip: You should store the returned technical identifiers, such as `clientId`, `accountContractId`, and `cardContractId` generated by the CMS in your system to carry out other business operations on these objects in the future. To be able to do something with an already existing object, the API requires you to provide an object ID (technical CMS identifier) in the path of the operation (or sometime in the body of the request). For example, to set PIN on the card, you must use the `/cards/{card_contract_id}/pin` endpoint, where in the path, you need to place a unique identifier of the card contract object. Alternatively, if you have no possibility to store CMS technical IDs, you can use special API operations to retrieve those identifiers based on your own identifiers that you have passed during the object create request. For more information, refer to the [CMS identifiers search](https://developer.mastercard.com/mastercard-processing-core/documentation/use-cases/cms-identifiers-search/index.md) use cases.

## Classifiers {#classifiers}

Classifiers represent rules or restrictions set on the `client` or `contract` level (`accountContract` or `cardContract`), allowing flexible configuration of business processes:

* Classifiers make it possible to segment clients and contracts (separate clients and contracts into groups) depending on the current status of a `client` or `contract` (`accountContract` or `cardContract`)
* Classifiers make it possible to set conditions for executing various actions in the system depending on the current status of a `client` or `contract` (`accountContract` or `cardContract`)

Classifiers must be configured in advance during your onboarding configuration. The definition provides the code of the classifier and possible classifier values.

For example, a classifier can be used to trigger the contactless or Automatic Billing Updater (ABU) feature for the card:

| `classfierCode` |     `classifierValue`      |  For Object   |     Description      |
|-----------------|----------------------------|---------------|----------------------|
| CTLS_FLAG       | CTLS_FLAG_ON CTLS_FLAG_OFF | Card contract | Managing Contactless |
| ABU             | Y N                        | Card contract | Managing ABU         |

## Parameters {#parameters}

Parameters can store specific values impacting CRM actions, defining how issued card will be used by the end user. Some parameters are global, and some are specified on a certain level, such as account contract or card contract. Parameters can be pre-defined with default values or fully customized to your needs. A big part of the process of adjusting parameters to your needs takes part during onboarding. The Mastercard Processing API allows you to check your existing parameters and provide changes.

For example, CLOSE_PREV_PLASTIC -- with parameter values:

* A -- the system locks the old plastic when the reissued plastic is unlocked
* Y - when the first operation with new plastic is registered, the system locks the old plastic
* N -- default value which allows both the old and reissued plastics to be used

## Tariffs {#tariffs}

Tariffs are stores designed to keep numerical values separately, such as fees or interest rates. Updating values is much easier because your card product can be linked to those tariffs. You need not go deep into the configurations of each implemented product and contract separately.

Tariffs may be of various kinds, depending on what part of a card or account contract configuration they belong to. Some values may be defined in two ways, for example, usage limits - by limiters and usage type of tariffs. The Mastercard Processing API allows you to set only a few tariffs, although it allows you to check which tariffs were implemented so far during the onboarding process.

Tariffs in the CMS are bundled into domains, described, among others, by the level of personalization. 'Global' is the most general, and 'personal' is on the individual contract level. Domains are the only source of tariffs in the system. Domains might be linked to the contract directly through an event related to the contract, or simply different sets of parameters defined before issuing a card. Each tariff has a specified role and code which describes the related area of use. These include service limit, interest, ageing, and billing and a specific type which says about use inside the area. Both role and type should be reflected in the tariff type code, for example, 'INT_RATE_DEP_EUR'.

## Product Configuration for Account Contracts and Card Contracts {#product-configuration-for-account-contracts-and-card-contracts}

A setup of our CMS is customized for your needs during the onboarding process and will be available when you are ready to use the Production environment. One of the main parameters to be defined in the CMS is the product configuration for the account contract and the card contract.

The product determines the following properties:

* Type of card or account (for example, debit, credit, prepaid).
* Currency.
* Billing cycle.
* List of allowed transactions.
* Transaction processing rules.
* Interest accrual rules.
* Fee calculation rules (for example, card annual fee).
* Usage limits.
* And many more.

Some product properties are specific to the card contract, and others to the account contract. For example:

* **Card contract**: The product defines the BIN ranges eligible for a specific PAN range to be used in card issuing.
* **Account contract**: The product defines which card products can be created under a given account contract.

When the product configuration is ready, the CMS will generate unique values for each product. These values correspond with the `productCode` field in the account contract and the `productCode` field in the card contract. These fields are used for the `createAccountContract` and `createCardContract` operations.

An example of a basic product configuration is presented in the following table:

| **Currency** | **BIN** | **BIN lower range** | **BIN upper range** | **Card or account type** | **Card Contract `productCode` value in the CMS** | **Account Contract `productCode` value in the CMS** |
|--------------|---------|---------------------|---------------------|--------------------------|--------------------------------------------------|-----------------------------------------------------|
| EUR          | 510000  | 0000000000          | 0099999999          | Debit                    | STD-MCDEBVF-EUR                                  | STD-DEBCH-EUR                                       |
| PLN          | 510000  | 0100000000          | 9999999999          | Prepaid                  | STD-MCPREGPRD-PLN                                | STD-PRE-PLN                                         |