Skip to main content
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 endpoint. Here is what each status means: Locking is reversible and canceling is not: a locked card can return to active, but a canceled card can never be reactivated.
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.

​
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 webhook. Build a cardholder-facing unlock path so users are never stranded.

​
Manage PINs

Set and retrieve PINs through the PIN endpoints, 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 for the user.
Lock when in doubt, cancel when confirmed. Locking preserves recovery; canceling forces a reissue.

​
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: 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: 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 endpoint:

​
Handle encrypted card details

Full card number and CVC are encrypted and require a session-ID handshake to retrieve. 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 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

Issue a Card

Issue and manage cards for your users.

Managing a Card's PIN

Set and retrieve PINs securely.

Scoped Cards

Purpose-specific cards with hard spend caps.

Viewing Encrypted Card Details

Retrieve full card details securely.