Freeze, replace, close

Most card support actions come down to four operations: freeze, unfreeze, replace, and close.

Freeze and unfreeze can be reversed. Replace and close are permanent.

Before you begin

You'll need an issued card.

How it works

Action	Endpoint	Reversible	Use when
Freeze	POST /v1/cards/{id}/freeze	Yes	Card is misplaced, a charge is being disputed, or the card needs a temporary suspension
Unfreeze	POST /v1/cards/{id}/unfreeze	Yes	The reason for freezing the card has passed
Replace	POST /v1/cards/{id}/replace	No	Card is damaged, lost, stolen, compromised, or expiring
Close	POST /v1/cards/{id}/close	No	Cardholder has left or the card is no longer needed

All four endpoints accept an Idempotency-Key. Always send one. For example, it prevents a double-click on a "Freeze" button from creating duplicate requests.

Steps

Freeze and unfreeze

curl -X POST "$ALETA_BASE_URL/v1/cards/card_01HX8ZQ2K4M7P9RSTVWXYZAB/freeze" \
  -H "Authorization: Bearer $ALETA_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Once the card is frozen, new authorizations are declined. Unfreezing takes effect just as quickly.

Freezing doesn't change the card balance or the funding account, and it doesn't release existing authorization holds. A transaction that was already held before the freeze can still settle normally when the merchant clears it.

Replace

Replacing a card issues a new card for the same cardholder and account, then closes the current one. The new card is returned in the response.

curl -X POST "$ALETA_BASE_URL/v1/cards/card_01HX8ZQ2K4M7P9RSTVWXYZAB/replace" \
  -H "Authorization: Bearer $ALETA_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason": "compromised"}'

Response, with a new id

{
  "id": "card_01HX8ZQ2K4M7P9RSTVWXYZCD",
  "object": "card",
  "form_factor": "virtual",
  "status": "pending",
  "reference": "user-4471-card-1",
  "created_at": "2026-08-02T10:14:00Z"
}

reason must be one of lost, stolen, damaged, expired, compromised, or other.

Not every program can replace a card. Where the processor has no replacement, the call is refused with operation_unsupported. To replace a lost or stolen card there, close it and issue a new one.

Keep these things in mind when replacing a card:

• The replacement has a new id, card number, and expiry date, and keeps the original's reference. Update anything in your system that references the old card.
• The replacement is issued like any other card. It is pending in the response, then inactive on card.issued. Activate it with POST /v1/cards/{id}/activate before it can be used.
• The original is closed and emits card.closed. If the cardholder uses the card in a phone wallet, they'll need to add the replacement card again.
• If the call fails with processor_unavailable, read the original card before you try again, so a replacement isn't issued twice.

Close

curl -X POST "$ALETA_BASE_URL/v1/cards/card_01HX8ZQ2K4M7P9RSTVWXYZAB/close" \
  -H "Authorization: Bearer $ALETA_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Closing a card is permanent. The card enters its terminal state and emits card.closed.

Closing doesn't affect the funding account. Its balance stays where it is, and other cards linked to the account continue to work. To move money out of the account, see funding and defunding.

Choosing between freeze, replace, and close

Situation	Action
"I've misplaced my card. It's probably somewhere in the house."	Freeze
"I found it."	Unfreeze
"It's definitely gone." / "It's damaged."	Replace
"There are charges I didn't make."	Freeze, then replace once confirmed
Employee leaves	Close
Card expires in 30 days	Replace, based on the card's expires_at

When you're unsure, freeze first. It's reversible. Replace when the card needs to be retired and issued again, and use close when the card is permanently finished.

Common errors

Status	code	Fix
400	missing_parameter	Replace: reason wasn't sent, or delivery_address is missing on a physical replacement
400	invalid_parameter	Replace: reason isn't one of the values above
404	card_not_found	The card doesn't exist, or belongs to another organization
422	card_invalid_state	Freezing a card that isn't active or is already frozen; unfreezing one that isn't frozen; or freezing or unfreezing an expired card. The message names the state
422	card_closed	The card is permanently closed, including closing or replacing it again
422	card_not_provisioned	Close or replace on a card the processor hasn't issued yet (pending). Wait for card.issued
422	unsupported_form_factor	Replace: the form_factor you named isn't one the program issues
422	operation_unsupported	Replace: this program's processor can't replace a card. Close it and issue a new one
502	processor_unavailable	The processor couldn't complete the call and the card is unchanged. Retry with the same Idempotency-Key
502	processor_permission_denied	The program isn't approved for this operation at the processor. Send us the request_id

Related

• Operations by card status — which actions are available in each state
• Card lifecycle