> ## Documentation Index
> Fetch the complete documentation index at: https://ramps-dp-card-pin-management.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Card PINs

> Let cardholders set, change, check, and unblock their card PIN.

Grid supports PIN management for its Lithic-issued virtual cards, including cards used through a digital wallet. Authenticate your backend with a Grid API token authorized to manage cards, and authenticate the cardholder before permitting a PIN change or unblock.

## Choose a PIN-entry flow

For hosted PIN entry, call `POST /cards/{id}/pin/session` with the canonical HTTPS `targetOrigin` of your frontend. Include the scheme, host, and optional port, without a path, trailing slash, credentials, query, or fragment.

Install the `lithic-embed` frontend SDK. Initialize `LithicEmbed` with the returned `environment` (`Environment.SANDBOX` or `Environment.PRODUCTION`), call `pinSetting(sessionToken)`, mount the control, and call its `submit()` method when the cardholder confirms. Follow [Lithic's embed integration guide](https://docs.lithic.com/docs/embedded-card-ui#setting-a-pin) for SDK usage and error handling. The control accepts four digits. The cardholder's plaintext PIN goes directly to Lithic.

The token expires at `expiresAt` and permits one successful submission. Request a new session for another change or after expiration. Treat the token as a secret: never persist, cache, log, or send it to analytics. Use the SDK's submission result to confirm success. An `OK` status alone cannot prove that an already configured PIN was changed.

If you own the PIN-entry UI, call `POST /cards/{id}/pin` with `encryptedPinBlock`. Encrypt immediately in the frontend using [Lithic's encrypted PIN block specification and public key](https://docs.lithic.com/docs/cards#encrypted-pin-block). The same public key serves sandbox and production. Use a fresh random nonce for each request and keep both plaintext and ciphertext out of logs and analytics. Grid forwards the encrypted block without decrypting it. A rejected block returns `400 INVALID_INPUT`.

## Check and recover a PIN

Call `GET /cards/{id}/pin` to read the processor's current `pinStatus` and `pendingCommands`:

| Status    | Next action                                                            |
| --------- | ---------------------------------------------------------------------- |
| `NOT_SET` | Ask the cardholder to set a PIN before a transaction that requires it. |
| `OK`      | The PIN is configured.                                                 |
| `BLOCKED` | Authenticate the cardholder and offer a PIN change or unblock.         |

Three consecutive incorrect attempts block an online PIN. Call `POST /cards/{id}/pin/unblock` to keep the same PIN, or use either PIN-entry flow to choose a new one. Unblocking a PIN that is already `OK` is safe; a card with no PIN returns `409 CONFLICT`.

There is no PIN-reveal API. If the cardholder forgets the PIN, let them set a new one. Setting a PIN does not activate a closed or frozen card or change its spending limits.

`Card.pinStatus` is the last observed processor status. It can be absent before the first observation or for a provider without PIN management; absence does not mean `NOT_SET`. Use the dedicated status endpoint when current state matters.

## Physical card boundary

Grid currently issues virtual cards. Lithic's offline physical-card flow additionally requires a PIN at issuance, before chip manufacture. Subsequent PIN changes and unblocks can remain queued until the chip interacts with a terminal. The status response exposes those commands for accurate reporting, but these endpoints do not enable physical card issuance. See [Lithic's offline PIN guide](https://docs.lithic.com/docs/offline-pin-cards).