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.

card hierarchy, visualization of table below

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 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
(for example, it will likely have a different CVV and expiry date), and so over time, there will be many cards accumulated under a user account,
some of which are no longer active.

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

AspectVirtual CardsPhysical CardsDigital Cards
Requirements to createKYC'd userKYC'd userExisting active virtual or physical card
Requires shippingNoYesNo
Can be suspended/lost/stolenYesYesNo
Can be turned off by ownerYesYesNo
Activation methodActive by defaultVia APIActive by default
Has a user-visible long numberYesYesNo
Can be displayed in mobile appYesYesNo
Can be tokenized for a walletYesYesNo - 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.
  • Cancelled: The card was cancelled and is no longer active.
  • Frozen: The card was temporarily frozen. New transactions are rejected.
  • 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.
    We collectively think of Frozen as Blocked. Lost, Stolen, Cancelled, or Expired cards are all Revoked.

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.

πŸ“˜

Info

There are endpoints available to manage the status of a card by activating, blocking, or revoking it at any point.

card lifecycle, visualization of table below
User actionCard state (previous)Card state (next)Comments
Create a physical cardInactiveInactiveGoes through shipping states: Issued, Ordered, Shipped, Delivered
Activate with codeInactiveActive
BlockActiveBlocked
UnblockBlockedActive
RevokeActive/BlockedRevoke

A card is bound to the spending controls set and has additional unique properties which include:

  • Physical cards have a shipping status.
  • A card can be digital when it is pushed to a wallet via a method called "tokenization".

To see all unique fields, see the detailed API spec for cards.

Spending controls

Card spending restrictions can be placed to regulate card expenditures and reduce fraudulent activities by setting limits on a card.

A restriction can include either or both of these guidelines:

  • A total amount of money that can be spent within a given time period
  • A total number of transactions that can be made within a given time period

For instance, a restriction can be set allowing a card to expend a maximum of $1200 monthly (for all cards combined).
When numerous limitations can be applied to a single card, it is enough that one limit's criteria is met for the transaction to be declined.

For example:

  • Set a daily expenditure cap of up to $1200.
  • Set a monthly expenditure cap of $800.
    The latter restriction is more stringent, and so the aggregate spend of the card will be capped at $800 per month and the card could never actually spend $1200 in a day.

Each card operates with a unique set of spending restrictions which are applied to the card and any digital version of the card in all wallets.

Examples:

{
  "id": "f70721da-adc8-49b4-887d-e93db0d3bd38",
  "type": "velocityLimit",
  "description": "Limit a single transaction to no more than $100",
  "amount": 1200,
  "velocityWindow": "perTransaction",
  "createdAt": "2023-08-07T08:46:01Z",
  "updatedAt": "2023-08-07T10:12:48Z"
}
{
  "id": "82d9cf93-a277-459c-9522-89ffbb9faf37",
  "type": "velocityLimit",
  "description": "Overall limit to $8000 per month",
  "amount": 8000,
  "velocityWindow": "monthly",
  "createdAt": "2023-08-07T08:46:01Z",
  "updatedAt": "2023-08-07T10:12:48Z"
}
{
  "id": "82d9cf93-a277-459c-9522-89ffbb9faf37",
  "type": "velocityLimit",
  "description": "No more than 10 transactions per day",
  "maxTransactions": 10,
  "velocityWindow": "daily",
  "createdAt": "2023-08-07T08:46:01Z",
  "updatedAt": "2023-08-07T10:12:48Z"
}