> ## Documentation Index
> Fetch the complete documentation index at: https://rain-sandbox-trial.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Card Management Best Practices

> Recommended practices for locking cards, managing PINs, handling lost or stolen cards, applying spend controls, and staying in sync with Rain.

Managing a card well comes down to a few recurring decisions: when to lock versus cancel, how to handle PINs and card details without exposing them, and when to trust a webhook over your own API call. Every card in Rain has one of four statuses, and most management actions move a card between them with the [Update a card](/reference/cards/update-a-card) endpoint. Here is what each status means:

| Status         | Meaning                                                                    |
| -------------- | -------------------------------------------------------------------------- |
| `notActivated` | Issued but not yet usable (typically a physical card awaiting activation). |
| `active`       | Usable for authorizations.                                                 |
| `locked`       | Temporarily blocked. Reversible. Set back to `active` to unlock.           |
| `canceled`     | Permanently disabled. Cannot be reactivated.                               |

Locking is reversible and canceling is not: a `locked` card can return to `active`, but a `canceled` card can never be reactivated.

<Warning>
  **Security best practices:**

  * Never store decrypted card details or PINs.
  * Only request full card details or a PIN when absolutely necessary.
  * Always use the latest encryption libraries.
</Warning>

## Lock a card

Set a card's status to `locked` to **temporarily** block all new authorizations. Locking is the right move for a misplaced card, a suspected but unconfirmed compromise, or a cardholder who wants to pause spend. Set the status back to `active` to unlock.

A lock is fully reversible and keeps the card, its number, and its digital-wallet tokens intact. Prefer locking over canceling whenever the card might return to use.

Rain automatically locks a card after too many incorrect PIN attempts, with `statusChangeReason: pin_limit_exceeded` on the [`card.updated`](/changelog/webhooks/v1/card/updated) webhook. Build a cardholder-facing unlock path so users are never stranded.

## Manage PINs

Set and retrieve PINs through the [PIN endpoints](/docs/managing-a-cards-pin), and always encrypt the PIN with a client session key before you transmit it. Never send or store a PIN in plaintext.

Enforce PIN quality before you submit:

* Length between **4 and 12 digits**.
* No simple sequences, such as `1234` or `0000`.
* No repeated digits, such as `1111`.

Retrieve a PIN only when the cardholder explicitly needs it, and never persist the decrypted value.

## Handle lost or stolen cards

For a confirmed lost or stolen card, set its status to `canceled`. Cancellation is **permanent**. A canceled card cannot be reactivated.

To get the cardholder spending again, [create a new card](/reference/cards/create-a-card-for-a-user) for the user.

<Info>
  Lock when in doubt, cancel when confirmed. Locking preserves recovery; canceling forces a reissue.
</Info>

## Apply spend controls

Prevent misuse before it happens rather than reacting to it:

* **Spending limits:** Set an `amount` and `frequency` (`per24HourPeriod`, `per7DayPeriod`, `per30DayPeriod`, `perYearPeriod`, `allTime`, or `perAuthorization`) on a card to cap exposure.
* **[Scoped cards](/docs/scoped-cards):** For one-off, agent, or purpose-specific spend, issue a scoped virtual card with a hard amount cap, an optional `expiresAt`, and an optional `allowedMccs` merchant-category allow-list to limit blast radius.
* **[Blocked MCCs and merchants](/docs/blocked-mccs-and-merchants):** Rain declines high-risk merchant categories and a maintained merchant blocklist by default, and can block a specific merchant for your program on request.

For example, cap a card's spend per 30-day period with the [Update a card](/reference/cards/update-a-card) endpoint:

```json theme={null}
{
  "limit": {
    "amount": 50000,
    "frequency": "per30DayPeriod"
  }
}
```

## Handle encrypted card details

Full card number and CVC are encrypted and require a session-ID handshake to [retrieve](/docs/viewing-encrypted-card-details). The last four digits and expiry are always available without it. Request full details only when strictly necessary, and never store the decrypted values.

## Stay in sync with webhooks

Subscribe to the [`card.updated`](/changelog/webhooks/v1/card/updated) webhook and treat it as your source of truth for card status. It fires on every lock, unlock, and cancel, on PIN-limit auto-locks, on digital-wallet provisioning, and on changes Rain initiates internally (`statusChangeReason: rain_initiated`).

Reconcile your local card state against this webhook rather than assuming your API call is the only thing that can change a card. That way a Rain-side or processor-side action never leaves your records out of sync.

## What's next

<CardGroup cols={2}>
  <Card title="Issue a Card" icon="credit-card" href="/docs/issuing-cards">
    Issue and manage cards for your users.
  </Card>

  <Card title="Managing a Card's PIN" icon="lock" href="/docs/managing-a-cards-pin">
    Set and retrieve PINs securely.
  </Card>

  <Card title="Scoped Cards" icon="shield-check" href="/docs/scoped-cards">
    Purpose-specific cards with hard spend caps.
  </Card>

  <Card title="Viewing Encrypted Card Details" icon="eye" href="/docs/viewing-encrypted-card-details">
    Retrieve full card details securely.
  </Card>
</CardGroup>