Skip to main content
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 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. 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: 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.