Cards

API Documentation

Cards are the payment instruments that cardholders use to access the funds or credit associated with their card account.

Column supports both physical cards (plastic cards that can be carried in a wallet) and virtual cards (digital card credentials that exist only electronically).

Each card is linked to a specific card account and inherits the rules, limits, and functionality defined at both the program and account levels.

Card Types

Virtual Cards

Virtual cards are digital payment credentials that exist only electronically, offering immediate issuance capabilities and enhanced security to securely deliver card credentials to your customers.

Physical Cards

Physical cards are plastic payment cards that cardholders can carry in their wallet.

Column partners directly with card manufacturers to handle the entire physical card fulfillment process. This covers every stage—from card personalization, to secure production, and shipping to cardholders.

Each physical card is produced from a card template that belongs to its card program. To see the templates you can choose from, list the card program's card templates. Pass a template's id as card_template_id when creating a card to choose one; otherwise the card program's default_card_template_id is used. The card's card_template_id field returns the template it was created with, and renewed and replaced cards keep the original card's template.

Once the card manufacturer ships a physical card, Column emits an issuing.card.shipped event. The card's manufacturing_details.shipping_details includes the shipment's carrier and tracking_number when the manufacturer has reported them.

Card Description

Pass description when creating a card, or update it later, to label the card for your own reference (for example, "Marketing team travel card"). It's up to 255 characters and returns as an empty string when unset. Pass an empty string on update to clear it. Renewed and replaced cards keep the original card's description.

Card Renewal and Replacement

Renewal

Renewals are used when a card is approaching expiration and you want a seamless transition for the cardholder. A renewed card is issued as a successor to the existing card. The original card remains usable until the renewed card is activated. Upon activation of the renewed card, the original card is automatically deactivated with the deactivation reason renewed, and its card tokens are moved to the renewed card, preserving continuity for the cardholder. If the renewed card is created as active, this happens immediately.

Replacement

Replacements are used when a card is lost, stolen, fraudulent, or voluntarily replaced by request. During replacement, the original card is deactivated as part of the operation and linked to the new card as the replacement target to ensure immediate protection.

PINs on Renewed and Replaced Cards

For debit card programs, the original card's PIN carries over when the new card keeps the original card number, so the cardholder doesn't need to set it again:

A PIN is tied to its card number, so it can't carry over to a new one. To give a replacement with a new card number a PIN, pass encrypted_pin; the cardholder can choose the same four digits as before. If you leave it out, the replacement has pin_status set to unset. It works for transactions that don't require a PIN, and transactions that do decline with decision reason pin_not_set until you update the card's PIN. A wrong PIN declines with pin_invalid.

On any renewal or replacement, passing encrypted_pin sets that PIN instead, and on a program with PIN reveal enabled, passing "generate_pin": true has Column choose a new one. To create a card that keeps its card number without a PIN, pass "SKIP". If the original card had no PIN, a carried-over card has none either. A renewal copies the PIN when it is created, so a PIN change on the original card after that point doesn't reach the renewed card.

When the PIN carries over, a block doesn't: the new card's PIN starts unblocked with no wrong attempts counted, even if the original card's PIN was blocked, and the new card emits issuing.card.pin_set. The original card keeps its own PIN state. A carried-over PIN is in effect an unblock, so if a blocked PIN should require the cardholder to choose a new one, pass encrypted_pin with the PIN they choose, "generate_pin": true for a new random PIN on a program with PIN reveal, or "SKIP" to issue the card without a PIN. A replacement with a new card number has no PIN unless you pass one, so there is no block to carry over.

Removing a PIN

To remove a debit card's PIN, delete the card's PIN. The card then works for transactions that don't require a PIN, and transactions that do will decline until you update the card's PIN. The card's pin_status becomes unset. Deleting the PIN of a card that has none succeeds, so the request is safe to retry. As with a PIN change, deleting the PIN on the original card doesn't affect a renewed card that already exists.

Unblocking a PIN

A card's PIN is blocked after 3 wrong PINs in a row on transactions. To unblock it without changing it, for example after you verify the cardholder, unblock the card's PIN. Unblocking clears the block and the count of wrong PINs, sends an issuing.card.pin_unblocked event, and returns the card. Unblocking a card whose PIN isn't blocked succeeds without an event, so the request is safe to retry.

Renewing or replacing a card with a blocked PIN also gives the new card an unblocked PIN when the PIN carries over; see PINs on Renewed and Replaced Cards.

Revealing a PIN

If PIN reveal is enabled for the card program, the card reveal SDKs can show a debit card's PIN to the cardholder, including a PIN Column chose with generate_pin. PINs set before PIN reveal became available can't be revealed until the PIN is set again.

PCI Compliance

The card number (PAN) and CVV2 are under PCI scope. The card object and the endpoints that return it never include them. The card object includes last_four_digits so you can identify a card without the full number.

The only way to show the full card details, and on programs with PIN reveal the PIN, is the reveal flow, which displays them to the cardholder through Column's card reveal SDKs for the web and React Native. Your server calls POST /issuing/cards/:card_id/reveal-tokens to create a single-use, short-lived reveal token. The SDK uses that token to fetch the card details from Column, encrypted end to end, and displays them inside Column's own iframes or components, so the card number and CVV2 never pass through your systems.

Statuses and Events

Statuses

Events

Card event payloads contain the card object.

A card created without a PIN emits no PIN event, and its issuing.card.created payload has pin_status: unset. Deleting the PIN of a card that has none emits no event either.

Renewing or replacing a card creates a new card, which emits its own issuing.card.created event. The original card emits issuing.card.inactive when it is deactivated.