Cards

Kulipa cards lifecycle and API usage

Introduction to Cards

Using Kulipa API, payment cards can be issued for users. When issuing, we refer to the user as the card owner.
There may be a different name on the card itself, and so we refer to the name on the card as the card holder.

There can be virtual and physical cards, and digital (tokenized) cards can be attached to each for mobile wallets such as Apple Pay. See the Cards section to learn about specific types of cards.

Preconditions

In order for a user to be eligible to create cards under their account, two preconditions must be met:

1. The user is in status active. This happens once a user successfully clears KYC. See creating a KYC
2. The wallet associated with this user is in status active. This is done by verifying the wallet

If a card is attempted to be created prior to these conditions being met, the system will respond with an error message.

Card

A card represents a set of identifiers that can be used for purchases. These identifiers include the PAN ("long number"), expiry date, CVV (3-4 additional digits), and in the case of physical cards, cryptographic data stored on the chip.

Cards have different form factors. They can be virtual - stored and displayed in the mobile app only - or they could additionally have a "physical" plastic/metal card with chip and pin, shipped to the user. A card can additionally be tokenized and pushed to Apple/Google pay - we call that a digital card.

Furthermore, when a card is deactivated (for example, lost or expired) and a replacement card is issued, it is operationally a completely separate card with a new ID, and likely a different CVV and expiry date. Over time, expect many cards to be accumulated under a user account, some of which are no longer active.

A card is bound to a monthly (rolling 30-day) limit, typically set at $10,000.

As for the different card types, here are some of the differences between them:

Aspect	Virtual Cards	Physical Cards	Digital Cards (tokenized)
Requirements to create	KYC'd user	KYC'd user	Existing active virtual or physical card
Requires shipping	No	Yes	No
Can be suspended/lost/stolen	Yes	Yes	No
Can be turned off by owner	Yes	Yes	No
Activation method	Active by default	Via API	Active by default
Has a user-visible long number	Yes	Yes	No
Can be displayed in mobile app	Yes	Yes	No
Can be tokenized for a wallet	Yes	Yes	No - it is itself a tokenization

Card status

A card can have any of the following statuses:

• Inactive: The card has been issued but not yet activated by the holder.
• Active: The card is currently usable.
• Frozen: The card was temporarily frozen. New transactions are rejected.
• Revoked: Any of these four statuses are considered a revoked card:
  • Cancelled: The card was cancelled and is no longer active.
  • Lost: The card was reported lost (or damaged). No longer usable.
  • Stolen: The card was reported stolen. No longer usable.
  • Expired: The expiration date has passed for this card and it is no longer usable.

Card lifecycle

By default, new physical cards are marked as inactive. Virtual cards are active by default. Digital cards can be created and attached to either a virtual or physical active card, and are activated as part of pushing them into the mobile wallet.

Cards can be created, frozen, and revoked via API calls.

User action	Card state (previous)	Card state (next)
Create a physical card	[None]	Inactive
Create a virtual card	[None]	Active
Create a digital (tokenized) card	[None]	Active
Activate with code	Inactive	Active
Freeze	Active	Frozen
Unfreeze	Frozen	Active
Revoke	Active/Frozen	Revoked

See also

• Create Cards