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:
- The
user
is in statusactive
. This happens once a user successfully clears KYC. See creating a KYC - The
wallet
associated with this user is in statusactive
. 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 |
Card tokenization
Cards can be added to Apple Pay and Google Pay wallets. Any API user who wants to allow tokenization of virtual or physical cards will have to enroll onto the Apple Pay / Google Pay program.
There are 2 ways of adding a card to a digital wallet.
Manual provisioning
A user can enter the card details manually in the digital wallet. Based on the level of risk determined, additional authentication may be needed from the end user. Two forms of authentication are supported - activation code and app to app authentication. Both should be supported.
- The user adds the card in the digital wallet
- In most cases, authentication is needed. The user is presented 2 options to authenticate
The user chooses to authenticate with your app
- The user is redirected to your app (a redirect method is configured per platform)
- The user is authenticated in app, most clients ask the user to sign a transaction.
- Call Kulipa's tokenization activation endpoint to activate
- Respond to the Digital Wallet with success
- Digital Wallet verifies the token is now active with the card scheme
The user chooses to authenticate via email
- The Digital Wallet sends a request to the card scheme to generate an activation code
- Kulipa receives this request and sends a webhook to you with the activation code
- You send an email with the activation code
- The user inputs the activation code in the digital wallet
- Card scheme verifies the code and activates the token
Push provisioning
Your app can have a button to push the card into the digital wallet. Because it originates from your app, no additional authentication is needed from the end user. The capability is provided by the digital wallet.
- Call the appropriate endpoint at Kulipa to generate the tokenized data (Apple/Google Pay)
- Use the returned data with Apple/Google SDK to push the card details to the digital wallet
- Card scheme verifies that the correct information is received from the digital wallet and activates the card tokenization
Note: Apple and Google Pay are not available in all countries. For a complete list, please refer to Apple's or Google's documentation.
NOTE: The complete end to end flow can only be done in the live environment.