Set a card PIN
Set or replace the card’s online PIN using a block encrypted in your client with the published PIN encryption public key. Grid cannot decrypt the block and never stores or logs PIN material.
Use this when you operate your own PIN-entry UI. For a hosted PIN-entry iframe, use GET /cards/{id}/pin-entry-url — the two are alternatives, and a card may use either at any time.
Setting a PIN clears a BLOCKED PIN, so a cardholder locked out by incorrect attempts can recover by choosing a new PIN without a separate unblock. Read GET /cards/{id} for the resulting status. Grid supports online PINs only; offline PIN cards are not supported.
Every call is audit-logged with the requesting actor.
Authorizations
API token authentication using format <api token id>:<api client secret>
Path Parameters
System-generated unique card identifier
Body
The cardholder's PIN, encrypted in your client before calling Grid. Use the PIN encryption public key for both sandbox and production. Grid cannot decrypt the block and never stores or logs PIN material.
Build it in the client, immediately after PIN entry, so the PIN never reaches your servers either: serialize {"nonce": <random integer>, "pin": "<4-digit PIN>"} as JSON, encode it as UTF-8, encrypt it using the public key above, and base64-encode the ciphertext. Generate a fresh cryptographically random integer nonce for each request to prevent replay. Preserve the PIN as a string, including leading zeros. Send the resulting base64 string as encryptedPinBlock. Never send the plaintext PIN or the unencrypted JSON to Grid. Keep ciphertext out of logs, storage, and analytics too.
A rejected block returns 400 INVALID_INPUT. Check the payload, encoding, and public key, then create a new block with a fresh nonce. See Card PINs for the complete PIN-entry flows.
16 - 1024"SGVsbG8sIHRoaXMgaXMgYSBiYXNlNjQtZW5jb2RlZCBjaXBoZXJ0ZXh0Li4u"
Response
PIN change accepted.