Cards

The cards section covers all partner-facing card operations. The endpoints here are shared across B2B and Individual account types — both go through the same assertPartnerCardOwnership('id') middleware before the underlying IT-Card controller runs.

The data of a card

Each AccountCard document in CIP is the local mirror of a card held by IT-Card. It carries the partner view of the card and links back to the owning account:

Field group	Fields
Identity	cardKey (immutable IT-Card identifier), cardMask (e.g. 411111******1111), name, embossedName1, embossedName2
Type	type — VIRTUAL or PHYSICAL; kind — DEBIT, CREDIT, or PREPAID
State	status (see lifecycle below), statusCode (IT-Card-native code), expDate (MM/YYYY)
Ownership	ownerType (b2b / individual), ownerId, partnerId
Currency	currency (3-letter ISO), cardCurrency
Restrictions	isRestricted, restrictionType, restrictionReason
Card program	cardProgram, cardProgrammeType, cardType, cardScheme, cardBin
Delivery	deliveryAddress, deliveryMethod, deliveryType (one of COURIER, LETTER, REGISTERED_LETTER, COURIER_BRANCH, CARD_DEPARTMENT, ORDERING_COMPANY, NONE)
Personalisation	design, cardImage, cardImageId

The cardKey is the only stable identifier you should ever use — cardMask and name are mutable.

Card lifecycle

Cards cycle through nine states defined by IT-Card. CIP groups them into three logical buckets:

Active & usable

Status	Meaning
ORDERED	Card record exists in IT-Card but the plastic hasn't been produced yet (physical only).
ACTIVE	Card is live and can transact.

Inactive — recoverable

Status	Meaning
LOCKED	Temporarily locked by the partner. Reversible via POST /cards/:id/unlock.
INACTIVE	Issued but never activated. Reversible via POST /cards/:id/activate.
RESTRICTED	Generic apply-restriction flag (lost / stolen / fraud); reversible by the issuing party.
BLOCKED	Hard-locked by an admin (PayNovus or B2B). AdminBlockRole decides who can lift it.

Inactive — terminal

Status	Meaning
EXPIRED	expDate has passed. Card is no longer usable.
CLOSED	Card is closed (either voluntarily or after a resign/replace). Final.

Restriction types

The RESTRICTED umbrella covers lost, stolen, closed, fraud, and mobile-lost. Each is its own endpoint under /cards/:id/restrict-*. The restrictionType is stored on the card record.

Tenant scoping

Every route under /cards/:id/... runs through assertPartnerCardOwnership:

1. Reads :id (a cardKey returned by IT-Card) from the URL
2. Resolves the card's owning account (B2BAccount or IndividualOnboarding)
3. Verifies the owning account's partnerId matches req.auth.partnerId
4. Returns 403 Forbidden if the partner doesn't own the card

Sub-router pattern

The partner router mounts a sub-router at /cards/:id with mergeParams: true, so req.params.id is populated before the ownership middleware fires. This pattern is used so that assertPartnerCardOwnership('id') is declared once for all 28+ card paths.

GET /cards (no :id) is registered on the outer router and returns a partner-wide listing without the ownership middleware.

The expDate field

Most card actions require an expDate payload field. The format is MM/YYYY (e.g. 07/2029). It acts as a second factor on sensitive operations — a stolen API key alone is never enough.

Sensitive operations

Endpoints marked sensitive in this section (CVV, PAN, 3DS, PIN, holder authorize) are rate-limited and audited. They should only be called from trusted backend environments — never from a browser or mobile app. See the Sensitive data → page for the full rationale.

Conceptual groups

Group	What it covers
Details & status	Reading the card record and current status.
Lifecycle	Lock, unlock, activate, temporary lock.
Restrictions	Mark a card as lost, stolen, closed, fraud, mobile-lost, or generic restrict.
Rename/replace	Nickname, embossed name, full card replacement, and resign.
Sensitive	CVV, PAN, 3DS management, PIN lifecycle, holder authorize. Rate-limited and audited.
Limits	Read and update per-card spending limits.

For the exact endpoint shapes, parameters, and the Try it widget, see the List of endpoints → page.