> ## Documentation Index > Fetch the complete documentation index at: https://docs.spritz.finance/llms.txt > Use this file to discover all available pages before exploring further. # Update card PIN > Updates the card PIN. **PIN Block Format (ISO 9564-1 Format 2):** The PIN must be formatted as a 16-character PIN block before encryption: - Byte 0: Control field (`2` indicates Format 2) - Byte 1: PIN length in hexadecimal (4-12) - Bytes 2-(1+N): The actual PIN digits - Remaining bytes: Padding (`F`) **Example:** A 4-digit PIN "5678" would be encoded as: `245678FFFFFFFFFF` **Formatting the PIN block:** ``` const pinBlock = `2${pinLength.toString(16)}${pin}${'F'.repeat(14 - pinLength)}`; ``` **Encryption:** 1. Generate a random AES-128 key 2. Encrypt the PIN block using AES-128-GCM with the random key 3. RSA-encrypt the AES key using the server's public key 4. Send the RSA-encrypted key as `encryptedKey` and the AES-encrypted PIN block as `encryptedPin` **Validation:** - PIN must be 4-12 digits - Weak PINs (repeating like 1111, sequential like 1234) are rejected ## OpenAPI ````yaml https://platform.spritz.finance/openapi.json post /v1/cards/{cardId}/update_pin openapi: 3.0.3 info: title: Spritz Finance API version: 1.0.0 description: API for the Spritz Finance platform with RFC 9457 error handling servers: - url: https://platform.spritz.finance description: Production - url: https://sandbox.spritz.finance description: Sandbox security: [] tags: - name: Users description: User management endpoints - name: Bank Accounts description: Manage bank accounts for off-ramp destinations - name: Bills description: Manage bill pay accounts - name: Cards description: Spritz-issued debit cards - name: Auto-Ramp Accounts description: Virtual bank accounts that automatically convert fiat deposits to crypto - name: Spritz App description: >- Endpoints used by the Spritz app and internal SDKs. Excluded from the public partner spec. paths: /v1/cards/{cardId}/update_pin: post: tags: - Cards summary: Update card PIN description: >- Updates the card PIN. **PIN Block Format (ISO 9564-1 Format 2):** The PIN must be formatted as a 16-character PIN block before encryption: - Byte 0: Control field (`2` indicates Format 2) - Byte 1: PIN length in hexadecimal (4-12) - Bytes 2-(1+N): The actual PIN digits - Remaining bytes: Padding (`F`) **Example:** A 4-digit PIN "5678" would be encoded as: `245678FFFFFFFFFF` **Formatting the PIN block:** ``` const pinBlock = `2${pinLength.toString(16)}${pin}${'F'.repeat(14 - pinLength)}`; ``` **Encryption:** 1. Generate a random AES-128 key 2. Encrypt the PIN block using AES-128-GCM with the random key 3. RSA-encrypt the AES key using the server's public key 4. Send the RSA-encrypted key as `encryptedKey` and the AES-encrypted PIN block as `encryptedPin` **Validation:** - PIN must be 4-12 digits - Weak PINs (repeating like 1111, sequential like 1234) are rejected operationId: postV1CardsByCardIdUpdate_pin parameters: - name: cardId in: path required: true schema: minLength: 1 description: The id of the card whose pin is being updated type: string requestBody: required: true content: application/json: schema: type: object properties: encryptedKey: minLength: 1 description: >- Base64-encoded RSA-encrypted AES-128 key used for PIN encryption type: string encryptedPin: description: >- AES-128-GCM encrypted PIN block. The plaintext must be an ISO 9564-1 Format 2 PIN block. type: object properties: iv: minLength: 1 description: >- Base64-encoded initialization vector for AES-GCM decryption type: string data: minLength: 1 description: Base64-encoded AES-GCM encrypted PIN block type: string required: - iv - data required: - encryptedKey - encryptedPin application/x-www-form-urlencoded: schema: type: object properties: encryptedKey: minLength: 1 description: >- Base64-encoded RSA-encrypted AES-128 key used for PIN encryption type: string encryptedPin: description: >- AES-128-GCM encrypted PIN block. The plaintext must be an ISO 9564-1 Format 2 PIN block. type: object properties: iv: minLength: 1 description: >- Base64-encoded initialization vector for AES-GCM decryption type: string data: minLength: 1 description: Base64-encoded AES-GCM encrypted PIN block type: string required: - iv - data required: - encryptedKey - encryptedPin multipart/form-data: schema: type: object properties: encryptedKey: minLength: 1 description: >- Base64-encoded RSA-encrypted AES-128 key used for PIN encryption type: string encryptedPin: description: >- AES-128-GCM encrypted PIN block. The plaintext must be an ISO 9564-1 Format 2 PIN block. type: object properties: iv: minLength: 1 description: >- Base64-encoded initialization vector for AES-GCM decryption type: string data: minLength: 1 description: Base64-encoded AES-GCM encrypted PIN block type: string required: - iv - data required: - encryptedKey - encryptedPin responses: '200': description: Response for status 200 content: application/json: schema: type: object properties: success: type: boolean required: - success '401': description: Response for status 401 content: application/json: schema: type: object properties: type: default: about:blank description: A URI reference that identifies the problem type type: string example: urn:problem-type:auth:unauthorized title: description: A short, human-readable summary of the problem type type: string example: Unauthorized status: description: The HTTP status code type: number example: 401 detail: description: A human-readable explanation specific to this occurrence type: string example: Bearer token required instance: description: A URI reference that identifies the specific occurrence type: string realm: description: The authentication realm type: string example: API scope: description: The required scope for this resource type: string example: read:users required: - title - status additionalProperties: false '404': description: Response for status 404 content: application/json: schema: type: object properties: type: default: about:blank description: A URI reference that identifies the problem type type: string title: description: A short, human-readable summary of the problem type type: string status: description: The HTTP status code type: number example: 404 detail: description: A human-readable explanation specific to this occurrence type: string instance: description: A URI reference that identifies the specific occurrence type: string resourceType: description: The type of resource that was not found type: string example: user resourceId: description: The identifier of the resource that was not found type: string required: - title - status - resourceType - resourceId additionalProperties: false '500': description: Response for status 500 content: application/json: schema: type: object properties: type: default: about:blank description: A URI reference that identifies the problem type type: string example: urn:problem-type:auth:unauthorized title: description: A short, human-readable summary of the problem type type: string example: Unauthorized status: description: The HTTP status code type: number example: 400 detail: description: A human-readable explanation specific to this occurrence type: string instance: description: A URI reference that identifies the specific occurrence type: string example: /errors/1234567890 code: description: >- Machine-readable cause, present when exactly one thing failed. Branch on this, never on `detail`, which is human-facing copy and may change. For deposit limits the vocabulary matches the `reason` values the limits API returns pre-flight. type: string example: transaction_limit field: description: The offending request field, present alongside `code`. type: string example: amountUsd retryable: description: >- Whether retrying the same request later may succeed without changing its inputs. type: boolean example: true required: - title - status additionalProperties: false security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Cognito JWT token for regular user authentication ````