Card APIs

Card creation

Integration flow of card creation between External system and LightCMS:

Step	Call	Direction	API contract	Details
1	GET /v3/cpds	External system -> LightCMS	Provided	External system gets list of Card product definitions
2	GET /v3/cpds/{code}	External system -> LightCMS	Provided	External system gets detail of CPD for new card
3	POST /v3/cards	External system → LightCMS	Provided	External system sends request to LightCMS to create card
4	POST /v3/cardCreateRequest	LightCMS → External system	Required	LightCMS sends request to external system mastering the card account (typically Core banking system - CBS) to register the card and its accounts. This step is optional for LightCMS.
5	POST /v3/cards/cardCreateResponse	External system → LightCMS	Provided	External system confirms that it has registered the new card on its side. This step is needed only if the previous step was executed.
6	PUT /v3/cards/{id}/activate	External system -> LightCMS	Provided	External system activates the physical card. It is not needed for Digital cards.
7	POST /v3/cardEvent	LightCMS → External system	Required	LightCMS sends notification about new card creation.

1. Get list of Card product definitions

External system gets list of available Card product definitions (CPDs) from LightCMS via GET /v3/cpds endpoint, the successor of a deactivated CPD via GET /v3/cpds/{code}/successor. CPD code is mandatory in the card creation request.

2. Get detail of Card product definition

External system gets detail of CPD for which the new card will be created. Detail contains limits and restrictions allowed for the CPD.

3. Card creation request

External system calls POST /v3/cards endpoint with the card, holder, accountsInfo, delivery, limits and restrictions data.

• card.cpdCode — the Card product definition (CPD) of the card. It has to be a currently valid CPD; LightCMS does not resolve CPD successors on card creation, so a deactivated CPD is rejected.
• holder — the cardholder, always a person. If a holder with the same holderExternalId already exists in LightCMS, the existing holder is used and its data are not updated from the request (use POST /v3/subjectUpdate for that).
• accountsInfo.accountOwner — the owner of the accounts, a person or a company (subjectType); the required fields depend on the subject type. As with the holder, an existing account owner is not updated.
• accountsInfo.accounts — at least one bank account linked to the card. An account that already exists in LightCMS must belong to the given account owner, otherwise the request is rejected. If accountCurrency is omitted, the card is linked to both the CZK and the EUR currency component of the account.
• delivery — deliveryAddress is required for POST and deliveryPoint (branch code) for BRANCH; neither is allowed for other delivery types.
• limits and restrictions — optional. The card gets all limits and restrictions defined in the CPD with their default values; the request only overrides some of them. Each overridden limit/restriction must be defined in the CPD, must allow modification by the customer, and may be listed only once. A limit value must be between 0 and the maximum set by the CPD. They can be changed later via PUT /v3/cards/{id}/limits and PUT /v3/cards/{id}/restrictions.

LightCMS returns the ID of the new card (cardId), which identifies the card in all other card APIs. The card number is not known yet at this point — it is assigned by the card processor later and can be read via GET /v3/cards/{id}.

LightCMS issues the card creation with card processor.

4. LightCMS asks external system mastering the card account to register the card

Once the card has been issued with the card processor, LightCMS calls POST /v3/cardCreateRequest endpoint on external system which is master of card account (typically Core banking system - CBS) to ask it to create the card.

It carries X-Message-Type: CreatedCard, and the newCard object.

• External system only acknowledges receipt immediately — this call is asynchronous, the actual result is reported in step 5. If the receipt is not acknowledged, LightCMS repeats the call several times (4 retries are commonly configured).

5. External system reports the outcome

Once external system (CBS) has processed the request from step 4, it should call POST /v3/cards/cardCreateResponse endpoint on LightCMS with the card object — cardId, cardProcessorId and the linked accounts with their accountProcessorId.

• echo the X-Dobito-TraceId value LightCMS sent in step 4, if it was sent — the result itself is matched to the card by cardId
• x-idempotency-key acts as a deduplication key — a call repeated with the same key is recorded only once, so a call that failed can safely be repeated
• the call is a confirmation, it carries no success/failure flag — the card stays in CONFIRMING status until LightCMS receives it

Once the confirmation is processed, the card leaves the CONFIRMING status and goes to final status defined on the CPD:

• virtual cards (VIRTUAL, VIRTUAL DISPOSABLE technologies) become ACTIVE,
• physical cards become DIGITALLY_ACTIVE if they can be tokenized, otherwise INACTIVE (waiting for activation via PUT /v3/cards/{id}/activate).

6. Card activation

If the card is physical it has to be activated via the PUT /v3/cards/{id}/activate endpoint. Digital cards do not need to be activated. It is activated automatically.

7. LightCMS notifies the outcome

When the card reaches ACTIVE or DIGITALLY_ACTIVE status, LightCMS calls POST /v3/cardEvent on external system with eventType: CARDCREATED and the card data — including the masked pan and cardProcessorId assigned by the card processor. This is fire-and-forget — no result callback is expected.

Info

No notification is sent for a card that ends up INACTIVE.

Card blocking

Card can end up blocked through the external API in two ways:

• external system blocks it directly
• LightCMS blocks it on its own based on card's account status change received from external system (CBS usually)

Step	Call	Direction	API contract	Details
1a	POST /v3/cards/{id}/block	External system → LightCMS	Provided	External system asks LightCMS to block a specific card
1b	POST /v3/accountUpdate	External system (CBS) → LightCMS	Provided	External CBS reports the linked account is no longer ACTIVE; LightCMS blocks every card linked to this account that has no other ACTIVE account
2	POST /v3/cardEvent	LightCMS → External system	Required	LightCMS produces notification to external system that the card is BLOCKED

1a. Block a specific card

External system calls POST /v3/cards/{id}/block with reason and requestedBy.

A card can carry several simultaneous blocks (e.g. one from BANK and one from HOLDER, or several reasons at once) — it stays blocked until every one of them is lifted.

LightCMS returns the ID of the block (blockId), which is needed to lift that specific block later.

LightCMS also blocks the card at card processor as part of this call, so authorization stops immediately.

1b. Card blocked as a side effect of its account being blocked

Rather than blocking the card directly, the external CBS can report that the account changed status — LightCMS then blocks every card linked only to that account (a card linked to another account that's still ACTIVE is left alone). Call POST /v3/accountUpdate with accountStatus set to BLOCKED or REVOKED.

2. LightCMS notifies the outcome

Either path ends the same way: once the card reaches BLOCKED, LightCMS calls POST /v3/cardEvent on external system with eventType: CARDBLOCKED, the resulting card.status and blockReason. This is fire-and-forget — no result callback is expected, and it's the same notification channel used for every other card status change.

Card unblocking

External system calls POST /v3/cards/{id}/unblock/{blockId} with requestedBy, targeting the specific blockId returned when the block was created.

• Unblocking is only permitted for a card in BLOCKED state whose account is ACTIVE. The card returns to ACTIVE (or DIGITALLY_ACTIVE if it has no card plastic yet).
• If the card carries other, still-active blocks, it remains BLOCKED after this call succeeds — every block must be individually lifted.
• LightCMS notifies external system via POST /v3/cardEvent (eventType: CARDUNBLOCKED) once the card's status changes

Card replacement

Replacing a card creates a new successor card and revokes the original one. The successor card goes through the same registration with the external CBS as a newly created card:

Step	Call	Direction	API contract	Details
1	POST /v3/cards/{id}/replace	External system → LightCMS	Provided	External system asks LightCMS to replace a specific card
2	POST /v3/cardCreateRequest	LightCMS → External system	Required	LightCMS asks the external system which is master of the card account to register the successor card. This step is optional for LighCMS.
3	POST /v3/cards/cardCreateResponse	External system → LightCMS	Provided	External system confirms that it has registered the successor card on its side. This step is needed only if the previous step was executed.
4	POST /v3/cardEvent	LightCMS → External system	Required	LightCMS notifies the external system about the successor card (CARDRENEWED) and the revoked original card (CARDREVOKED)

1. Card replacement request

External system calls POST /v3/cards/{id}/replace with the ID of the card being replaced and the card, delivery, limits and restrictions data for the successor card.

• Replacement is only permitted for a card in DIGITALLY_ACTIVE, ACTIVE, BLOCKED, CANCELLED state, or REVOKED state when it was not revoked because of an earlier replacement (a card can be replaced only once).
• The successor card gets the latest successor of the replaced card's CPD (see GET /v3/cpds/{code}/successor). A card whose CPD creates cards in INACTIVE state cannot be replaced.
• The successor card takes over the holder, the linked accounts (with their priorities) and the digital tokens of the replaced card.
• delivery follows the same rules as on card creation — deliveryAddress is required for POST, deliveryPoint for BRANCH. A deliveryAddress also updates the holder's postal address.
• limits and restrictions follow the same rules as on card creation. Values not provided in the request are taken over from the replaced card, the rest from the CPD. They can be changed later via PUT /v3/cards/{id}/limits and PUT /v3/cards/{id}/restrictions.

LightCMS returns the ID of the successor card (cardId). The successor card is created in LightCMS in status CONFIRMING and LightCMS issues it with the card processor. At the same time the replaced card is revoked with reason REPLACEMENT, so it stops authorizing transactions (if the replaced card is already REVOKED or CANCELLED, only its revocation reason is changed to REPLACEMENT).

2. and 3. Registration of the successor card with external CBS

Identical to steps 2 and 3 of Card creation — LightCMS calls POST /v3/cardCreateRequest with the successor card (X-Message-Type: CreatedCard) and the external CBS reports the outcome via POST /v3/cards/cardCreateResponse.

4. LightCMS notifies the outcome

LightCMS calls POST /v3/cardEvent on your system:

• eventType: CARDRENEWED for the successor card, once it reaches ACTIVE, DIGITALLY_ACTIVE or BLOCKED status.
• eventType: CARDREVOKED for the replaced card, once it reaches REVOKED status (not sent when the replaced card was already REVOKED or CANCELLED).

Card revocation

Revocation permanently terminates a card — a revoked card is immediately stopped from authorizing any transaction and can never be activated or unblocked again. If the cardholder needs a working card afterwards, it has to be replaced.

Step	Call	Direction	API contract	Details
1	POST /v3/cards/{id}/revoke	External system → LightCMS	Provided	External system asks LightCMS to revoke a specific card
2	POST /v3/cardEvent	LightCMS → External system	Required	LightCMS notifies the external system that the card is now REVOKED (or CANCELLED)

1. Revoke a specific card

External system calls POST /v3/cards/{id}/revoke. The request has no body.

• A card in ACTIVE, DIGITALLY_ACTIVE or BLOCKED state ends up REVOKED, with revocation reason PERMANENTLY_BLOCKED.
• A card that was not yet activated (INACTIVE) ends up CANCELLED instead.
• LightCMS revokes the card with the card processor as part of this call and invalidates all its card plastics.
• A card that is already revoked cannot be revoked again.

Cards are also revoked automatically by LightCMS — after the end of card validity (reason AFTER_VALIDITY) and when the card is replaced (reason REPLACEMENT, see Card replacement). The list of revocation reasons can be retrieved via GET /v3/enumeration/revokeReasons.

2. LightCMS notifies the outcome

Once the card reaches its final state, LightCMS calls POST /v3/cardEvent on your system with eventType: CARDREVOKED and the resulting card.status (REVOKED, or CANCELLED for a card that was not yet activated). This is fire-and-forget — no result callback is expected.