LIlightsparkdev
Cards

Set a card PIN

Changed on

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.

post/cards/{id}/set-pin

Request

  • Base URL
    https://api.lightspark.com/grid/2025-10-13
  • URL
    https://api.lightspark.com/grid/2025-10-13/cards/{id}/set-pin
  • Auth
    HTTP basic

Request body

encryptedPinBlockstring required

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.

Example request

{
  "encryptedPinBlock": "SGVsbG8sIHRoaXMgaXMgYSBiYXNlNjQtZW5jb2RlZCBjaXBoZXJ0ZXh0Li4u"
}

Response

PIN change accepted.

Changes

  • d996ddfb9d2bRevision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

  • 5abf2bb56bcbRevision changes
    • warning

      added the new CORRIDOR_UNDER_MAINTENANCE enum value to the response property for the response status