Skip to navigation
Cards

Card Controls

Let customers lock a card, set spending controls, report a lost card, and add travel notices.
View as Markdown

Overview

Card Controls put customers in charge of their own cards. With a single API you can let them instantly lock a misplaced card, set spending limits by category, add a travel notice, or report a card lost or stolen and order a replacement.

These actions require the cards:manage scope so customers explicitly consent to your app making changes on their behalf.

What you can do

Lock & unlock

Instantly freeze a card the customer has misplaced, then unlock it when it turns up.

Spending controls

Set per-category or per-transaction limits, or block categories like ATM or international.

Travel notices

Let customers tell Citi where and when they’re traveling to avoid declined transactions.

Report lost or stolen

Close a compromised card and order a replacement in one step.

Lock a card

1

Authenticate

Obtain an access token with the cards:manage scope.

2

Send the control update

Call the endpoint with the cardRef and the desired state.

3

Confirm to the customer

The response returns the updated status — reflect it in your UI immediately.

{
  "cardRef": "card_44127",
  "action": "LOCK",
  "status": "LOCKED",
  "effectiveAt": "2026-04-23T14:40:00Z"
}

Locking is instant and reversible. A locked card declines new purchases but still allows recurring payments the customer has already set up, so subscriptions aren’t disrupted.

Add a travel notice

{
  "cardRef": "card_44127",
  "travelNotice": {
    "destinations": ["ES", "PT"],
    "startDate": "2026-06-01",
    "endDate": "2026-06-14"
  }
}

Reporting a card lost or stolen is permanent — the card is closed and cannot be reactivated. Always confirm the customer’s intent before calling this action.

Security requirements

Control actions require an OAuth 2.0 access token with the cards:manage scope. See the Authentication guide.