Cards

Replace card

Replace a card and automatically deactivate the original. The response contains the new replacement card; retrieve the original card to see its deactivation_reason and replacement_card_id.

Requested reason	PAN	Original card's recorded reason	Original card's tokens
lost, stolen, fraud, voluntary	New PAN	Requested reason	Deactivated
damaged	Reused	damaged	Deactivated
expired	Reused	renewed	Deactivated

All non-terminal tokens on the original card are deactivated for every replacement reason, including when the PAN is reused. Reusing the PAN increments sequence_number. An expired replacement records renewed as the reason, but does not preserve tokens. The separate renew endpoint migrates tokens when the renewal card is activated. renewed and account_closed are not valid replacement request reasons and return HTTP 400. A card can't be replaced as damaged or expired if any card with the same PAN was deactivated as lost, stolen, or fraud.

patch/issuing/cards/{card_id}/replace

Request

Base URL: https://api.column.com
URL: https://api.column.com/issuing/cards/{card_id}/replace
Auth: HTTP basic

Path parameters

card_idstring required

Headers

Idempotency-Keystring

Idempotency keys can be up to 255 characters long and are case sensitive. Column reserves the right to expire idempotency keys after 30 days. Only ASCII printable characters (code 32 - 126) are allowed for idempotency keys.

Request body

Reason for deactivating the original card during replacement. lost, stolen, fraud, and voluntary requests create a replacement with a new PAN. damaged requests reuse the PAN. expired requests are processed as renewal-style replacements with the same PAN and a new expiration, and the original card's reason is recorded as renewed. All non-terminal card tokens on the original card are deactivated for every reason. renewed and account_closed are not accepted by this endpoint.

encrypted_pinstring

Debit card programs only. expired and damaged replacements reuse the PAN, so omitting this keeps the original card's PIN. lost, stolen, fraud, and voluntary replacements get a new PAN, which the original PIN can't carry over to, so this is required for them. Pass a base64-encoded encrypted PIN to set a new PIN, or SKIP to create the replacement without a PIN and set one later with PATCH /issuing/cards/{card_id}/pin.

expiration_monthinteger

Optional expiration month (1-12)

expiration_yearinteger

Optional expiration year (4-digit year, e.g. 2025)

statusstring

Optional status for the replacement card

Example request

{
  "deactivation_reason": "lost",
  "expiration_month": 12,
  "expiration_year": 2029,
  "status": "active"
}

Response

Successful response

authorized_user_entity_idstring required

The ID of the person entity authorized to use this card

binstring

The 6 or 8-digit BIN (Bank Identification Number) for the card

card_account_idstring required

The ID of the card account

card_authorization_policy_idstring

The ID of the card authorization policy

card_program_idstring required

The ID of the card program

card_template_idstring nullable

The ID of the card template the physical card was created with: the card_template_id from the create request, or the card program's default card template when none was given. Renewed and replaced cards keep the original card's template. This field is null for virtual cards.

created_atstring date-time required

The creation date of the card

deactivated_atstring date-time nullable

The timestamp when the card was deactivated

The reason this card was deactivated. Null until deactivation. When a card is replaced, this reason is recorded on the original card, not the new replacement card. Historical cards may return an inferred reason; generic legacy deactivations are reported as voluntary.

expiration_monthinteger required

The expiration month of the card (1-12)

expiration_yearinteger required

The expiration year of the card (4-digit year, e.g. 2025)

first_activated_atstring date-time nullable

The timestamp when the card was first activated

idstring required

The ID of the card

last_active_atstring date-time nullable

Timestamp when the card was last set to active status

last_four_digitsstring required

The last four digits of the card PAN

last_inactive_atstring date-time nullable

Timestamp when the card was last set to deactivated status

last_paused_atstring date-time nullable

Timestamp when the card was last set to paused status

original_card_idstring nullable

The ID of the card that this card replaced. Populated on the replacement card

platform_idstring required

The ID of the platform that owns this card

replacement_card_idstring nullable

The ID of the card that replaced this one. Populated on the original card after replacement

sequence_numberinteger required

The sequence number of the card. Starts at 1 for new cards and increments when a card is renewed (same PAN, new expiration). Resets to 1 when a card is replaced (new PAN)

status'active' | 'paused' | 'deactivated' required

The current status of the card. Possible values: active, paused, deactivated

typestring required

The form factor of the card. Possible values: virtual, physical.

Example response

{
  "bin": "41234567",
  "card_account_id": "cacc_2x8gszy5folpA9s0TOCseE9ABDM",
  "card_authorization_policy_id": "caup_2x8gszy5folpA9s0TOCseE9ABDM",
  "card_program_id": "cpgm_2x8gszy5folpA9s0TOCseE9ABDM",
  "card_template_id": "ctmp_2x8gszy5folpA9s0TOCseE9ABDM",
  "expiration_month": 12,
  "expiration_year": 2029,
  "id": "card_2x8gszy5folpA9s0TOCseE9ABDM",
  "last_four_digits": "1234",
  "manufacturing_details": {
    "shipping_details": {
      "name": "Oliver Hockey"
    }
  },
  "sequence_number": 1,
  "type": "physical"
}

Changes

No recorded changes to this operation across all 1 revision of this API.